bullswarm 0.25.2 → 0.25.3

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # bullswarm changelog
 
+## 0.25.3 — usage-limit recovery and headroom-aware routing
+
+- A provider that reports a usage limit is now its own mechanical failure kind,
+  `quota` — never `process`, `semantic`, or `auth`. The attempt is killed at
+  once instead of waiting out a CLI that printed its limit and then hung, and
+  the pool is quarantined until the reset the message named, falling back to
+  that pool's cached 5-hour `resets_at` and then to 30 minutes rather than the
+  flat 10. The quarantine record carries `kind: 'quota'` and excludes the pool
+  from every later dispatch, in that run and in others, until it expires; the
+  action moves to another pool with quota and is never retried on the one that
+  hit the limit. `bullswarm run`, the V1 runtime, and V2 dispatch all apply the
+  same deadline. Detection is shape-gated: an agent report that discusses usage
+  limits, or tool output quoting them, is not a limit, and phrases that other
+  services also emit (`rate limited`, `too many requests`, `quota exceeded`)
+  count only as a bare notice, never as narration about someone else's quota
+  ("rate limited by the GitHub API, retrying"). Connectors declare their
+  own phrases under `quotaSignatures`; installed connectors receive new ones on
+  upgrade.
+
+- Routing avoids pools that are close to their 5-hour limit. A pool at or above
+  `FIVE_HOUR_NEAR_LIMIT_PCT` (75) is chosen only when no eligible pool below it
+  exists for the lane, ahead of pace, an approved assignment, and incumbency;
+  pools at or above 90 stay excluded outright, and a pool with no 5-hour
+  reading counts as having headroom. Routing reasons and candidate lists name
+  the utilization that decided the pick, and `bullswarm pools` shows it as
+  `5h=<n>%` with a `NEAR-5H-LIMIT` label. Meters and quarantines are re-read
+  from the meter cache and core state before every action dispatch and before
+  every retry inside one — forced live right after a usage limit — so a long
+  run no longer dispatches from the pool snapshot frozen at launch.
+
+- `workflow watch` reports a usage-limit retry as a notable event in both
+  modes' vocabulary: `⚠ <action> usage limit on <pool> · paused until
+  <deadline> · retrying on another pool`, then `↺ <action> now on <pool> ·
+  <model>` once the retry lands. Both print without `--verbose`, wake `--next`,
+  and appear in `--jsonl` as `attempt.quota` and `attempt.moved`. The new
+  `--classic` flag forces the older heartbeat-based watcher (transition-on-change
+  snapshots plus a periodic heartbeat, 60 seconds unless `--heartbeat <seconds>`
+  is given) for a V2 run; it is a no-op for legacy runs and cannot combine with
+  `--next`.
+
 ## 0.25.2 — event-based watch
 
 - `workflow watch <run> --next` is safe to relaunch after every wake-up: each

package/README.md

@@ -37,12 +37,17 @@ detaches safely.
    passing verification.
 2. **Pace by meter.** The scheduling resource is the subscription window:
    elapsed% minus used%, most-behind pool wins. Pace may only promote a
-   *cheaper* pool. Lanes are work-nature, never hard-coded to pools.
+   *cheaper* pool. Lanes are work-nature, never hard-coded to pools. The
+   5-hour window never paces — it gates: a pool at or above 75% of it is
+   chosen only when no eligible pool below that line exists, and one at or
+   above 90% is not dispatched at all.
 3. **Delegate output is evidence, never authority.** The Workflow Planner may
    propose actions, but only the deterministic kernel validates the program,
    accepts requirement-scoped evidence, and computes completion.
 4. **Quarantine re-probes.** A benched pool must be able to return to service
-   automatically; a lane is never allowed to silently go down.
+   automatically; a lane is never allowed to silently go down. A pool benched
+   for a usage limit waits for the reset the provider named, not a flat
+   guess — and never longer.
 
 ## Install
 
@@ -94,7 +99,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | `delegate` | Explain and execute the smallest reliable shape: one content-verified agent, or the planning contract for an autonomous workflow you author (`--orchestrator` dispatches a planner agent instead). |
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
-| `pools` | Show each pool's meter state, pace position, quarantine status |
+| `pools` | Show each pool's meter state, pace position, 5-hour utilization (`5h=<n>%`, flagged `NEAR-5H-LIMIT` at or above 75%), quarantine status |
 | `strategy` | Interactive provider/model control center with live high/medium/low route previews and an agent-facing JSON API |
 | `doctor` | Machine-readable readiness report; self-heals on first call |
 | `workflow` | Start an autonomous goal, or run / validate / draft / inspect explicit workflows and their live instances. |
@@ -209,8 +214,15 @@ best eligible models on its configured interval. Disable it with
 `strategy auto off --yes`. Discovery commands, model argument syntax, pricing,
 and benchmark declarations remain connector-owned. Unknown license value,
 prices, and benchmarks stay `null` rather than being guessed. An assignment is
-only a preference: quarantine, exhaustion, burst gates, and capability checks
-still win.
+only a preference: quarantine, exhaustion, burst gates, 5-hour headroom, and
+capability checks still win. Routing prefers pools below
+`FIVE_HOUR_NEAR_LIMIT_PCT` (75) of their 5-hour window over pools at or above
+it, ahead of pace, an approved assignment, and incumbency; a near-limit pool is
+still picked when it is the only eligible one, and a pool with no 5-hour
+reading counts as having headroom. The routing reason and every candidate row
+name the utilization that decided the pick, and meters and quarantines are
+re-read before each dispatch — and again, live, right after a usage limit —
+so a long run never routes off the snapshot it launched with.
 
 Model exclusions are hard routing policy. An excluded model is removed from
 recommendations and assignments, and Bullswarm pins a same-tier allowed model
@@ -490,9 +502,18 @@ prints one attach line, then one line per notable event as it happens
 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
+only with `--verbose`. A usage-limit failure (`failureKind: 'quota'`) always
+prints, verbose or not: `⚠ <actionId> usage limit on <pool> · paused until
+<deadline> · retrying on another pool`, followed once the mechanical retry
+lands on another pool by `↺ <actionId> now on <pool> · <model>`. The
+periodic heartbeat is off unless you pass `--heartbeat <seconds>`;
+`--stall-after <seconds>` (default 300) reports a running agent that has
+gone silent. Pass `--classic` to force the older heartbeat-based watcher
+instead (the transition-on-change snapshot stream plus a periodic
+heartbeat, every 60 seconds unless `--heartbeat <seconds>` is given) —
+legacy (non-V2) runs already behave this way and `--classic` is a no-op for
+them; `--classic` cannot combine with `--next`, which exists only for event
+mode. `--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
@@ -507,12 +528,14 @@ 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`,
+`agent.recovered`, `cancellation.requested`, `attempt.quota`,
+`attempt.moved`, `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.
+(non-V2) runs keep the compact transition-plus-heartbeat stream unchanged,
+the same stream `--classic` opts a V2 run into.
 
 ```bash
 bullswarm workflow watch <shortId>
@@ -523,6 +546,7 @@ bullswarm workflow watch <shortId> --jsonl       # one JSON object per event
 bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
 bullswarm workflow watch <shortId> --verbose     # started / retry / steering too
 bullswarm workflow watch <shortId> --stall-after 120 --heartbeat 30
+bullswarm workflow watch <shortId> --classic     # older heartbeat-based watcher instead of event mode
 ```
 
 `workflow tui` is the interactive, Claude-style `/workflows` view. For an
