bullswarm 0.25.1 → 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -109,11 +109,22 @@ validate again. A valid launch detaches and returns `shortId`; report it.
 ## 3. Observe and judge the result
 
 ```bash
-bullswarm workflow watch <shortId>
+bullswarm workflow watch <shortId> --next
+bullswarm workflow watch <shortId> --next --after <sequence> --since <iso-timestamp>
 bullswarm workflow runs result <shortId> --json
 ```
 
 When the user asked you to complete the work, follow the run through its result.
+Launch `bullswarm workflow watch <shortId> --next` in a background terminal, act
+on the printed event when it exits, and relaunch until the outcome line reports
+a pause or a terminal status. Each exit that leaves the run going ends with
+`next: bullswarm workflow watch <shortId> --next --after <sequence> --since <iso>`:
+relaunch with exactly those two values, so events committed while you were
+acting are printed instead of skipped and a stall you already saw does not
+report twice. In `--jsonl` mode there is no such line — take `--after` from the
+`sequence` field of the last object. V2 watch prints one line per notable event
+and stays silent while work is merely in progress; `--heartbeat` is opt-in and
+`--stall-after` (default 300s) reports a silent running agent.
 `watch` also exits at a durable planning pause; that is not completion.
 
 Read action outputs and actual artifacts, and probe important edge cases yourself.

package/skill/references/operations.md

@@ -30,6 +30,8 @@ deprecated alias for `--orchestrator <pool> --orchestrator-strict`.
 Observe and consume:
 
 ```bash
+bullswarm workflow watch <shortId> --next
+bullswarm workflow watch <shortId> --next --after <sequence> --since <iso-timestamp>
 bullswarm workflow watch <shortId>
 bullswarm workflow tui <shortId>
 bullswarm workflow tui --json <shortId>
@@ -37,7 +39,19 @@ bullswarm workflow events --json <shortId> --after 0
 bullswarm workflow runs result <shortId> --json
 ```
 
-The default watch is a compact heartbeat. Use `--verbose` only for diagnosis.
+V2 watch prints one attach line, then one line per notable event, and stays
+silent while work is merely in progress. Launch
+`bullswarm workflow watch <shortId> --next` in a background terminal, act on the
+printed event when it exits, and relaunch until the outcome line reports a
+pause or a terminal status. Every `--next` exit that leaves the run going ends
+with `next: bullswarm workflow watch <shortId> --next --after <sequence> --since <iso>`;
+relaunch with those exact `--after` and `--since` values so events committed
+while no watcher was attached are printed rather than skipped and an
+already-reported stall does not fire again (its recovery still prints). With
+`--jsonl` that line is absent: take `--after` from the `sequence` field carried
+by every emitted object. `--heartbeat` is opt-in for V2 (legacy still
+defaults to 60s). `--stall-after` (default 300s) reports a silent running
+agent. Use `--verbose` only for diagnosis.
 The result command is the stable delivery/verification envelope; do not scrape
 task files or assume the last provider response is the deliverable.
 

package/src/help.js

