bullswarm 0.25.4 → 0.25.5

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # bullswarm changelog
 
+## 0.25.5 — forecast-aware routing
+
+- Bullswarm now knows what it is already running. Every dispatch registers the
+  work it starts in a small ledger on disk (`~/.bullswarm/assignments/`, one
+  atomically written file per assignment), and every process reads it: a
+  `bullswarm run` in one terminal, a V1 runtime and four concurrent V2 kernel
+  actions all see each other's agents instead of each assuming the pool is
+  idle. Records whose process is gone, or that are older than 12 hours, are
+  pruned on read, so a crash cannot leave phantom load behind. `bullswarm
+  assignments` lists what is in flight right now — pool, run, action, how long
+  it has been going and how much longer it is expected to take — and
+  `bullswarm pools` carries the same count as `inflight=<n>`.
+
+- A spend model turns those records into percentage points. It measures how
+  fast a pool actually burns its 5-hour and weekly windows by pairing meter
+  readings with the worker-minutes dispatched between them, and how long an
+  assignment on a given lane and effort tier usually runs by taking the median
+  of real attempts from the decision log. Every number carries its basis —
+  `history` (measured), `bootstrap` (one window's usage so far), or the
+  documented `default` table — and the sample count behind it. A pool nobody
+  has measured reports `null`, never a plausible-looking guess.
+
+- Routing now decides on the forecast instead of on the last reading. Each
+  pool's projection (reading + what its in-flight agents will still spend) gets
+  the expected consumption of the assignment being routed added on top, and the
+  existing thresholds apply to that number: a pool projected at or above 75% of
+  its 5-hour window drops to the near-limit tier while its reading is still
+  below the line, and one projected at or above 90% is dropped from selection
+  as forecast-gated. Nothing is gated on an unknown forecast, and if every
+  capable pool is gated, the least loaded of them is still picked — with the
+  reason saying exactly that — rather than the action being stranded.
+
+- Parallel work now spreads instead of stacking. Within a tier, a pool's pace
+  surplus is reduced by the weekly quota its in-flight agents and this
+  assignment are expected to spend, and by at least a flat 3 surplus points
+  per in-flight agent (`DEFAULT_INFLIGHT_PENALTY_PCT`, `config.inflightPenaltyPct`
+  in state.json, `0` disables it). The floor matters: at measured weekly rates
+  a six-minute agent projects to under one point, which would leave a burst on
+  one pool. The charge is labeled `penalty` when the floor set it and by its
+  measured basis otherwise. Load also beats incumbency: an incumbent carrying
+  more in-flight agents than a challenger keeps neither its margin nor its cost
+  guard. Four actions launched within the same second land on
+  four different providers rather than all on the single most-behind one, and
+  the V2 kernel re-reads the ledger before every pick rather than only on its
+  throttled meter refresh, so actions launched seconds apart still see each
+  other.
+
+- Everything that observes routing shows the new numbers. `bullswarm
+  assignments [--json]` is a new command listing the live ledger; `bullswarm
+  pools` gained an `inflight=<n>` column and prints its 5-hour cell as
+  `5h=<reading>%-><projected>%` when in-flight work is expected to move it,
+  with `spend`, `projectedFiveHourPct` and `projectedWeeklyPct` in `--json`;
+  `bullswarm run --dry-run` prints the forecast the pick was made on and, being
+  a preview, still registers nothing and writes no decision log; and the
+  strategy control center shows each provider's in-flight count next to its
+  usage. Live meter readings are now retained as a capped per-pool series at
+  `~/.bullswarm/meters/history/<pool>.jsonl`, because the snapshot cache keeps
+  only the newest reading and a rate needs two.
+
+- A rate is only reported once the dispatch behind it is real: at least five
+  worker-minutes must be attributable to a window before its utilization
+  counts as percentage-points-per-minute. Without that floor a pool at 26% of
+  its 5-hour window with one six-second-old agent measures as 260% per minute
+  and forecasts every provider past the burst line, which is the failure this
+  model exists to prevent rather than cause.
+
+- All of it is visible after the fact. The routing reason names the in-flight
+  counts and projections that moved the pick (`5h used 30% -> 41% projected, 2
+  in flight`, `skipped near 5h limit (projected): wati 76%`, `forecast-gated
+  at/above 90%: …`, `preferred over busier: …`), every candidate row carries
+  `pace`, `effectiveSurplus`, `inflight`, `projectedFiveHourPct`,
+  `forecastFiveHourPct`, `projectedWeeklyPct`, `ratePerMinute`,
+  `estimateSource` and `forecastGated`, and the decision log records the
+  forecast the pick was made on. Pools that carry no ledger or spend fields
+  route exactly as they did before.
+
 ## 0.25.4 — reasoning levels
 
 - A connector now declares how its own CLI expresses a thinking level, and

package/README.md

@@ -227,6 +227,49 @@ 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.
 
+Those thresholds are applied to the FORECAST, not to the last reading. A meter
+reading is already old when it arrives: agents dispatched seconds ago have
+spent quota the provider has not reported yet, and the assignment being routed
+will spend more. So each pool's projection — its reading plus the quota its
+in-flight agents are still expected to burn — gets this candidate's own
+expected consumption added, and the tiers apply to that number: a pool
+projected at or above 75% drops to the near-limit tier even while its reading
+is lower, and one projected at or above `BURST_BLOCK_PCT` (90) is left out of
+selection entirely as forecast-gated. If every capable pool is forecast-gated,
+routing still names the least loaded of them rather than stranding the action,
+and says so in the reason. A pool with no measured rate forecasts nothing and
+is never gated or deprioritized for a number nobody produced.
+
+Within a tier, pools already carrying work yield to quieter pools of similar
+pace: each pool's surplus is reduced by the weekly quota its in-flight agents
+and this assignment are expected to spend, and by at least a flat 3 surplus
+points per in-flight agent. That floor is what spreads work at real rates,
+where a six-minute agent projects to well under one point; the charge is
+labeled `penalty` when the floor set it and carries its measured basis
+(`history`, `bootstrap`) when the projection was larger. Load also beats
+incumbency: an incumbent carrying more in-flight agents than a challenger keeps
+neither its 10-point margin nor its cost protection, so the quieter pool wins
+as soon as its effective surplus is higher. A burst of parallel actions
+therefore spreads across providers instead of stacking on the single
+most-behind one.
+`bullswarm pools` shows each pool's `inflight=<n>` count and its 5-hour column
+as `5h=<reading>%-><projected>%` whenever in-flight work is expected to move
+it, `bullswarm assignments` lists what those agents are, `bullswarm run
+--dry-run` prints the forecast the pick was made on without registering
+anything, and every candidate row carries `pace`, `effectiveSurplus`,
+`inflight`, `projectedFiveHourPct`, `forecastFiveHourPct`, `ratePerMinute`,
+`estimateSource` and `forecastGated`, so a surprising pick can be read back
+number by number.
+
+The rates come from real records: every live meter reading is retained as a
+capped per-pool series (`~/.bullswarm/meters/history/<pool>.jsonl`) and paired
+with the worker-minutes dispatched between readings. Until at least five
+worker-minutes of dispatch are attributable to a window there is no rate at
+all — `null`, not a ratio of percentage points to seconds — so a fresh machine
+routes on pace and the flat penalty until it has measured something. The
+penalty itself is `config.inflightPenaltyPct` in `~/.bullswarm/state.json`
+(default 3; `0` turns the tie-breaker off).
+
 Model exclusions are hard routing policy. An excluded model is removed from
 recommendations and assignments, and Bullswarm pins a same-tier allowed model
 through the connector-owned model flag whenever the provider default could be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.25.4",
+  "version": "0.25.5",
   "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/references/operations.md

@@ -161,7 +161,65 @@ 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
+dispatch rather than frozen at launch.
+
+Those thresholds apply to the forecast, not to the reading: a pool's
+projection (its reading plus what its in-flight agents will still spend) plus
+the expected consumption of the assignment being routed. Diagnose a surprising
+pick with the numbers, in this order:
+
+```bash
+bullswarm assignments --json   # what is running right now, in every process
+bullswarm pools --json         # inflight {count, minutes, records[]} per pool
+bullswarm workflow runs show <id> --json   # routing reason + candidates
+```
+
+- `bullswarm assignments` is the ledger itself — no meters, no network. Each
+  record names the pool, source (`run` / `workflow-v1` / `workflow-v2`), run
+  and action, `startedAt`, `elapsedMinutes`, `expectedMinutes` and
+  `remainingMinutes`. An empty list with work apparently running means the
+  dispatching process never registered it; a stale-looking entry is pruned on
+  the next read once its process is gone.
+- `bullswarm pools` carries `inflight=<n>` next to each pool's `5h=<n>%`
+  reading; `--json` adds the full `inflight` block (`count`, elapsed
+  `minutes`, `remainingMinutes`, `unknownExpected`, `records[]`) and each
+  pool's `spend.fiveHour` / `spend.weekly` rates with
+  `projectedFiveHourPct` / `projectedWeeklyPct`.
+- Candidate rows (in the decision log, `workflow runs show --json`, and
+  `run --json`) explain the pick number by number: `pace` is the raw quota
+  surplus, `effectiveSurplus` is that surplus after subtracting the work the
+  pool is already carrying, `inflight` is the agent count behind it,
+  `projectedFiveHourPct` is the reading plus in-flight spend,
+  `forecastFiveHourPct` adds this assignment, `ratePerMinute` is the measured
+  5-hour burn rate, and `estimateSource` says what the adjustment was based on
+  — `history` or `bootstrap` (the measured projection exceeded the floor),
+  `penalty` (the flat 3-points-per-in-flight-agent floor set the charge, either
+  because no rate is measured or because the projection was smaller), `none`
+  (nothing to charge). An incumbent carrying more in-flight agents than a
+  challenger loses its incumbency margin and cost guard, so `why` can name a
+  pricier pool when the incumbent is the one that is loaded.
+- `forecastGated: true` means the pool was excluded because its forecast
+  reached 90%; `forecast.gated` on the result lists those names and
+  `forecast.candidateMinutes` is the duration the pick was made against. If
+  every capable pool is gated, the reason starts `every capable pool is
+  forecast-gated…` and the least-loaded one is used anyway.
+- A `null` projection or `ratePerMinute` is a pool nobody has measured yet —
+  it is deliberately never gated or deprioritized for it, so unmeasured pools
+  can look "lucky" until the model has readings for them. A rate also stays
+  `null` until at least `MIN_RATE_MINUTES` (5) of dispatch is attributable to
+  the window: percentage points divided by six seconds of work is not a rate,
+  and forecasting on it would gate every pool the moment it took its first
+  assignment.
+
+Live meter readings are retained as a capped per-pool series at
+`~/.bullswarm/meters/history/<pool>.jsonl` (500 lines) — the snapshot cache
+keeps only the newest reading, and a rate needs two. The log starts empty on
+every machine, so rates read `bootstrap` (or `null`) until enough live
+readings with dispatch between them accumulate. The flat per-in-flight-agent
+penalty is `config.inflightPenaltyPct` in `~/.bullswarm/state.json` (default
+3, `0` disables the tie-breaker).
+
+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

package/src/cli.js

@@ -27,6 +27,11 @@ import { helpForArgs, usageLine } from './help.js';
 import { disabledModelsForPool, resolveDispatchModel, selectedModelsForTier } from './lib/strategy.js';
 import { cmdDelegate } from './delegate.js';
 import { createRunHeartbeat } from './lib/run-heartbeat.js';
+import {
+  describeAssignment, expectedMinutesFromSpendModel, listAssignments,
+  registerAssignment, releaseAssignment, updateAssignment, withLedger,
+} from './lib/assignments.js';
+import { attachForecast, forecastRecord, inflightPenaltyFrom } from './lib/forecast.js';
 
 export function getBullswarmDir() {
   const h = process.env.BULLSWARM_HOME?.trim();
@@ -71,6 +76,10 @@ async function cmdPools(opts) {
     console.error(`quarantine expired, returned to service: ${released.join(', ')}`);
   }
   saveState(getBullswarmDir(), state);
+  // Current cross-process load, from the shared ledger rather than this
+  // process's own memory: work another Bullswarm started still shows here —
+  // plus the spend rates that turn that load into a projected utilization.
+  attachForecast(pools, getBullswarmDir(), { now, decisionLog: state.decisionLog ?? [] });
   if (opts.json) {
     console.log(JSON.stringify({ pools }, null, 2));
     return 0;
@@ -82,8 +91,16 @@ async function cmdPools(opts) {
       : `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}%`;
+    // routing now deprioritizes this pool for it. When in-flight work makes
+    // the projection differ from the reading, both are shown — routing decides
+    // on the right-hand number.
+    const readingPct = p.fiveHourUsedPct == null ? null : Math.round(p.fiveHourUsedPct * 10) / 10;
+    const projectedPct = p.projectedFiveHourPct == null
+      ? null
+      : Math.round(p.projectedFiveHourPct * 10) / 10;
+    const fiveHour = readingPct == null
+      ? (projectedPct == null ? '' : ` 5h=?->${projectedPct}%`)
+      : ` 5h=${readingPct}%${projectedPct != null && projectedPct !== readingPct ? `->${projectedPct}%` : ''}`;
     const nearLimit = p.nearFiveHourLimit === true ? ' NEAR-5H-LIMIT' : '';
     const status = !p.enabled
       ? 'disabled'
@@ -91,7 +108,40 @@ async function cmdPools(opts) {
         ? `QUARANTINED until ${new Date(p.quarantine.until).toLocaleTimeString()} (${p.quarantine.reason})`
         : `ready${burst}${nearLimit}`;
     console.log(
-      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'}${fiveHour} ${status}`,
+      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} inflight=${p.inflight?.count ?? 0}${fiveHour} ${status}`,
+    );
+  }
+  return 0;
+}
+
+// --- assignments --------------------------------------------------------------
+// The in-flight ledger, read straight from disk: no meters, no network, no
+// pool build — just what is running right now across every Bullswarm process.
+
+function cmdAssignments(opts) {
+  const now = Date.now();
+  const records = listAssignments(getBullswarmDir(), { now });
+  if (opts.json) {
+    console.log(JSON.stringify(
+      records.map((r) => ({ ...r, ...describeAssignment(r, now) })),
+      null,
+      2,
+    ));
+    return 0;
+  }
+  if (!records.length) {
+    console.log('no in-flight assignments');
+    return 0;
+  }
+  for (const r of records) {
+    const view = describeAssignment(r, now);
+    const work = `${r.lane ?? '?'}/${r.effort ?? '?'}`;
+    const target = [r.runId, r.actionId].filter(Boolean).join('/') || '-';
+    const expected = view.expectedMinutes == null ? 'unknown' : `${view.expectedMinutes}m`;
+    console.log(
+      `${r.pool.padEnd(14)} ${work.padEnd(14)} ${(r.source ?? '-').padEnd(11)} ${target} `
+      + `age=${view.elapsedMinutes ?? '?'}m expected=${expected} `
+      + `worker=${r.workerPid ?? 'spawning'}`,
     );
   }
   return 0;
@@ -175,6 +225,16 @@ async function cmdRun(opts) {
   for (const p of pools) {
     p.incumbent = state.incumbents?.[lane] === p.name;
   }
+  // Route on the forecast, not on the reading: what every Bullswarm process
+  // has in flight right now, and how fast each pool burns its windows. Read
+  // before the eligible-pool copies are made so the fields survive the spread.
+  attachForecast(pools, getBullswarmDir(), { now, decisionLog: state.decisionLog ?? [] });
+  // The duration this assignment is booked for — the same number the ledger
+  // will publish for it (F3), so routing and every other process agree.
+  const expected = await expectedMinutesFromSpendModel(
+    { lane, effort: effortTier },
+    { decisionLog: state.decisionLog ?? [] },
+  );
 
   // Burst gate (M3): a pool whose 5h window is >=90% used is excluded from
   // dispatch entirely this run — it paces nothing, it's just out of burst room.
@@ -199,6 +259,8 @@ async function cmdRun(opts) {
     now,
     preferredPool: state.strategy?.assignments?.[effortTier]?.pool ?? null,
     effortTier,
+    candidateMinutes: expected.expectedMinutes,
+    inflightPenaltyPct: inflightPenaltyFrom(state),
   });
   if (gated.length && route.pick) {
     route.why += ` (burst-gated: ${gated.map((g) => g.name).join(', ')})`;
@@ -209,12 +271,16 @@ async function cmdRun(opts) {
     // A preview never writes: the decision log records dispatches, not what
     // an operator merely asked to see.
     if (!dryRun) {
-      logDecision(state, { lane, picked: null, keepOnClaude: true, ok: null, why: route.why });
+      logDecision(state, {
+        lane, picked: null, keepOnClaude: true, ok: null, why: route.why,
+        forecast: forecastRecord(route, null),
+      });
       saveState(getBullswarmDir(), state);
     }
     emit({
       ok: true, keepOnClaude: true, ...(dryRun ? { dryRun: true } : {}),
       why: route.why, pick: { pool: null, command: null },
+      forecast: forecastRecord(route, null), candidates: route.candidates,
     }, opts);
     return 0;
   }
@@ -255,11 +321,15 @@ async function cmdRun(opts) {
   if (dryRun) {
     // Preview through argvWithModel — the same builder runDelegate uses — so
     // the printed command can never drift from the one that would be spawned.
+    // The forecast is reported exactly as a real dispatch would route on it;
+    // F1 keeps the preview a pure read — no ledger entry, no decision log.
     emit({
       ok: true,
       dryRun: true,
       keepOnClaude: false,
       why: route.why,
+      forecast: forecastRecord(route, connector.name),
+      candidates: route.candidates,
       pick: {
         pool: connector.name,
         model: selectedModel,
@@ -278,6 +348,17 @@ async function cmdRun(opts) {
 
   const heartbeat = createRunHeartbeat({ intervalSec: heartbeatSec });
   heartbeat.start();
+  // Registered the moment the pool is picked, before the worker exists, so no
+  // other process sees this pool as idle while the CLI is still spawning. The
+  // expectation is the one routing already booked this assignment for (F3).
+  const ledgerEntry = withLedger(() => registerAssignment(getBullswarmDir(), {
+    pool: connector.name,
+    model: selectedModel ?? connector.model ?? null,
+    lane: lane ?? null,
+    effort: effortTier ?? null,
+    source: 'run',
+    ...expected,
+  }));
   let verdict;
   try {
     verdict = await watchOnce(runtimeConnector, taskText, targetDir, paths, {
@@ -293,9 +374,13 @@ async function cmdRun(opts) {
       bullswarmDir: getBullswarmDir(),
       onActivity: (event) => heartbeat.activity(event),
       onAgentEvent: () => heartbeat.event(),
+      onSpawn: (pid) => {
+        if (ledgerEntry) withLedger(() => updateAssignment(getBullswarmDir(), ledgerEntry.id, { workerPid: pid }));
+      },
     });
   } finally {
     heartbeat.stop();
+    if (ledgerEntry) withLedger(() => releaseAssignment(getBullswarmDir(), ledgerEntry.id));
   }
 
   // Persist incumbency on success; quarantine hint on auth failure.
@@ -323,6 +408,11 @@ async function cmdRun(opts) {
     reasoning,
     usage: verdict.meta?.usage ?? null,
     outFile: paths.outFile,
+    // The forecast this pick was made on — the numbers pickPool compared, so a
+    // later reader can replay the decision instead of re-deriving it. The full
+    // candidate list stays out of the log: 500 entries of it would bloat the
+    // state file the spend model has to read on every dispatch.
+    forecast: forecastRecord(route, connector.name),
   });
   saveState(getBullswarmDir(), state);
 
@@ -352,6 +442,19 @@ function emit(verdict, opts) {
     if (Array.isArray(verdict.pick?.command) && verdict.dryRun) {
       console.log(`command: ${verdict.pick.command.join(' ')}`);
     }
+    // The forecast the pick was made on, so a preview explains itself without
+    // --json: what the pool is already carrying, where its 5h window is headed
+    // once this assignment runs, and what that estimate is based on.
+    if (verdict.forecast && verdict.dryRun) {
+      const f = verdict.forecast;
+      console.log(
+        `forecast: inflight=${f.inflight} `
+        + `5h ${f.projectedFiveHourPct ?? '?'}%->${f.forecastFiveHourPct ?? '?'}% `
+        + `expected=${f.expectedMinutes == null ? 'unknown' : `${f.expectedMinutes}m`} `
+        + `rate=${f.ratePerMinute == null ? 'unmeasured' : `${f.ratePerMinute}%/min`} `
+        + `basis=${f.estimateSource ?? 'none'}`,
+      );
+    }
     if (verdict.reasoning?.applied) {
       const clamped = verdict.reasoning.clamped ? ', clamped' : '';
       console.log(`reasoning: ${verdict.reasoning.applied} (${verdict.reasoning.source}${clamped})`);
@@ -584,6 +687,8 @@ export async function main(argv) {
       return cmdHealth(opts);
     case 'pools':
       return cmdPools(opts);
+    case 'assignments':
+      return cmdAssignments(opts);
     case 'doctor':
       return cmdDoctor(opts);
     case 'workflow':

package/src/help.js

@@ -66,7 +66,8 @@ const top = rich({
     { name: 'delegate', desc: 'classify any task, preview the execution shape, and route it to one agent or a workflow' },
     { name: 'run', desc: 'dispatch one bounded task' },
     { name: 'health', desc: 're-judge saved delegate outputs' },
-    { name: 'pools', desc: 'show routing pools, meters, and quarantine state' },
+    { name: 'pools', desc: 'show routing pools, meters, in-flight load, and quarantine state' },
+    { name: 'assignments', desc: 'list the work in flight right now across every Bullswarm process' },
     { name: 'strategy', desc: 'discover models and manage tier assignments' },
     { name: 'doctor', desc: 'report installation readiness' },
     { name: 'workflow', desc: 'create, execute, observe, and audit workflows' },
@@ -272,17 +273,19 @@ const runText = rich({
     { flag: '--reasoning <low|medium|high|xhigh|max|default>', desc: "run-wide thinking-level override, clamped to what the picked pool's connector accepts; `default` passes nothing and lets the delegate CLI's own configuration decide", default: 'strategy reasoning setting for the effort tier, else the connector default' },
     { flag: '--timeout <seconds>', desc: 'hard wall-clock kill timer for the delegate process', default: 'none — the delegate is allowed to run to completion' },
     { flag: '--heartbeat <seconds>', desc: 'print one compact progress heartbeat to stderr per interval without streaming delegate output', default: 'off' },
-    { flag: '--dry-run', desc: 'print the routing decision and the exact command that would be spawned (including the resolved reasoning flag) without spawning it or writing the decision log', default: 'off (dispatches for real)' },
+    { flag: '--dry-run', desc: 'print the routing decision, the forecast it was made on, and the exact command that would be spawned (including the resolved reasoning flag) without spawning it, registering an in-flight assignment, or writing the decision log', default: 'off (dispatches for real)' },
     { flag: '--json', desc: 'print the machine-readable verdict document', default: 'human-readable summary line' },
   ],
   safety: [
     'spawns a real external coding-agent CLI process rooted at --add-dir (never with --dry-run)',
     'writes ~/.bullswarm/state.json (decision log, pool incumbency) on completion; --dry-run writes neither',
+    'registers the picked pool in the shared in-flight ledger (~/.bullswarm/assignments/) for the life of the run and releases it when the attempt ends; --dry-run registers nothing',
     'may quarantine a pool for a period after an authentication failure',
   ],
   examples: [
     { cmd: 'bullswarm run --lane analyze --add-dir . "List every TODO comment in src/ with file:line"', note: 'routes one bounded analysis task and prints the verdict' },
     { cmd: 'bullswarm run --lane build --add-dir . --reasoning max --dry-run --json "Refactor the loader"', note: 'shows the exact argv, including the clamped reasoning flag, without dispatching' },
+    { cmd: 'bullswarm run --lane build --add-dir . --dry-run "Refactor the loader"', note: 'prints a `forecast:` line — inflight count, projected 5h percent before and after this assignment, its expected minutes, the measured burn rate, and the basis of that estimate' },
   ],
   next: 'bullswarm health to re-judge saved outputs, or bullswarm pools to check routing/quota state before the next run.',
 });
@@ -347,18 +350,43 @@ const healthText = rich({
 const poolsText = rich({
   usage: 'bullswarm pools [--force] [--json]',
   purpose: 'Show every configured pool: cost rank, lanes, live meter usage/elapsed percentage, '
-    + 'pace surplus, and quarantine/burst-gate status.',
+    + 'pace surplus, in-flight assignment count, projected 5-hour utilization, and '
+    + 'quarantine/burst-gate status. The 5-hour column reads `5h=<reading>%` alone when '
+    + 'nothing is in flight and `5h=<reading>%-><projected>%` when in-flight work is '
+    + 'expected to push the window further; routing decides on the right-hand number.',
   args: [],
   options: [
     { flag: '--force', desc: 'bypass the meter cache and re-read live usage for every pool', default: 'off (cached meter readings reused within their TTL)' },
-    { flag: '--json', desc: 'machine-readable pool array', default: 'human-readable aligned table' },
+    { flag: '--json', desc: 'machine-readable pool array, each entry carrying inflight {count, minutes, remainingMinutes, unknownExpected, records[]}, spend {fiveHour, weekly} rates with their source and sample count, and projectedFiveHourPct / projectedWeeklyPct', default: 'human-readable aligned table' },
   ],
   safety: [
     'calls each connector\'s live usage meter (network request per metered pool) to compute used/elapsed percentages',
     'always writes state.json after sweeping expired quarantines back into service, even in --json mode',
+    'reading the in-flight ledger prunes entries left behind by crashed processes (dead pids, or older than 12 hours)',
   ],
   examples: [{ cmd: 'bullswarm pools --force' }],
-  next: 'bullswarm doctor for a pass/fail readiness report instead of raw pool state.',
+  next: 'bullswarm assignments to see which run and action each in-flight entry belongs to.',
+});
+
+const assignmentsText = rich({
+  usage: 'bullswarm assignments [--json]',
+  purpose: 'List the work in flight RIGHT NOW across every Bullswarm process — one line per '
+    + 'live assignment with its pool, lane/effort, source, run/action, age in minutes, expected '
+    + 'duration, and worker pid. This is the shared ledger `bullswarm pools` counts as '
+    + 'inflight=<n>, so a run started by another terminal or kernel appears here too.',
+  args: [],
+  options: [
+    { flag: '--json', desc: 'machine-readable array of live assignment records', default: 'one human-readable line per assignment' },
+  ],
+  safety: [
+    'reads ~/.bullswarm/assignments/ only — no meters, no network, no pool build',
+    'prunes entries whose kernel and worker processes are both gone, and entries older than 12 hours, so a crashed process leaves no phantom load',
+  ],
+  examples: [
+    { cmd: 'bullswarm assignments' },
+    { cmd: 'bullswarm assignments --json', note: 'each record carries pool, source, runId, actionId, kernelPid, workerPid, startedAt, elapsedMinutes, expectedMinutes, remainingMinutes' },
+  ],
+  next: 'bullswarm pools to see that same load next to each pool\'s meter and pace surplus.',
 });
 
 const doctorText = rich({
@@ -1522,6 +1550,7 @@ const HELP = {
   delegate: { _text: delegateText },
   health: { _text: healthText },
   pools: { _text: poolsText },
+  assignments: { _text: assignmentsText },
   doctor: { _text: doctorText },
   version: { _text: versionText },
   release: { _text: releaseText },