@@ -611,6 +635,20 @@ channel, so reading source text such as an auth-signature matcher cannot falsely
 quarantine Grok or Command Code. Error-shaped semantic results and stderr
 diagnostics still trigger the auth/quota guard.
 
+A provider that reports a usage limit — `You've hit your session limit ·
+resets 8:20pm (Asia/Hong_Kong)`, `usage_credits_required`, `rate limit
+exceeded`, `quota exceeded` — is its own mechanical failure kind, `quota`,
+never `process`, `semantic`, or `auth`. The attempt is killed immediately
+even if the CLI would otherwise hang, and the pool is quarantined until the
+reset time parsed from the message, falling back to that pool's cached 5-hour
+`resets_at` and then to 30 minutes. The quarantine record carries
+`kind: 'quota'` and excludes the pool from every later dispatch, in this run
+and in others, until it expires; the action is immediately re-dispatched on
+another pool with quota and never retried on the one that hit the limit. An
+agent report that merely discusses usage limits, or tool output that quotes
+them, is not a limit: detection is shape-gated to lines that look like a
+provider notice.
+
 After ten minutes without transport, parsed-event, or semantic-action evidence,
 an active child is labeled `suspected_stalled`. This is an inspection signal,
 not a death verdict and never an automatic kill: buffered CLIs can be silent