@@ -987,25 +987,39 @@ const workflowTuiText = rich({
 });
 
 const workflowWatchText = rich({
-  usage: 'bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once] [--verbose]',
-  purpose: "Follow one run's progress with low noise: prints only semantic changes plus a "
-    + 'periodic heartbeat, then a timing breakdown at completion. Each line shows two silences: '
-    + '"quiet" is time since the last durable workflow event, "agent output … ago" is time since a '
-    + 'live agent last produced output, so a thinking agent and a dead one look different. Distinct from the '
+  usage: 'bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--stall-after <seconds>] [--next [--after <sequence>] [--since <iso-timestamp>]] [--jsonl] [--once] [--verbose]',
+  purpose: "Follow one V2 run by printing one attach line, then one line per notable event "
+    + '(action finished/failed/blocked/cancelled, evidence, stage completion, stall/recovery, planning, '
+    + 'cancellation) and staying silent while work is merely in progress. `--next` prints no attach '
+    + 'line and returns after the first notable event, or immediately at a pause or terminal status. '
+    + 'Every `--next` exit that leaves the run going prints a `next:` relaunch line carrying `--after` and '
+    + '`--since`; pass those two values back on the relaunch so events committed while no watcher was '
+    + 'attached are printed instead of skipped and an already-reported stall does not fire again. '
+    + '`--heartbeat` is opt-in for V2; legacy runs keep the historical heartbeat stream. Distinct from the '
     + 'full-screen tui and the machine-oriented events replay.',
   args: [{ name: '<runId>', desc: 'shortId or runId' }],
   options: [
     { flag: '--interval <seconds>', desc: 'poll interval while following', default: '2' },
-    { flag: '--heartbeat <seconds>', desc: 'max gap between heartbeat lines when nothing has changed', default: '60' },
-    { flag: '--jsonl', desc: 'emit one JSON object per line instead of human text', default: 'off (human text)' },
+    { flag: '--heartbeat <seconds>', desc: 'print a periodic heartbeat line when nothing has changed; opt-in for V2, must be >= 1', default: 'off for V2, 60 for legacy' },
+    { flag: '--stall-after <seconds>', desc: 'report a running agent as silent after this many seconds without activity; must be >= 1', default: '300' },
+    { flag: '--next', desc: 'print no attach line; exit after the first poll that printed a notable event, or immediately at a pause or terminal status', default: 'off (follows until terminal or pause)' },
+    { flag: '--after <sequence>', desc: 'start from this durable event sequence instead of the current high-water mark, so events committed since the previous watcher exited are printed; use the value from the previous `next:` line (in --jsonl, the `sequence` field of the last object)', default: 'attach at the current high-water mark' },
+    { flag: '--since <iso-timestamp>', desc: 'the previous watcher\'s exit time; a running agent already silent at attach is reported only if its silence crossed --stall-after at or after this time, so no duplicate stall line prints (its recovery still does); use the value from the previous `next:` line', default: 'report every agent silent past --stall-after at attach' },
+    { flag: '--jsonl', desc: 'emit one JSON object per line instead of human text; every object carries the `sequence` it was emitted at, and the `next:` relaunch line is not printed', default: 'off (human text)' },
     { flag: '--once', desc: 'print a single current snapshot and exit immediately instead of following', default: 'off (follows until terminal)' },
-    { flag: '--verbose', desc: 'include per-agent action detail lines', default: 'off (compact)' },
+    { flag: '--verbose', desc: 'include started, retry, and steering-delivered lines (V2) and per-agent action detail (legacy)', default: 'off (compact)' },
   ],
   safety: [
     'read-only — polls durable state/events on a timer; writes nothing',
     'exits 0 if the run reaches a delivered status (or on --once), 1 if it reaches a non-delivered terminal status',
+    '--next exits 0 while the run continues or when it delivered, 1 when it ended without delivering or the kernel is not running',
+    'for a V2 run, a --next exit that leaves the run going ends with `next: bullswarm workflow watch <shortId> --next --after <sequence> --since <iso>`; pause, terminal and interrupted exits keep their own outcome/next lines',
+  ],
+  examples: [
+    { cmd: 'bullswarm workflow watch ab12cd --next', note: 'print the next notable event and exit; relaunch until outcome reports a pause or a terminal status' },
+    { cmd: 'bullswarm workflow watch ab12cd --next --after 42 --since 2026-09-08T10:15:00.000Z', note: 'the relaunch: copy both values from the `next:` line the previous exit printed' },
+    { cmd: 'bullswarm workflow watch ab12cd --stall-after 120 --heartbeat 30' },
   ],
-  examples: [{ cmd: 'bullswarm workflow watch ab12cd --heartbeat 30' }],
   next: 'bullswarm workflow runs result <runId> --json once it finishes, or bullswarm workflow tui <runId> for the interactive view.',
 });
 

package/src/workflow/cli.js

