bullswarm 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # bullswarm changelog
 
+## 0.25.2 — event-based watch
+
+- `workflow watch <run> --next` is safe to relaunch after every wake-up: each
+  such exit prints `next: bullswarm workflow watch <id> --next --after <seq>
+  --since <time>`; relaunching with those values replays notable events that
+  landed while no watcher was attached, reports a level at most once, and does
+  not repeat a stall already reported (its recovery line still prints). `--jsonl`
+  objects carry `sequence`.
+
+- `workflow watch` for V2 runs is event-based by default: one attach line,
+  then one line per notable event (action finished/failed/blocked/cancelled,
+  evidence, stage completion, planner turn, stall/recovery, cancellation)
+  and silence while work is merely in progress. `--next` prints no attach
+  line and exits after the first notable event (0 while the run continues or
+  delivered, 1 when it ended without delivering or the kernel is not
+  running). `--stall-after <seconds>` (default 300) reports a silent running
+  agent; `--heartbeat <seconds>` is opt-in for V2 (legacy still defaults to
+  60s). `--jsonl` emits one object per event with a stable `type`. Agent
+  starts, mechanical retries, and steering delivery remain `--verbose` only.
+  `--once` and legacy (non-V2) transition-plus-heartbeat output are
+  unchanged.
+
 ## 0.25.0 — shared programs that finish with the graph
 
 - New goal workflows share the target worktree by default. File territories

package/README.md

@@ -302,7 +302,9 @@ The detached response includes a short ID and exact observation commands:
 
 ```bash
 bullswarm workflow runs show <shortId>
-bullswarm workflow watch <shortId>        # low-noise live progress + terminal timing
+bullswarm workflow watch <shortId>        # V2: attach, then one line per notable event
+bullswarm workflow watch <shortId> --next # print the next notable event and exit
+                                          # relaunch with the --after/--since it prints
 bullswarm workflow                         # unified human workflow home
 bullswarm workflow tui <shortId>          # jump directly to one run timeline
 bullswarm workflow tui --json <shortId>
@@ -482,20 +484,45 @@ auditing completed runs.
 
 ### Live workflow dashboard
 
-For ordinary observation, use the non-interactive watcher. Human output is one
-compact aggregate line per semantic change and a 60-second heartbeat while
-otherwise quiet. Each line reports status/location, events and agent actions
-captured since the preceding sample, and quiet duration. It does not repeat
-command or response excerpts. Use `--verbose` for the detailed per-agent and
-last-action view. Compact terminal output reports the overall attempt count and
-elapsed time; `--verbose` includes every attempt's agent/model, outcome, and
-tokens. This keeps agent monitoring cheap while retaining a drill-down path.
+For ordinary observation, use the non-interactive watcher. For V2 runs it
+prints one attach line, then one line per notable event as it happens
+(action finished/failed/blocked/cancelled, evidence, stage completion,
+planner turn, stall/recovery, cancellation, and the existing pause and
+terminal `outcome:` / `next:` lines) and stays silent while work is merely
+in progress. Agent starts, mechanical retries, and steering delivery print
+only with `--verbose`. The periodic heartbeat is off unless you pass
+`--heartbeat <seconds>`; `--stall-after <seconds>` (default 300) reports a
+running agent that has gone silent. `--next` prints no attach line and
+exits after the first notable event so a background terminal can wake the
+caller; relaunch until the outcome line reports a pause or a terminal
+status (exit 0 while the run continues or delivered, 1 when it ended
+without delivering or the kernel is not running). Every `--next` exit that
+leaves the run going ends with a relaunch line —
+`next: bullswarm workflow watch <shortId> --next --after <sequence> --since <iso>` —
+and the relaunch should copy those two values verbatim: `--after` starts
+from the durable event sequence the previous watcher consumed, so events
+committed while nothing was attached are printed instead of skipped, and
+`--since` is that watcher's exit time, so an agent whose silence it already
+reported does not produce a duplicate stall line (its recovery still
+prints). `--jsonl` emits one JSON object per notable event with a stable
+`type` (`attach`, `action.finished`,
+`evidence.recorded`, `stage.completed`, `planner.finished`, `agent.stalled`,
+`agent.recovered`, `cancellation.requested`, `paused`, `finished`,
+`interrupted`, and with `--verbose` `action.started`, `attempt.retrying`,
+`steering.delivered`); in that mode the relaunch line is not printed and
+every object instead carries the `sequence` it was emitted at, which is the
+value to pass as `--after`. `--once` still prints one current snapshot. Legacy
+(non-V2) runs keep the compact transition-plus-heartbeat stream unchanged.
 
 ```bash
 bullswarm workflow watch <shortId>
-bullswarm workflow watch <shortId> --jsonl       # automation-friendly stream
+bullswarm workflow watch <shortId> --next        # next notable event, then exit
+bullswarm workflow watch <shortId> --next --after 42 --since 2026-09-08T10:15:00.000Z
+                                                 # the relaunch: values copied from the previous next: line
+bullswarm workflow watch <shortId> --jsonl       # one JSON object per event
 bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
-bullswarm workflow watch <shortId> --verbose     # detailed agent/action view
+bullswarm workflow watch <shortId> --verbose     # started / retry / steering too
+bullswarm workflow watch <shortId> --stall-after 120 --heartbeat 30
 ```
 
 `workflow tui` is the interactive, Claude-style `/workflows` view. For an