package/connectors/_schema.json

@@ -10,6 +10,8 @@
     "$comment-cwd": "cwdMode documents how the CLI resolves its project: 'pwd' means the CLI resolves from $PWD so the watcher MUST set PWD and spawn inside --add-dir"
   },
   "authSignatures": ["strings in output that mean auth/throttle failure"],
+  "quotaSignatures": ["strings in output that mean this credential is out of quota RIGHT NOW (usage/rate limit hit)"],
+  "$comment-quotaSignatures": "Optional. Merged on top of DEFAULT_QUOTA_SIGNATURES (src/lib/quota.js), matched case-insensitively, and only honored when the matched line is quota-shaped (<=300 chars and the phrase starts in the first 40 chars or the line is error-shaped) so agent prose and tool output that merely discuss limits are never killed. A hit is classified as the mechanical failure kind `quota` (checked before authSignatures), kills the attempt, and quarantines the pool until the reset time parsed from the message, else the pool's cached five_hour.resets_at, else 30 minutes.",
   "outputExtraction": {
     "$comment": "how to get the real answer out of stdout+stderr+files",
     "strategy": "stdout|stdout-tail|json-field|file|event-stream",

package/connectors/claude-code.json

@@ -23,6 +23,12 @@
     "not logged in",
     "please run /login"
   ],
+  "$comment-quotaSignatures": "usage-limit phrases: classified `quota`, quarantined until the reset the message names. DEFAULT_QUOTA_SIGNATURES (src/lib/quota.js) apply on top of these.",
+  "quotaSignatures": [
+    "hit your session limit",
+    "hit your limit",
+    "hit your usage limit"
+  ],
   "outputExtraction": {
     "strategy": "event-stream"
   },

package/connectors/codex.json

@@ -21,6 +21,11 @@
     "unauthorized",
     "invalid api key"
   ],
+  "$comment-quotaSignatures": "usage_credits_required is a spent window, not a broken credential: it classifies `quota` (checked before authSignatures) so the pool is quarantined until its reset instead of re-probed in 10 minutes.",
+  "quotaSignatures": [
+    "usage_credits_required",
+    "usage limit"
+  ],
   "outputExtraction": {
     "strategy": "event-stream"
   },

package/connectors/command-code.json

@@ -21,6 +21,8 @@
     "not authenticated",
     "cmd login"
   ],
+  "$comment-quotaSignatures": "empty on purpose: no cmd-specific usage-limit wording has been observed yet; DEFAULT_QUOTA_SIGNATURES in src/lib/quota.js covers the generic provider phrasings.",
+  "quotaSignatures": [],
   "outputExtraction": {
     "strategy": "event-stream"
   },

package/connectors/echo-worker.mjs

@@ -1,6 +1,7 @@
 // echo-worker.mjs — deterministic test delegate for bullswarm.
 // Reads a task file; behavior is driven by directives in the task text.
 //   FAIL:auth   -> prints an auth failure, exits 0 (the lying-exit trap)
+//   FAIL:quota  -> prints a provider usage limit naming its reset, exits 0
 //   FAIL:exit   -> prints a complete answer, exits 1 (exit-1-after-success)
 //   INTENT:     -> prints only an announcement, exits 0
 //   otherwise   -> echoes the task as a completed answer, exit 0
@@ -11,6 +12,11 @@ const task = readFileSync(process.argv[2], 'utf8');
 const sleepMatch = task.match(/SLEEP_MS:(\d+)/);
 if (sleepMatch) await new Promise((resolve) => setTimeout(resolve, Number(sleepMatch[1])));
 