@@ -1252,23 +1252,56 @@ function wfEvents(opts) {
 }
 
 async function wfWatch(opts) {
+  // A value flag with no value (--heartbeat, --interval, --stall-after,
+  // --after, --since) is a usage error, not a silent fall back to the default.
+  const flagError = flagErrors(opts, ['workflow', 'watch']);
+  if (flagError != null) return flagError;
   const token = opts.rest[0];
   if (!token) {
     console.error(`usage: ${usageLine(['workflow', 'watch'])}`);
     return 2;
   }
   const intervalSec = Number(opts.interval ?? 2);
-  const heartbeatSec = Number(opts.heartbeat ?? 60);
+  // --heartbeat is now opt-in: absent means no periodic line for a V2 run and
+  // the historical 60s for a legacy one.
+  const heartbeatSec = opts.heartbeat == null ? null : Number(opts.heartbeat);
   if (!Number.isFinite(intervalSec) || intervalSec < 0.1 ||
-      !Number.isFinite(heartbeatSec) || heartbeatSec < 1) {
+      (heartbeatSec != null && (!Number.isFinite(heartbeatSec) || heartbeatSec < 1))) {
     console.error('✗ --interval must be >= 0.1 seconds and --heartbeat must be >= 1 second');
     return 2;
   }
+  const stallAfterSec = Number(opts['stall-after'] ?? 300);
+  if (!Number.isFinite(stallAfterSec) || stallAfterSec < 1) {
+    console.error('✗ --stall-after must be >= 1 second');
+    return 2;
+  }
+  // Continuity for a relaunched watcher: both values come from the `next:` line
+  // the previous --next exit printed.
+  let afterSequence = null;
+  if (opts.after != null) {
+    afterSequence = Number(opts.after);
+    if (!Number.isInteger(afterSequence) || afterSequence < 0) {
+      console.error('✗ --after must be a non-negative integer');
+      return 2;
+    }
+  }
+  let sinceMs = null;
+  if (opts.since != null) {
+    sinceMs = Date.parse(opts.since);
+    if (!Number.isFinite(sinceMs)) {
+      console.error('✗ --since must be an ISO 8601 timestamp');
+      return 2;
+    }
+  }
   try {
     return await runWorkflowWatch(BULLSWARM_DIR(), token, {
       intervalMs: intervalSec * 1000,
-      heartbeatMs: heartbeatSec * 1000,
+      heartbeatMs: heartbeatSec == null ? null : heartbeatSec * 1000,
+      stallAfterMs: stallAfterSec * 1000,
+      afterSequence,
+      sinceMs,
       once: opts.once === true,
+      next: opts.next === true,
       jsonl: opts.jsonl === true,
       verbose: opts.verbose === true,
     });
@@ -1375,7 +1408,7 @@ function parseFlags(argv) {
     'worker-pool', 'worker-model', 'request', 'run-id',
     'suggested-plan', 'planner', 'program', 'summary', 'reason',
     'max-agents', 'max-expansion-rounds', 'max-actions', 'concurrency',
-    'retry-attempts', 'interval', 'heartbeat', 'message',
+    'retry-attempts', 'interval', 'heartbeat', 'stall-after', 'since', 'message',
   ]);
   // A value flag with no value (end of argv, or the next token is another
   // flag) is a usage error, never a silent default: a bare --program must not

package/src/workflow/watch-cli.js

@@ -1,7 +1,8 @@
 import { withV2Cancellation } from './v2-cancellation.js';
 // Low-noise, non-interactive workflow progress watcher.
-// Prints only semantic changes plus a periodic heartbeat, then a timing
-// breakdown at terminal status. This is intentionally distinct from the
+// V2 runs are event-based: one attach line, then one line per notable event
+// and silence while work is merely in progress. Legacy runs keep their
+// transition-plus-heartbeat output. This is intentionally distinct from the
 // full-screen TUI and the machine-oriented events replay API.
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -10,6 +11,7 @@ import { resolveRunId, v2RunnerLiveness } from './short-id.js';
 import { readSteering } from './steering.js';
 import { hasPassingRequirementEvidence, isProgramWorkflow } from './execution-policy.js';
 import { readEvents } from './events.js';
+import { presentationStageStatus, projectV2DependencyStages } from './v2-presentation.js';
 import { isDeliveredWorkflowStatus, isTerminalWorkflowStatus } from './status.js';
 
 function readJson(path) {
@@ -283,31 +285,388 @@ async function resolveRunWithGrace(bullswarmDir, token, waitForRunMs, intervalMs
   }
 }
 
+// ── Event mode ──────────────────────────────────────────────────────────────
+// For V2 runs the watcher is event-based: one attach line, then one line per
+// notable event and nothing at all while work is merely in progress. Progress
+// polling still happens (state.json plus events.jsonl), but a poll that
+// carries no notable event prints nothing.
+
+export const DEFAULT_STALL_AFTER_MS = 300_000;
+
+const V2_SCHEMA = 'bullswarm.workflow.state.v2';
+
+function isV2State(state) {
+  return state?.schemaVersion === V2_SCHEMA;
+}
+
+// Every agent attempt in one list with a stable key, so a silent episode can
+// be reported exactly once and recovered exactly once. Worker attempts carry
+// their own id; planner and scout attempts are keyed by their ordinal.
+function v2AttemptRecords(state) {
+  const records = [];
+  for (const attempt of state.preflight?.scout?.attempts ?? []) {
+    records.push({ key: `preflight-scout-${attempt.ordinal}`, actionId: 'preflight-scout', attempt });
+  }
+  for (const attempt of state.planner?.attempts ?? []) {
+    records.push({ key: `workflow-planner-${attempt.ordinal}`, actionId: 'workflow-planner', attempt });
+  }
+  for (const attempt of state.attempts ?? []) {
+    records.push({ key: attempt.id ?? `${attempt.actionId}-${attempt.ordinal}`, actionId: attempt.actionId, attempt });
+  }
+  return records;
+}
+
+// Epoch ms of the most recent sign of life for one attempt: output bytes, a
+// provider stream event, or (before either) its start.
+function attemptActivityAt(attempt) {
+  const latest = Math.max(
+    Date.parse(attempt.lastActivityAt ?? '') || 0,
+    Date.parse(attempt.lastEventAt ?? '') || 0,
+    Date.parse(attempt.startedAt ?? '') || 0,
+  );
+  return latest || null;
+}
+
+// Program runs group actions into dependency levels projected from the program
+// itself; verified runs carry durable presentation stages. Both are rendered
+// as one "stage completed" line, and each stage is reported once.
+function v2Stages(state) {
+  const stages = isProgramWorkflow(state)
+    ? projectV2DependencyStages(state)
+    : state.presentation?.stages ?? [];
+  return stages.map((stage) => ({ stage, status: presentationStageStatus(stage, state.actions ?? []) }));
+}
+
+function actionDurationSec(runtime, event, nowMs) {
+  if (!runtime?.startedAt) return null;
+  return secondsBetween(runtime.startedAt, runtime.finishedAt ?? event?.committedAt ?? new Date(nowMs).toISOString());
+}
+
+function attemptOrdinal(state, attemptId) {
+  const known = (state.attempts ?? []).find((attempt) => attempt.id === attemptId)?.ordinal;
+  if (Number.isFinite(known)) return known;
+  const trailing = Number(/-(\d+)$/.exec(String(attemptId ?? ''))?.[1]);
+  return Number.isFinite(trailing) ? trailing : null;
+}
+
+// Carried across polls: which stages have already been reported, which
+// attempts are in a reported silent episode, and which actions have a failed
+// attempt whose replacement would be a mechanical retry.
+//
+// A relaunched watcher (--after/--since) seeds the same memory from continuity
+// inputs instead of from the live state alone: replayedEvents are the durable
+// events this launch is about to print, and sinceMs is when the previous
+// watcher exited.
+export function initialWatchMemory(state, {
+  replayedEvents = [],
+  sinceMs = null,
+  stallAfterMs = DEFAULT_STALL_AFTER_MS,
+  nowMs = Date.now(),
+} = {}) {
+  // A stage whose action finished among the replayed events is exactly the news
+  // this relaunch exists to deliver, so it must not be pre-marked as reported
+  // even though it is already terminal on disk. A stage that was terminal
+  // before the cursor stays silent.
+  const replayedActions = new Set(replayedEvents
+    .filter((event) => event.type === 'action.finished' || event.type === 'evidence.recorded')
+    .map((event) => event.payload?.actionId)
+    .filter(Boolean));
+  const done = isV2State(state)
+    ? v2Stages(state)
+      .filter(({ stage, status }) => (status.terminal || stage.completedAt)
+        && !(stage.actionIds ?? []).some((id) => replayedActions.has(id)))
+      .map(({ stage }) => stage.id)
+    : [];
+  const stalled = new Map();
+  // An agent whose silence crossed the stall threshold before the previous
+  // watcher exited was already reported by it: remember the episode so this
+  // launch prints no duplicate stall line, while its recovery still prints.
+  if (sinceMs != null && isV2State(state)) {
+    for (const { key, attempt } of v2AttemptRecords(state)) {
+      if (attempt.status !== 'running') continue;
+      const activityAt = attemptActivityAt(attempt);
+      if (activityAt == null) continue;
+      if (nowMs - activityAt < stallAfterMs) continue;
+      if (activityAt + stallAfterMs >= sinceMs) continue;
+      stalled.set(key, { since: activityAt });
+    }
+  }
+  return { stages: new Set(done), stalled, retry: new Map() };
+}
+
+/**
+ * Turn the durable events committed since the last poll, plus the current
+ * state, into the notable events a watcher should print. Pure: the carried
+ * memory is never mutated, a fresh one is returned alongside the events.
+ */
+export function notableWatchEvents({
+  events = [],
+  state,
+  memory = null,
+  verbose = false,
+  nowMs = Date.now(),
+  stallAfterMs = DEFAULT_STALL_AFTER_MS,
+} = {}) {
+  const carried = memory ?? initialWatchMemory(state);
+  const stages = new Set(carried.stages);
+  const stalled = new Map(carried.stalled);
+  const retry = new Map(carried.retry);
+  const notable = [];
+
+  const onAttemptStarted = (actionId, payload, ordinal) => {
+    // A new attempt after a failed one is the dispatcher retrying mechanically.
+    if (retry.has(actionId)) {
+      if (verbose) notable.push({ type: 'attempt.retrying', actionId, failureKind: retry.get(actionId) });
+      retry.delete(actionId);
+    }
+    if (verbose) {
+      notable.push({
+        type: 'action.started', actionId,
+        pool: payload.pool ?? null, model: payload.model ?? null, attempt: ordinal,
+      });
+    }
+  };
+  const onAttemptFinished = (actionId, payload) => {
+    if (payload.status === 'succeeded') retry.delete(actionId);
+    else retry.set(actionId, payload.failureKind ?? payload.status ?? 'unknown');
+  };
+
+  for (const event of events) {
+    const payload = event.payload ?? {};
+    switch (event.type) {
+      case 'action.finished': {
+        const runtime = (state.actions ?? []).find((item) => item.id === payload.actionId) ?? null;
+        const status = payload.status ?? runtime?.status ?? 'finished';
+        retry.delete(payload.actionId);
+        notable.push({
+          type: 'action.finished',
+          actionId: payload.actionId,
+          status,
+          failureKind: payload.failureKind ?? runtime?.lastFailure?.kind ?? null,
+          why: payload.why ?? runtime?.lastFailure?.message
+            ?? (payload.outOfScope ?? payload.paths)?.join(', ') ?? null,
+          durationSec: status === 'blocked' ? null : actionDurationSec(runtime, event, nowMs),
+        });
+        break;
+      }
+      case 'evidence.recorded': {
+        const requirementIds = payload.requirements ?? [];
+        notable.push({
+          type: 'evidence.recorded',
+          actionId: payload.actionId,
+          requirements: requirementIds.map((id) => ({
+            id,
+            status: payload.statuses?.[id] ?? state.ledger?.requirements?.[id]?.status ?? 'unknown',
+          })),
+        });
+        break;
+      }
+      case 'presentation.stage_completed': {
+        if (stages.has(payload.stageId)) break;
+        stages.add(payload.stageId);
+        notable.push({
+          type: 'stage.completed',
+          stageId: payload.stageId ?? null,
+          label: payload.label ?? payload.stageId ?? 'stage',
+          status: payload.status === 'completed' ? 'completed' : 'ended',
+          completed: payload.completed ?? null,
+          total: payload.total ?? null,
+        });
+        break;
+      }
+      case 'planner.finished': {
+        notable.push(payload.ok === false
+          ? {
+            type: 'planner.finished', ok: false, turn: payload.turn ?? null,
+            failureKind: payload.failureKind ?? null,
+            why: payload.why ?? payload.failureKind ?? 'no reason recorded',
+          }
+          : {
+            type: 'planner.finished', ok: true, turn: payload.turn ?? null,
+            kind: payload.kind ?? null, summary: payload.summary ?? null,
+          });
+        break;
+      }
+      case 'workflow.cancellation_requested':
+        notable.push({
+          type: 'cancellation.requested',
+          reason: payload.reason ?? null,
+          source: payload.source ?? null,
+        });
+        break;
+      case 'attempt.started':
+        onAttemptStarted(payload.actionId, payload, attemptOrdinal(state, payload.attemptId));
+        break;
+      case 'planner.attempt_started':
+        onAttemptStarted('workflow-planner', payload, payload.ordinal ?? null);
+        break;
+      case 'preflight.scout_attempt_started':
+        onAttemptStarted('preflight-scout', payload, payload.ordinal ?? null);
+        break;
+      case 'attempt.finished':
+        onAttemptFinished(payload.actionId, payload);
+        break;
+      case 'planner.attempt_finished':
+        onAttemptFinished('workflow-planner', payload);
+        break;
+      case 'preflight.scout_attempt_finished':
+        onAttemptFinished('preflight-scout', payload);
+        break;
+      case 'steering.delivered':
+        if (verbose) notable.push({ type: 'steering.delivered', steeringId: payload.steeringId ?? null });
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Program runs commit no durable level-completed event, so a dependency level
+  // that flipped to terminal between polls is detected here instead. A stage
+  // already reported from its durable event is never reported twice.
+  if (isProgramWorkflow(state)) {
+    for (const { stage, status } of v2Stages(state)) {
+      if (!status.terminal || stages.has(stage.id)) continue;
+      stages.add(stage.id);
+      notable.push({
+        type: 'stage.completed',
+        stageId: stage.id,
+        label: stage.label,
+        status: status.successful ? 'completed' : 'ended',
+        completed: status.completed,
+        total: status.total,
+      });
+    }
+  }
+
+  // Silence is measured from the later of the attempt's last output activity,
+  // last agent event and start. A stalled agent is never killed; the line only
+  // says the watcher can no longer see progress.
+  for (const { key, actionId, attempt } of v2AttemptRecords(state)) {
+    const activityAt = attemptActivityAt(attempt);
+    if (attempt.status !== 'running' || activityAt == null) {
+      stalled.delete(key);
+      continue;
+    }
+    const episode = stalled.get(key);
+    if (episode) {
+      if (activityAt > episode.since) {
+        stalled.delete(key);
+        notable.push({
+          type: 'agent.recovered', actionId, attemptId: key,
+          silentSec: Math.max(0, Math.round((activityAt - episode.since) / 1000)),
+        });
+      }
+      continue;
+    }
+    const silentMs = Math.max(0, nowMs - activityAt);
+    if (silentMs < stallAfterMs) continue;
+    stalled.set(key, { since: activityAt });
+    notable.push({
+      type: 'agent.stalled', actionId, attemptId: key,
+      silentSec: Math.round(silentMs / 1000),
+      pool: attempt.pool ?? null, model: attempt.model ?? null,
+    });
+  }
+
+  return { notable, memory: { stages, stalled, retry } };
+}
+
+/** One notable event as one human line. */
+export function renderWatchEvent(event) {
+  switch (event.type) {
+    case 'attach':
+      return `● watching ${event.shortId ?? event.runId} · ${event.status} · ` +
+        `${event.running} running, ${event.waiting} waiting · +${formatDuration(event.elapsedSec)}`;
+    case 'action.finished':
+      if (event.status === 'succeeded') return `✓ ${event.actionId} finished · ${formatDuration(event.durationSec)}`;
+      if (event.status === 'blocked') return `⊘ ${event.actionId} blocked · ${event.why ?? 'dependency not satisfied'}`;
+      if (event.status === 'cancelled') return `✗ ${event.actionId} cancelled · ${formatDuration(event.durationSec)}`;
+      return `✗ ${event.actionId} ${event.status} · ${event.failureKind ?? 'unknown'}: ` +
+        `${event.why ?? 'no reason recorded'} · ${formatDuration(event.durationSec)}`;
+    case 'evidence.recorded':
+      return `◆ ${event.actionId} evidence · ` +
+        (event.requirements.map((item) => `${item.id} ${item.status}`).join(', ') || 'no requirements');
+    case 'stage.completed':
+      return event.status === 'completed'
+        ? `✓ ${event.label} completed · ${event.completed}/${event.total}`
+        : `✗ ${event.label} ended · ${event.completed}/${event.total}`;
+    case 'planner.finished':
+      if (!event.ok) return `× planning attempt rejected · ${event.why}`;
+      return event.turn === 1
+        ? `◇ plan created (turn 1) · ${event.summary ?? event.kind ?? 'no summary'}`
+        : `◇ plan updated #${event.turn} · ${event.summary ?? event.kind ?? 'no summary'}`;
+    case 'agent.stalled':
+      return `⚠ ${event.actionId} silent for ${formatDuration(event.silentSec)} · ` +
+        `${event.pool ?? '?'}/${event.model ?? '?'} · still running, not auto-killed`;
+    case 'agent.recovered':
+      return `↻ ${event.actionId} active again after ${formatDuration(event.silentSec)}`;
+    case 'cancellation.requested':
+      return '⧖ cancellation requested';
+    case 'action.started':
+      return `▶ ${event.actionId} started · ${event.pool ?? '?'}/${event.model ?? '?'} · attempt ${event.attempt ?? '?'}`;
+    case 'attempt.retrying':
+      return `↺ ${event.actionId} retrying · ${event.failureKind}`;
+    case 'steering.delivered':
+      return '→ steering delivered';
+    default:
+      return null;
+  }
+}
+
+function watchEventLine(event, { jsonl, at, runId, shortId, sequence = null }) {
+  if (!jsonl) return renderWatchEvent(event);
+  const { type, ...fields } = event;
+  // `sequence` is the durable cursor this object was emitted at: the machine
+  // form of the human `next: ... --after <sequence>` relaunch line.
+  return JSON.stringify({ type, at, runId, shortId, ...(sequence == null ? {} : { sequence }), ...fields });
+}
+
 export async function runWorkflowWatch(bullswarmDir, token, {
   intervalMs = 2000,
-  heartbeatMs = 60000,
+  // Absent means "no periodic heartbeat" for V2 runs and the historical 60s
+  // for legacy runs; `--heartbeat <seconds>` opts a V2 run back in.
+  heartbeatMs = null,
   once = false,
+  next = false,
   jsonl = false,
   verbose = false,
+  stallAfterMs = DEFAULT_STALL_AFTER_MS,
+  // Continuity across a --next relaunch: start from the durable sequence the
+  // previous watcher had consumed, and treat stalls it already reported (it
+  // exited at sinceMs) as reported. Both absent means attach as usual.
+  afterSequence = null,
+  sinceMs = null,
   waitForRunMs = 0,
+  now = Date.now,
   output = process.stdout,
 } = {}) {
   const resolved = await resolveRunWithGrace(bullswarmDir, token, waitForRunMs, intervalMs);
   const statePath = join(resolved.runDir, 'state.json');
+  // --next follows the run until something happens, so it never degrades to a
+  // single snapshot even if --once is also passed.
+  const oneShot = once && !next;
   let priorFingerprint = null;
   let priorHumanFingerprint = null;
   let lastPrintedAt = 0;
   let priorSequence = null;
   let pendingEvents = [];
   let lastActivityAt = null;
+  let memory = null;
+  let attached = false;
   while (true) {
     const state = withV2Cancellation(readJson(statePath), resolved.runDir);
     if (state) {
-      const snapshot = watchSnapshot(resolved.runDir, state);
+      const nowMs = now();
+      const snapshot = watchSnapshot(resolved.runDir, state, new Date(nowMs));
+      // Legacy runs keep their transition-plus-heartbeat output exactly as it
+      // was; only V2 runs become event-based, and --once stays a snapshot.
+      const eventMode = isV2State(state) && !oneShot;
       if (priorSequence == null) {
         // A newly attached watcher has no preceding interval. Start at the
-        // durable high-water mark instead of replaying the run lifetime.
-        priorSequence = state.events?.sequence ?? state.eventSequence ?? 0;
+        // durable high-water mark instead of replaying the run lifetime, unless
+        // --after names the cursor the previous watcher stopped at, in which
+        // case the events committed since then are replayed and printed.
+        priorSequence = afterSequence ?? state.events?.sequence ?? state.eventSequence ?? 0;
         // Semantic quiet counts durable marks only (events, action starts and
         // finishes). Raw child output is surfaced separately as transport
         // liveness so a thinking agent and a dead one look different.
@@ -322,7 +681,7 @@ export async function runWorkflowWatch(bullswarmDir, token, {
             Date.parse(agent.lastActionAt ?? '') || 0,
             Date.parse(agent.startedAt ?? '') || 0,
           )),
-          Date.parse(state.lifecycle?.startedAt ?? state.startedAt ?? '') || Date.now(),
+          Date.parse(state.lifecycle?.startedAt ?? state.startedAt ?? '') || nowMs,
         );
       }
       const newEvents = readEvents(resolved.runDir, { after: priorSequence });
@@ -330,51 +689,117 @@ export async function runWorkflowWatch(bullswarmDir, token, {
         pendingEvents.push(...newEvents);
         lastActivityAt = Math.max(
           lastActivityAt,
-          ...newEvents.map((event) => Date.parse(event.committedAt ?? '') || Date.now()),
+          ...newEvents.map((event) => Date.parse(event.committedAt ?? '') || nowMs),
         );
         priorSequence = newEvents.at(-1)?.sequence ?? state.events?.sequence ?? state.eventSequence ?? priorSequence;
       }
-      snapshot.quietForSec = Math.max(0, Math.floor((Date.now() - lastActivityAt) / 1000));
-      const fingerprint = snapshotFingerprint(snapshot);
-      const humanFingerprint = humanTransitionFingerprint(snapshot);
-      const heartbeat = Date.now() - lastPrintedAt >= heartbeatMs;
-      const changed = jsonl || verbose
-        ? fingerprint !== priorFingerprint
-        : humanFingerprint !== priorHumanFingerprint;
-      if (changed || heartbeat || once) {
-        output.write(jsonl
-          ? `${JSON.stringify({ type: heartbeat && fingerprint === priorFingerprint ? 'heartbeat' : 'progress', ...snapshot })}\n`
-          : `${renderWatchSnapshot(snapshot, {
-            heartbeat: heartbeat && !changed,
-            verbose,
-            events: pendingEvents,
-          })}\n`);
-        priorFingerprint = fingerprint;
-        priorHumanFingerprint = humanFingerprint;
-        lastPrintedAt = Date.now();
-        pendingEvents = [];
+      snapshot.quietForSec = Math.max(0, Math.floor((nowMs - lastActivityAt) / 1000));
+      const emitLine = (event) => {
+        const line = watchEventLine(event, {
+          jsonl, at: snapshot.at, runId: snapshot.runId, shortId: snapshot.shortId,
+          sequence: priorSequence,
+        });
+        if (line == null) return;
+        output.write(`${line}\n`);
+        lastPrintedAt = nowMs;
+      };
+      let notablePrinted = 0;
+      if (eventMode) {
+        if (!attached) {
+          attached = true;
+          memory = initialWatchMemory(state, {
+            replayedEvents: afterSequence == null ? [] : newEvents,
+            sinceMs, stallAfterMs, nowMs,
+          });
+          lastPrintedAt = nowMs;
+          // --next is a wake-up call, not a follow: it prints only what happens.
+          if (!next) {
+            emitLine({
+              type: 'attach', runId: snapshot.runId, shortId: snapshot.shortId,
+              status: snapshot.status, running: snapshot.runningCount,
+              waiting: snapshot.waitingCount, elapsedSec: snapshot.elapsedSec,
+            });
+          }
+        }
+        const collected = notableWatchEvents({
+          events: newEvents, state, memory, verbose, nowMs, stallAfterMs,
+        });
+        memory = collected.memory;
+        for (const event of collected.notable) {
+          emitLine(event);
+          notablePrinted += 1;
+        }
+        // The periodic heartbeat is opt-in for V2 runs (--heartbeat <seconds>).
+        const beatMs = Number.isFinite(heartbeatMs) && heartbeatMs > 0 ? heartbeatMs : null;
+        if (beatMs != null && !next && nowMs - lastPrintedAt >= beatMs) {
+          output.write(jsonl
+            ? `${JSON.stringify({ type: 'heartbeat', ...snapshot })}\n`
+            : `${renderWatchSnapshot(snapshot, { heartbeat: true, verbose, events: pendingEvents })}\n`);
+          lastPrintedAt = nowMs;
+          pendingEvents = [];
+        }
+      } else {
+        const legacyHeartbeatMs = heartbeatMs == null ? 60000 : heartbeatMs;
+        const fingerprint = snapshotFingerprint(snapshot);
+        const humanFingerprint = humanTransitionFingerprint(snapshot);
+        const heartbeat = nowMs - lastPrintedAt >= legacyHeartbeatMs;
+        const changed = jsonl || verbose
+          ? fingerprint !== priorFingerprint
+          : humanFingerprint !== priorHumanFingerprint;
+        if (changed || heartbeat || oneShot) {
+          output.write(jsonl
+            ? `${JSON.stringify({ type: heartbeat && fingerprint === priorFingerprint ? 'heartbeat' : 'progress', ...snapshot })}\n`
+            : `${renderWatchSnapshot(snapshot, {
+              heartbeat: heartbeat && !changed,
+              verbose,
+              events: pendingEvents,
+            })}\n`);
+          priorFingerprint = fingerprint;
+          priorHumanFingerprint = humanFingerprint;
+          lastPrintedAt = nowMs;
+          pendingEvents = [];
+          if (changed) notablePrinted += 1;
+        }
       }
       if (snapshot.interrupted) {
-        if (!jsonl) { output.write(`outcome: interrupted; edits retained\nnext: bullswarm workflow resume ${snapshot.shortId ?? snapshot.runId}\n`); }
-        return once ? 0 : 1;
+        if (eventMode && jsonl) emitLine({ type: 'interrupted', status: snapshot.status });
+        else if (!jsonl) { output.write(`outcome: interrupted; edits retained\nnext: bullswarm workflow resume ${snapshot.shortId ?? snapshot.runId}\n`); }
+        return oneShot ? 0 : 1;
       }
-      if (snapshot.terminal || once) {
-        if (!jsonl && snapshot.terminal) {
+      if (snapshot.terminal || oneShot) {
+        if (eventMode && jsonl && snapshot.terminal) {
+          emitLine({ type: 'finished', status: snapshot.status, delivered: isDeliveredWorkflowStatus(snapshot.status) });
+        } else if (!jsonl && snapshot.terminal) {
           output.write(`outcome: ${snapshot.status}\n`);
           output.write(`next: bullswarm workflow runs result ${snapshot.shortId ?? snapshot.runId} --json\n`);
         }
-        return isDeliveredWorkflowStatus(snapshot.status) || once ? 0 : 1;
+        return isDeliveredWorkflowStatus(snapshot.status) || oneShot ? 0 : 1;
       }
       if (snapshot.awaitingPlanner) {
         // A caller-planner run has paused durably; the runtime process has
         // exited and nothing will change until the caller submits a program
         // (or, after a cancellation request, resumes it once to finalize).
-        if (!jsonl) {
-          const token = snapshot.shortId ?? snapshot.runId;
+        const runToken = snapshot.shortId ?? snapshot.runId;
+        if (eventMode && jsonl) {
+          emitLine({
+            type: 'paused', boundary: snapshot.awaitingPlanner.boundary,
+            turn: snapshot.awaitingPlanner.turn, cancellationRequested: snapshot.cancellationRequested,
+          });
+        } else if (!jsonl) {
           output.write(`outcome: waiting for the caller planner (${snapshot.awaitingPlanner.boundary} boundary)\n`);
           output.write(snapshot.cancellationRequested
-            ? `next: cancellation requested; bullswarm workflow cancel ${token} --json finalizes it\n`
-            : `next: bullswarm workflow plan show ${token} --json\n`);
+            ? `next: cancellation requested; bullswarm workflow cancel ${runToken} --json finalizes it\n`
+            : `next: bullswarm workflow plan show ${runToken} --json\n`);
+        }
+        return 0;
+      }
+      // --next has delivered its wake-up: something notable happened and the
+      // run is still going. The relaunch line hands the caller the exact cursor
+      // and exit time to resume from, so nothing committed in between is lost.
+      if (next && notablePrinted > 0) {
+        if (eventMode && !jsonl) {
+          output.write(`next: bullswarm workflow watch ${snapshot.shortId ?? snapshot.runId}`
+            + ` --next --after ${priorSequence} --since ${snapshot.at}\n`);
         }
         return 0;
       }