+if (task.includes('FAIL:quota')) {
+  // A usage limit is not a broken credential: it names when it resets.
+  console.log('Error: usage limit reached · resets in 45 minutes');
+  process.exit(0);
+}
 if (task.includes('FAIL:auth-hang')) {
   console.log('Authentication failed: quota exhausted; waiting process should be terminated.');
   await new Promise((resolve) => setTimeout(resolve, 5000));

package/connectors/echo.json

@@ -7,6 +7,7 @@
     "cwdMode": "task-file-dir"
   },
   "authSignatures": ["Authentication failed", "unauthorized"],
+  "quotaSignatures": [],
   "outputExtraction": { "strategy": "stdout" },
   "meter": { "type": "none" },
   "costRank": 5,

package/connectors/grok.json

@@ -17,6 +17,8 @@
     "rate limit",
     "invalid api key"
   ],
+  "$comment-quotaSignatures": "empty on purpose: no grok-specific usage-limit wording has been observed yet, and the generic phrasings (rate limit exceeded, too many requests, quota exceeded) already come from DEFAULT_QUOTA_SIGNATURES in src/lib/quota.js.",
+  "quotaSignatures": [],
   "outputExtraction": {
     "strategy": "event-stream"
   },

package/connectors/opencode2.json

@@ -8,6 +8,8 @@
     "$comment-cwdMode": "QUIRK: resolves its project from $PWD, not the spawn cwd. The watcher MUST set env.PWD and spawn with cwd inside the target repo, or it will silently analyse the wrong repository and answer confidently about it."
   },
   "authSignatures": ["No cookie auth credentials found", "unauthorized"],
+  "$comment-quotaSignatures": "empty on purpose: provider quota errors reach opencode from the upstream API in generic form (insufficient_quota, rate limit exceeded, too many requests), which DEFAULT_QUOTA_SIGNATURES in src/lib/quota.js already matches.",
+  "quotaSignatures": [],
   "outputExtraction": { "strategy": "event-stream" },
   "eventStream": {
     "format": "jsonl",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "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

@@ -124,7 +124,11 @@ 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.
+`--stall-after` (default 300s) reports a silent running agent. A usage-limit
+failure always prints — `⚠ ... usage limit on <pool> · paused until <deadline>
+· retrying on another pool`, then `↺ ... now on <pool> · <model>` once the
+mechanical retry lands — even without `--verbose`. Pass `--classic` for the
+older heartbeat-based watcher instead (it cannot combine with `--next`).
 `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

@@ -51,7 +51,13 @@ 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.
+agent. A usage-limit failure always prints, verbose or not: `⚠ ... usage
+limit on <pool> · paused until <deadline> · retrying on another pool`, then
+`↺ ... now on <pool> · <model>` once the mechanical retry lands on another
+pool. Use `--verbose` only for diagnosis. `--classic` forces the older
+heartbeat-based watcher (transition-on-change snapshots plus a periodic
+heartbeat) instead of event mode; it is a no-op for legacy runs and cannot
+combine with `--next`.
 The result command is the stable delivery/verification envelope; do not scrape
 task files or assume the last provider response is the deliverable.
 
@@ -149,9 +155,13 @@ bullswarm strategy inventory --json
 bullswarm strategy routes --json
 ```
 
-Automatic routing chooses the most-behind capable eligible pool, honors burst
-gates and quarantine, and applies only explicitly approved model assignments
-and exclusions. Humans can use bare `bullswarm strategy` to toggle providers
+Automatic routing chooses the most-behind capable eligible pool among those
+with 5-hour headroom, honors burst gates and quarantine, and applies only
+explicitly approved model assignments and exclusions. A pool at or above 75%
+of its 5-hour window is picked only when no eligible pool below that line
+exists; `bullswarm pools` shows the reading as `5h=<n>%` with a
+`NEAR-5H-LIMIT` label, and meters and quarantines are re-read before every
+dispatch rather than frozen at launch. Humans can use bare `bullswarm strategy` to toggle providers
 and multi-select high/medium/low per model. Agents should consume the inventory
 and apply validated changes with `strategy set-provider`, `strategy set-model`,
 or one atomic `strategy configure --file <json> --yes`. Never weaken those
@@ -159,8 +169,13 @@ controls in a prompt.
 
 ## Recovery and stopping rules
 
-- Auth/throttle signatures quarantine the affected pool; later dispatches use
-  another eligible pool.
+- Auth signatures quarantine the affected pool for a 10-minute re-probe
+  window; later dispatches use another eligible pool.
+- A provider usage limit is the distinct failure kind `quota`: the attempt is
+  killed at once, the pool is quarantined until the reset the message named
+  (else its cached 5-hour `resets_at`, else 30 minutes), and the action moves
+  to a pool that still has quota. The quarantine holds across runs until it
+  expires. Discussing usage limits in a report is not a usage limit.
 - A quota-gated preferred orchestrator falls back unless it was strictly pinned
   for QA.
 - Silence is evidence to inspect, not automatic proof of a hang. Check the TUI

package/src/cli.js

@@ -78,13 +78,17 @@ async function cmdPools(opts) {
       ? 'unmetered'
       : `used ${p.usedPct ?? '?'}% elapsed ${p.elapsedPct ?? '?'}% [${src}]`;
     const burst = p.burstGate ? ' BURST-GATED' : '';
+    // 5h is a gate, never a pace (doctrine M3): show the reading and whether
+    // routing now deprioritizes this pool for it.
+    const fiveHour = p.fiveHourUsedPct == null ? '' : ` 5h=${Math.round(p.fiveHourUsedPct * 10) / 10}%`;
+    const nearLimit = p.nearFiveHourLimit === true ? ' NEAR-5H-LIMIT' : '';
     const status = !p.enabled
       ? 'disabled'
       : p.quarantine
         ? `QUARANTINED until ${new Date(p.quarantine.until).toLocaleTimeString()} (${p.quarantine.reason})`
-        : `ready${burst}`;
+        : `ready${burst}${nearLimit}`;
     console.log(
-      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} ${status}`,
+      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'}${fiveHour} ${status}`,
     );
   }
   return 0;
@@ -228,6 +232,9 @@ async function cmdRun(opts) {
       timeoutSec: opts.timeout == null ? null : Number(opts.timeout),
       env: childDepthEnv(process.env),
       model: selectedModel,
+      // Lets a usage-limit verdict fall back to this pool's cached 5h meter
+      // reset when the provider's message named no reset time of its own.
+      bullswarmDir: getBullswarmDir(),
       onActivity: (event) => heartbeat.activity(event),
       onAgentEvent: () => heartbeat.event(),
     });
@@ -240,7 +247,12 @@ async function cmdRun(opts) {
     state.incumbents ??= {};
     state.incumbents[lane] = connector.name;
   } else if (verdict.quarantineHint) {
-    quarantinePool(state, connector.name, verdict.why, now);
+    // A usage limit carries its own deadline (the reset the provider named);
+    // an auth failure keeps the flat re-probe window.
+    quarantinePool(state, connector.name, verdict.why, now, {
+      until: verdict.quarantineUntil ?? null,
+      kind: verdict.failureKind === 'quota' ? 'quota' : 'auth',
+    });
     verdict.quarantinedUntil = state.pools[connector.name]?.quarantine?.until;
   }
 

package/src/help.js

@@ -987,20 +987,26 @@ const workflowTuiText = rich({
 });
 
 const workflowWatchText = rich({
-  usage: 'bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--stall-after <seconds>] [--next [--after <sequence>] [--since <iso-timestamp>]] [--jsonl] [--once] [--verbose]',
+  usage: 'bullswarm workflow watch <runId> [--classic] [--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. '
+    + 'cancellation) and staying silent while work is merely in progress. A usage-limit failure always '
+    + 'prints, verbose or not: an `⚠ ... usage limit on <pool> · paused until <deadline> · retrying on '
+    + 'another pool` line, then an `↺ ... now on <pool> · <model>` line once the mechanical retry lands. '
+    + '`--classic` forces the older heartbeat-based watcher instead (transition-on-change snapshots plus '
+    + 'a periodic heartbeat); legacy runs already behave this way and are unaffected. `--next` prints no '
+    + 'attach line and returns after the first notable event, or immediately at a pause or terminal status '
+    + '(event mode only — it cannot combine with `--classic`). '
     + '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.',
+    + '`--heartbeat` is opt-in for V2; legacy runs (and `--classic`) keep the historical 60s heartbeat by '
+    + 'default. Distinct from the full-screen tui and the machine-oriented events replay.',
   args: [{ name: '<runId>', desc: 'shortId or runId' }],
   options: [
+    { flag: '--classic', desc: 'force the older heartbeat-based watcher (transition-on-change snapshots plus a periodic heartbeat) instead of event mode; no-op for legacy runs; cannot combine with --next', default: 'off (event mode for V2 runs)' },
     { flag: '--interval <seconds>', desc: 'poll interval while following', default: '2' },
-    { 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: '--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 and --classic' },
     { 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' },
@@ -1014,11 +1020,13 @@ const workflowWatchText = rich({
     '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',
+    '--classic --next is rejected with exit 2: --next only applies to event mode',
   ],
   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' },
+    { cmd: 'bullswarm workflow watch ab12cd --classic', note: 'the older heartbeat-based watcher instead of event mode' },
   ],
   next: 'bullswarm workflow runs result <runId> --json once it finishes, or bullswarm workflow tui <runId> for the interactive view.',
 });

package/src/lib/config.js

@@ -13,6 +13,7 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadState } from './state.js';
 import { paceScore, isQuarantined } from './route.js';
+import { FIVE_HOUR_NEAR_LIMIT_PCT } from '../meters/framework.js';
 import { expandClaudeAccountConnectors } from './claude-accounts.js';
 import { expandOpenCodeKaihkConnectors } from './opencode-kaihk.js';
 
@@ -66,6 +67,10 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
       elapsedPct: null,
       pace: null,
       burstGate: false,
+      // 5h window (doctrine M3): gates routing, never paces it.
+      fiveHourUsedPct: null,
+      fiveHourResetsAt: null,
+      nearFiveHourLimit: false,
       meterSnapshot: null,
       subscription: {
         ...(conn.subscription ?? {}),
@@ -85,6 +90,15 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
     const ps = state.pools[p.name] ?? {};
 
     const reading = readings[p.name];
+    // The 5h gate is independent of the pacing window: a reading may carry a
+    // 5h utilization with no weekly/monthly window to pace by, and routing
+    // still has to see that the pool is close to its 5h limit.
+    if (reading) {
+      const fiveHour = fiveHourFromReading(reading);
+      p.fiveHourUsedPct = fiveHour.usedPct;
+      p.fiveHourResetsAt = fiveHour.resetsAt;
+      p.nearFiveHourLimit = fiveHour.nearLimit;
+    }
     if (reading?.pacing) {
       // Provider-truth path (M1/M2)
       p.meterSource = reading.source; // live | cache | stale
@@ -112,6 +126,30 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
   return { state, connectors, pools };
 }
 
+/** null-safe finite coercion: null/undefined/NaN all mean "no reading". */
+function finiteOrNull(value) {
+  if (value == null) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * 5h window fields from a meter reading. Prefers the flat fields paceSnapshot
+ * produces and falls back to the raw snapshot, so a reading assembled by an
+ * older code path still reports a real 5h number instead of null.
+ */
+function fiveHourFromReading(reading) {
+  const usedPct = finiteOrNull(reading?.fiveHourUsedPct)
+    ?? finiteOrNull(reading?.snapshot?.five_hour?.utilization);
+  const raw = reading?.fiveHourResetsAt ?? reading?.snapshot?.five_hour?.resets_at ?? null;
+  const resetsMs = typeof raw === 'string' ? Date.parse(raw) : NaN;
+  return {
+    usedPct,
+    resetsAt: Number.isFinite(resetsMs) ? new Date(resetsMs).toISOString() : null,
+    nearLimit: usedPct != null && usedPct >= FIVE_HOUR_NEAR_LIMIT_PCT,
+  };
+}
+
 /**
  * Async variant that fetches live readings for pools with readers.
  */