bullswarm 0.28.5 → 0.28.7

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # bullswarm changelog
 
+## 0.28.7 — pools about to reset spend their leftover first
+
+- routing: quota that expires sooner is worth more. A pool whose pacing window
+  resets within 24 hours (weekly) or 3 days (monthly) is now ranked on urgency
+  — its effective surplus divided by the fraction of the window still to run —
+  ahead of every pool whose window is not about to close, instead of on the
+  surplus alone. At 2026-09-11 12:26 HKT the medium lane went to
+  `claude-code:wati` (+22.9 points, 13h33m and 8.1% of its week left) over
+  `grok` (+13.8 points, 2h02m and 1.2% left, urgency ~1150 against wati's
+  ~283), and grok's points expired unspent two hours later; the owner had been
+  pinning grok by hand for such runs. Three states for an expiring pool:
+  `urgent` (surplus still to spend and a pacing forecast — the reading plus
+  in-flight work plus this candidate, each clipped at the reset — below 95%,
+  with 5 points of extra headroom demanded when no spend rate was measured),
+  which outranks incumbency and a configured effort assignment but never a
+  strict pin or the 5-hour rules; `draining` (forecast at/above 95%), ranked
+  behind every normal pool so a window about to be emptied is not fed one more
+  run; and `normal` (on or ahead of pace), ranked exactly as today. A pool with
+  no parsable `paceResetsAt`, a reset already past, or any other window is
+  never expiring soon and nothing about it changes. `bullswarm pools` ends an
+  expiring pool's line with `resets in 2h02m EXPIRING-SOON urgency=1150`, and
+  each routing candidate row carries `paceResetsInMinutes`, `expiringSoon`,
+  `urgency`, `forecastPacingPct` and `urgencyState`.
+
+## 0.28.6 — the 5-hour near-limit line reads the clock
+
+- routing: the 5-hour near-limit line is now clock-relative. A pool is
+  deprioritized only when its 5h forecast is at/above 75% AND ahead of the
+  share of the 5h window that has already elapsed. On 2026-09-10 at 22:19Z a
+  high-tier integrator skipped `claude-code:wati` (81% used, 23 minutes to the
+  reset — 92.3% of the window elapsed, 88.1% projected) and
+  `claude-code:petsona` (75.3% projected, 85.7% elapsed) and went to the one
+  account already ahead of its weekly pace, while wati still held 34% of its
+  weekly quota unspent with 13% of the week left to spend it. Both pools now keep the lane:
+  88.1% with 23 minutes left is a pool spending at the clock's pace, not a pool
+  about to hit a wall. Pools with no `resets_at`, an unparsable one, or a reset
+  already past keep the fixed 75% line, and the 90% burst gate is unchanged —
+  it ignores the clock. The routing reason and the `candidates[]` rows say
+  which case applied: `5h used 81% -> 88.1% projected, under the clock (92.3%
+  elapsed)`, `skipped near 5h limit (projected): claude-code:wati 88.1% (20.0%
+  elapsed)`, and a new `fiveHourElapsedPct` field. `bullswarm pools` shows the
+  same clock: `5h=81% (92% elapsed)`.
+- routing: 5-hour spend is clipped at the reset. Quota spent after the window
+  rolls over lands in the next window, so the candidate's minutes and each
+  in-flight record's remaining minutes are charged to the 5h forecast only up
+  to `fiveHourResetsAt` — 10 minutes from a reset, a 40-minute task at 0.5
+  points per minute adds 5 points to the forecast, not 20. The weekly/monthly
+  pacing charge is deliberately not clipped: that spend counts against its
+  window whichever side of the 5h reset it lands on.
+
 ## 0.28.5 — narrow-terminal detail panes use the whole screen
 
 - tui: on a narrow terminal (under 100 columns, e.g. a phone over SSH) the

package/package.json

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

package/src/cli.js

@@ -3,7 +3,9 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
-import { pickPool } from './lib/route.js';
+import {
+  expiringSoonView, fiveHourElapsedPct, formatResetsIn, pickPool,
+} from './lib/route.js';
 import { argvWithModel, watchOnce } from './lib/watch.js';
 import {
   isReasoningLevel, REASONING_DEFAULT, REASONING_LEVELS, resolveReasoningLevel,
@@ -113,17 +115,29 @@ async function cmdPools(opts) {
     const projectedPct = p.projectedFiveHourPct == null
       ? null
       : Math.round(p.projectedFiveHourPct * 10) / 10;
+    // R10: the same reading means different things at different points in the
+    // window, so show where the window stands when the provider reported it.
+    const elapsed = fiveHourElapsedPct(p);
+    const clock = elapsed == null ? '' : ` (${Math.round(elapsed)}% elapsed)`;
     const fiveHour = readingPct == null
-      ? (projectedPct == null ? '' : ` 5h=?->${projectedPct}%`)
-      : ` 5h=${readingPct}%${projectedPct != null && projectedPct !== readingPct ? `->${projectedPct}%` : ''}`;
+      ? (projectedPct == null ? '' : ` 5h=?->${projectedPct}%${clock}`)
+      : ` 5h=${readingPct}%${projectedPct != null && projectedPct !== readingPct ? `->${projectedPct}%` : ''}${clock}`;
     const nearLimit = p.nearFiveHourLimit === true ? ' NEAR-5H-LIMIT' : '';
+    // R11: a pacing window about to reset is quota about to be lost, so say
+    // when it closes and how urgent what is left has become. Pools whose
+    // window is not closing soon print nothing extra.
+    const expiring = expiringSoonView(p, { now });
+    const expiringNote = expiring.expiringSoon
+      ? ` resets in ${formatResetsIn(expiring.minutesToReset)} EXPIRING-SOON`
+        + ` urgency=${Math.round(expiring.urgency)}`
+      : '';
     const status = !p.enabled
       ? 'disabled'
       : p.quarantine
         ? `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 ?? '-'} inflight=${p.inflight?.count ?? 0}${fiveHour} ${status}`,
+      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} inflight=${p.inflight?.count ?? 0}${fiveHour} ${status}${expiringNote}`,
     );
   }
   return 0;

package/src/help.js

@@ -324,11 +324,17 @@ const poolsText = rich({
     + '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.',
+    + 'expected to push the window further; routing decides on the right-hand number. '
+    + 'A trailing `(<n>% elapsed)` is how much of that 5-hour window has already run: '
+    + 'routing only deprioritizes a near-limit pool whose usage is ahead of its clock. '
+    + 'A pool whose weekly window resets within 24 hours, or whose monthly window resets '
+    + 'within 3 days, ends its line with `resets in <Nd Nh|Nh Nm|Nm> EXPIRING-SOON '
+    + 'urgency=<n>`: quota about to be lost, scored as surplus divided by the fraction '
+    + 'of the window still to run, which is what routing ranks it on.',
   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, each entry carrying inflight {count, minutes, remainingMinutes, unknownExpected, records[]}, spend {fiveHour, weekly, monthly, pacing} rates with their source and sample count, pacingWindow, and projectedFiveHourPct / projectedWeeklyPct / projectedMonthlyPct / projectedPacingPct', default: 'human-readable aligned table' },
+    { flag: '--json', desc: 'machine-readable pool array, each entry carrying inflight {count, minutes, remainingMinutes, unknownExpected, records[]}, spend {fiveHour, weekly, monthly, pacing} rates with their source and sample count, pacingWindow, paceResetsAt, and projectedFiveHourPct / projectedWeeklyPct / projectedMonthlyPct / projectedPacingPct', default: 'human-readable aligned table' },
   ],
   safety: [
     'calls each connector\'s live usage meter (network request per metered pool) to compute used/elapsed percentages',

package/src/lib/route.js

@@ -15,10 +15,12 @@
 //   R6. A pool at 100% used is exhausted; quarantined pools are ineligible
 //       until their quarantine expires (the re-probe path).
 //   R7. 5h headroom outranks pace: a pool at/above FIVE_HOUR_NEAR_LIMIT_PCT of
-//       its 5h window is chosen only when no eligible pool below the threshold
-//       exists for the lane. Like quarantine and burst gates, this outranks an
-//       explicit assignment and incumbency — a near-limit pool that is picked
-//       anyway spends the run's next attempt on a quota failure.
+//       its 5h window AND above that window's elapsed share (R10 — the
+//       threshold is clock-relative, not a fixed line) is chosen only when no
+//       eligible pool below the threshold exists for the lane. Like quarantine
+//       and burst gates, this outranks an explicit assignment and incumbency —
+//       a near-limit pool that is picked anyway spends the run's next attempt
+//       on a quota failure.
 //   R8. Route on the FORECAST, not on the reading. A reading is already old at
 //       the moment it is read: work dispatched seconds ago has spent quota the
 //       meter has not seen, and the assignment being routed will spend more.
@@ -34,8 +36,63 @@
 //   R9. Load beats incumbency: an incumbent carrying more in-flight agents
 //       than a challenger keeps neither its margin nor its cost guard; the
 //       quieter pool wins as soon as its effective surplus is higher.
+//  R10. The near-limit line is clock-relative. R7's tier is for a pool that
+//       will hit its 5h wall mid-run, and that danger is time-shaped: 88%
+//       projected with 23 minutes left in the window is a pool spending at its
+//       own pace that is about to be handed a fresh window; 77% with four
+//       hours left is a pool heading for the wall. So a pool is deprioritized
+//       only when its forecast is at/above FIVE_HOUR_NEAR_LIMIT_PCT *and*
+//       above the percentage of the 5h window already elapsed. (Observed
+//       2026-09-10T22:19Z: claude-code:wati, 81% used with 23 minutes left —
+//       92.3% of its window elapsed — was tiered down for a forecast of 88.1%,
+//       so a high-tier integrator went to the one account already ahead of its
+//       weekly pace while wati's quota, 34% of the week unspent with 13% of
+//       the week left, expired unused.) Spend that lands after the reset
+//       belongs to the NEXT window: the candidate's minutes and each in-flight
+//       record's remaining minutes are clipped at resets_at before they are
+//       charged to the 5h forecast — the weekly/monthly pacing penalty is
+//       never clipped, that spend does count against its window. No
+//       resets_at, an unparsable one, or a reset already in the past means no
+//       clock: R7 keeps its fixed line and nothing is clipped, because a pool
+//       is never treated differently for a number nobody produced (R8).
+//  R11. Quota that expires sooner is worth more ("expiring soon"). A pace
+//       surplus is a difference in points and says nothing about how long the
+//       pool has left to spend it. (Observed 2026-09-11T04:26Z: grok held
+//       +13.8 weekly points with 2h02m left in its week — 1.2% of the window —
+//       while claude-code:wati held +22.9 with 13h33m left (8.1%). R2 sent the
+//       run to wati on 22.9 > 13.8, and grok's 15 points expired two hours
+//       later; the owner had been pinning grok by hand.) So a pool whose
+//       PACING window resets within a fixed lead time — EXPIRING_SOON_MS: 24
+//       hours weekly, 3 days monthly, the owner's chosen values, about a
+//       seventh of a week and a tenth of a month — is ranked on
+//       urgency = effective surplus / the fraction of its window still to run
+//       (floored at MIN_WINDOW_LEFT_FRACTION so a reset seconds away cannot
+//       divide by zero) instead of on the surplus alone. Three states:
+//         urgent   — surplus still to spend and a pacing forecast (the
+//                    reading, plus in-flight work and this candidate, each
+//                    clipped at the pacing reset exactly as R10 clips the 5h
+//                    window) below PACING_FORECAST_BLOCK_PCT; with no measured
+//                    rate the reading must also sit 5 points under that line,
+//                    because an unmeasured pool's forecast is only its
+//                    reading. Ranks ahead of every pool not expiring soon.
+//         draining — forecast at/above the line: ranked after every normal
+//                    pool and chosen only when nothing else is eligible, so a
+//                    pool about to be emptied is not fed one more run that
+//                    would push it over the wall.
+//         normal   — expiring soon but on or ahead of pace: ranked with
+//                    everyone else on effective surplus, exactly as today.
+//       Urgency outranks incumbency (R3/R4/R9) and a configured effort
+//       assignment (preferredPool) by the same mechanism R7's tier uses —
+//       selection happens among the urgent pools while one exists — so an
+//       urgent challenger needs neither the 10-point margin nor the cost
+//       guard. It never overrides a strict pin (workflow strictPool filters
+//       the pool list before pickPool ever sees it), and never the 5h rules:
+//       a pool tiered down by R7/R10 or gated by R8 is not rescued by
+//       urgency. No pacing window, no parsable paceResetsAt, a reset already
+//       in the past, or any window other than weekly/monthly means there is
+//       no lead time to measure and nothing about the pool changes (R8).
 
-import { FIVE_HOUR_NEAR_LIMIT_PCT, BURST_BLOCK_PCT } from '../meters/framework.js';
+import { FIVE_HOUR_NEAR_LIMIT_PCT, BURST_BLOCK_PCT, WINDOW_MS } from '../meters/framework.js';
 // One strict numeric coercion for the whole codebase (src/lib/num.js): a
 // missing measurement stays null instead of becoming a confident zero.
 import { finiteOrNull as num } from './num.js';
@@ -54,6 +111,40 @@ export const INCUMBENCY_MARGIN = 10; // surplus points a challenger must beat
  */
 export const DEFAULT_INFLIGHT_PENALTY_PCT = 3;
 
+/**
+ * R11 lead times: how close a pacing window's reset has to be before the pool
+ * counts as "expiring soon". The owner's chosen values — roughly a seventh of
+ * a week and a tenth of a month — long enough that a run dispatched now can
+ * still use the quota, short enough that the pool really is about to lose it.
+ * Any window that is not one of these keys is never expiring soon.
+ */
+export const EXPIRING_SOON_MS = {
+  weekly: 24 * 3600_000,
+  monthly: 72 * 3600_000,
+};
+
+/**
+ * Pacing-window forecast at/above which an expiring-soon pool is `draining`
+ * rather than `urgent`: its window is about to close AND about to be emptied,
+ * so one more run spends the run's next attempt on a quota failure.
+ */
+export const PACING_FORECAST_BLOCK_PCT = 95;
+
+/**
+ * Smallest window-left fraction urgency will divide by (0.5% of the window).
+ * A reset thirty seconds away is 0.005% of a week: without a floor the score
+ * would be Infinity-shaped and one pool would swallow every lane.
+ */
+export const MIN_WINDOW_LEFT_FRACTION = 0.005;
+
+/**
+ * Points of headroom an UNMEASURED expiring-soon pool needs below
+ * PACING_FORECAST_BLOCK_PCT to be called urgent. With no spend rate its
+ * forecast is only its reading plus a flat penalty, so the last few points
+ * before the line are exactly where that estimate is least trustworthy.
+ */
+export const UNMEASURED_URGENT_HEADROOM_PCT = 5;
+
 export function elapsedPct(meter, now = Date.now()) {
   if (!meter || meter.type === 'none') return 0;
   const start = meter.windowStart ?? 0;
@@ -100,36 +191,115 @@ function tenth(value) {
   return Math.round(Number(value) * 10) / 10;
 }
 
+/** The 5h window, in minutes — 300. */
+export const FIVE_HOUR_WINDOW_MINUTES = WINDOW_MS['5h'] / 60_000;
+
+/**
+ * Minutes left before this pool's 5h window resets, from the provider's
+ * `fiveHourResetsAt` (src/lib/config.js, straight off the meter reading).
+ *
+ * null when there is no reading, when it cannot be parsed, or when the reset
+ * is already at/behind `now` — an outrun deadline is unknown, not a
+ * zero-length window (R8/R10).
+ */
+export function minutesUntilFiveHourReset(pool, now = Date.now()) {
+  const resetsAtMs = Date.parse(pool?.fiveHourResetsAt ?? '');
+  if (!Number.isFinite(resetsAtMs)) return null;
+  const minutes = (resetsAtMs - now) / 60_000;
+  return minutes > 0 ? minutes : null;
+}
+
+/**
+ * How much of the 5h window has already elapsed, 0–100, or null when the
+ * reset time is unknown (R10). elapsed = 100 × (300 − minutes left) / 300.
+ */
+export function fiveHourElapsedPct(pool, now = Date.now()) {
+  const left = minutesUntilFiveHourReset(pool, now);
+  if (left == null) return null;
+  const elapsed = (100 * (FIVE_HOUR_WINDOW_MINUTES - left)) / FIVE_HOUR_WINDOW_MINUTES;
+  return Math.max(0, Math.min(100, elapsed));
+}
+
+/**
+ * In-flight minutes that fall PAST the 5h reset, summed over the records the
+ * producer already charged to this window (R10). Only these minutes are
+ * credited back from the projection — the rest of the record still spends
+ * inside the window being forecast.
+ */
+function inflightOverflowMinutes(pool, minutesToReset) {
+  const records = Array.isArray(pool?.inflight?.records) ? pool.inflight.records : [];
+  let overflow = 0;
+  for (const record of records) {
+    const m = num(record?.remainingMinutes);
+    if (m == null) continue;
+    overflow += Math.max(0, Math.max(0, m) - minutesToReset);
+  }
+  return overflow;
+}
+
 /**
  * 5h forecast for one pool and the assignment being routed (R8 rule a):
  *
  *   forecast = (projectedFiveHourPct ?? fiveHourUsedPct)
- *              + fiveHour.ratePerMinute × candidateMinutes
+ *              − ratePerMinute × in-flight minutes past the reset
+ *              + ratePerMinute × min(candidateMinutes, minutes to the reset)
  *
  * with the candidate term added only when both of its numbers exist; anything
  * else falls back to the best available reading, and a pool with no reading
  * at all forecasts null (unknown — never gated, never deprioritized).
  *
+ * R10 clipping: quota spent after `fiveHourResetsAt` lands in the NEXT 5h
+ * window and cannot overflow this one, so the candidate's minutes are clipped
+ * at the reset, and the in-flight minutes the producer charged past the reset
+ * are credited back out of its projection (never below the pool's own
+ * reading). This clip is the 5h forecast's alone — the pacing-window charge in
+ * inflightLoad() is deliberately left unclipped, because that spend does count
+ * against the weekly/monthly window whichever side of the 5h reset it lands
+ * on. With no parsable reset time nothing is clipped at all.
+ *
  * `forecasted` records whether the number is more than the raw reading. Only a
  * real projection input (a producer-supplied projectedFiveHourPct, or a rate ×
  * candidateMinutes term) turns a reading into a forecast; a bare reading keeps
  * exactly its old meaning so nothing changes for callers that attach no model.
  *
+ * `nearLimit` is the raw R7 test (forecast >= FIVE_HOUR_NEAR_LIMIT_PCT);
+ * `underClock` is R10's exemption from it — near the limit, but no further
+ * into the window's quota than into the window's time.
+ *
  * @param {object} pool
  * @param {number|null} [candidateMinutes] expected minutes of this assignment
+ * @param {number} [now]
  * @returns {{raw: number|null, projected: number|null,
  *            ratePerMinute: number|null, candidateAdd: number|null,
- *            forecast: number|null, forecasted: boolean}}
+ *            forecast: number|null, forecasted: boolean,
+ *            minutesToReset: number|null, elapsedPct: number|null,
+ *            inflightCreditPct: number, nearLimit: boolean,
+ *            underClock: boolean}}
  */
-export function fiveHourForecast(pool, candidateMinutes = null) {
+export function fiveHourForecast(pool, candidateMinutes = null, now = Date.now()) {
   const raw = num(pool?.fiveHourUsedPct);
   const projected = num(pool?.projectedFiveHourPct);
   const ratePerMinute = num(pool?.spend?.fiveHour?.ratePerMinute);
   const minutes = num(candidateMinutes);
-  const base = projected ?? raw;
+  const minutesToReset = minutesUntilFiveHourReset(pool, now);
+  const clip = (m) => (minutesToReset == null ? m : Math.min(m, minutesToReset));
   const candidateAdd =
-    ratePerMinute != null && minutes != null ? ratePerMinute * minutes : null;
+    ratePerMinute != null && minutes != null ? ratePerMinute * clip(minutes) : null;
+  // Credit back only what the producer charged past the reset; a zero credit
+  // leaves the projection byte-for-byte what it was before R10.
+  const overflowMinutes =
+    minutesToReset == null || ratePerMinute == null
+      ? 0
+      : inflightOverflowMinutes(pool, minutesToReset);
+  const inflightCreditPct = overflowMinutes > 0 ? ratePerMinute * overflowMinutes : 0;
+  const base =
+    projected == null ? raw
+    : inflightCreditPct > 0
+      ? Math.max(raw ?? projected - inflightCreditPct, projected - inflightCreditPct)
+      : projected;
   const forecast = base == null ? null : base + (candidateAdd ?? 0);
+  const elapsedPct = fiveHourElapsedPct(pool, now);
+  const nearLimit = forecast != null && forecast >= FIVE_HOUR_NEAR_LIMIT_PCT;
   return {
     raw,
     projected,
@@ -137,6 +307,13 @@ export function fiveHourForecast(pool, candidateMinutes = null) {
     candidateAdd,
     forecast,
     forecasted: projected != null || candidateAdd != null,
+    minutesToReset,
+    elapsedPct,
+    inflightCreditPct,
+    nearLimit,
+    // R10: at/above the line but no further through its quota than through its
+    // window — the reset arrives before the wall does.
+    underClock: nearLimit && elapsedPct != null && forecast <= elapsedPct,
   };
 }
 
@@ -167,6 +344,12 @@ export function fiveHourForecast(pool, candidateMinutes = null) {
  * elapsed worker-minutes (src/lib/assignments.js attachInflight), which says
  * nothing about the quota still to be spent.
  *
+ * These minutes are NOT clipped at the 5h reset (R10). This charge is the
+ * pacing window's — weekly or monthly — and an agent still running an hour
+ * after the 5h window rolls over goes on spending the same weekly quota. Only
+ * the 5h forecast in fiveHourForecast() clips at `fiveHourResetsAt`, and it
+ * computes that separately from this number.
+ *
  * estimateSource: `none` (nothing to charge), `penalty` (the flat floor set the
  * charge), or the source label of the rate that was used (`history` /
  * `bootstrap`, from `spend.pacing` or `spend.weekly`) when the measured
@@ -184,9 +367,7 @@ export function inflightLoad(pool, opts = {}) {
   const count = Math.max(0, num(pool?.inflight?.count) ?? 0);
   // The pacing window's rate, or the weekly one when that window has no
   // measured rate — the surplus and the penalty stay on the same window.
-  const paced = num(pool?.spend?.pacing?.ratePerMinute) != null
-    ? pool.spend.pacing
-    : pool?.spend?.weekly ?? null;
+  const paced = pacingRateBlock(pool);
   const rate = num(paced?.ratePerMinute);
   const minutes = num(candidateMinutes);
   const penaltyPct = num(inflightPenaltyPct) ?? DEFAULT_INFLIGHT_PENALTY_PCT;
@@ -229,6 +410,201 @@ export function inflightLoad(pool, opts = {}) {
   return { count, penalty, ratePerMinute: rate, estimateSource };
 }
 
+/**
+ * The spend block whose rate paces this pool: `spend.pacing` when it carries a
+ * measured rate, else `spend.weekly`. Charging a weekly rate against a monthly
+ * surplus would compare points from two different windows, so this is the only
+ * fallback — and it is the one inflightLoad() has always used, shared here so
+ * the pacing forecast (R11) charges the same rate the ranking charges.
+ */
+function pacingRateBlock(pool) {
+  return num(pool?.spend?.pacing?.ratePerMinute) != null
+    ? pool.spend.pacing
+    : pool?.spend?.weekly ?? null;
+}
+
+/**
+ * Minutes until this pool's PACING window (weekly or monthly) resets, from
+ * `pool.paceResetsAt` (src/lib/config.js, straight off the meter reading).
+ *
+ * null when there is no reading, when it cannot be parsed, or when the reset
+ * is already at/behind `now` — an outrun deadline is unknown, not a
+ * zero-length window (R8/R11). The 5h twin is minutesUntilFiveHourReset().
+ */
+export function minutesUntilPacingReset(pool, now = Date.now()) {
+  const resetsAtMs = Date.parse(pool?.paceResetsAt ?? '');
+  if (!Number.isFinite(resetsAtMs)) return null;
+  const minutes = (resetsAtMs - now) / 60_000;
+  return minutes > 0 ? minutes : null;
+}
+
+/** `5d22h`, `2h02m`, `45m` — how long a window has left, for humans (R11). */
+export function formatResetsIn(minutes) {
+  const total = Math.max(0, Math.round(num(minutes) ?? 0));
+  const days = Math.floor(total / 1440);
+  const hours = Math.floor((total % 1440) / 60);
+  const mins = total % 60;
+  if (days > 0) return `${days}d${hours}h`;
+  if (hours > 0) return `${hours}h${String(mins).padStart(2, '0')}m`;
+  return `${mins}m`;
+}
+
+/**
+ * In-flight minutes that fall INSIDE the pacing window still to run — the
+ * complement of inflightOverflowMinutes(). Everything after the reset is the
+ * next window's problem (R11, mirroring R10).
+ */
+function inflightMinutesWithin(pool, minutesToReset) {
+  const records = Array.isArray(pool?.inflight?.records) ? pool.inflight.records : [];
+  let inside = 0;
+  for (const record of records) {
+    const m = num(record?.remainingMinutes);
+    if (m == null) continue;
+    const kept = Math.max(0, m);
+    inside += minutesToReset == null ? kept : Math.min(kept, minutesToReset);
+  }
+  return inside;
+}
+
+/**
+ * What this pool's PACING window (weekly or monthly) will read once the work
+ * it is already carrying and the assignment being routed have landed (R11):
+ *
+ *   forecast = (projectedPacingPct ?? usedPct)
+ *              − ratePerMinute × in-flight minutes past the pacing reset
+ *              + ratePerMinute × min(candidateMinutes, minutes to the reset)
+ *
+ * Spend that lands after the reset belongs to the NEXT window, so both terms
+ * are clipped at `paceResetsAt` exactly as fiveHourForecast() clips at the 5h
+ * one: the producer's projection (src/lib/spend.js) charges every remaining
+ * in-flight minute to this window, and the minutes past the reset are credited
+ * back out of it — never below the pool's own reading. When the producer
+ * attached no projection the same in-flight minutes are added to the reading
+ * instead, which is the identical number by another route.
+ *
+ * With no measured rate there is nothing to multiply by: the forecast is the
+ * reading plus the flat per-agent penalty inflightLoad() already charges, and
+ * a pool with no reading at all forecasts null (unknown — R8).
+ *
+ * @returns {{raw: number|null, projected: number|null,
+ *            ratePerMinute: number|null, candidateAdd: number|null,
+ *            inflightCreditPct: number, minutesToReset: number|null,
+ *            forecast: number|null}}
+ */
+export function pacingForecast(pool, candidateMinutes = null, now = Date.now(), opts = {}) {
+  const { inflightPenaltyPct = DEFAULT_INFLIGHT_PENALTY_PCT } = opts;
+  const raw = num(pool?.usedPct);
+  const projected = num(pool?.projectedPacingPct);
+  const ratePerMinute = num(pacingRateBlock(pool)?.ratePerMinute);
+  const minutes = num(candidateMinutes);
+  const minutesToReset = minutesUntilPacingReset(pool, now);
+  const base = projected ?? raw;
+  const empty = {
+    raw, projected, ratePerMinute, candidateAdd: null, inflightCreditPct: 0, minutesToReset,
+  };
+  if (base == null) return { ...empty, forecast: null };
+  if (ratePerMinute == null) {
+    const count = Math.max(0, num(pool?.inflight?.count) ?? 0);
+    const penaltyPct = num(inflightPenaltyPct) ?? DEFAULT_INFLIGHT_PENALTY_PCT;
+    return { ...empty, forecast: base + count * penaltyPct };
+  }
+  const clip = (m) => (minutesToReset == null ? m : Math.min(m, minutesToReset));
+  const candidateAdd = minutes == null ? 0 : ratePerMinute * clip(Math.max(0, minutes));
+  const overflowMinutes =
+    minutesToReset == null ? 0 : inflightOverflowMinutes(pool, minutesToReset);
+  const inflightCreditPct = overflowMinutes > 0 ? ratePerMinute * overflowMinutes : 0;
+  const carried =
+    projected == null
+      ? raw + ratePerMinute * inflightMinutesWithin(pool, minutesToReset)
+      : inflightCreditPct > 0
+        ? Math.max(raw ?? projected - inflightCreditPct, projected - inflightCreditPct)
+        : projected;
+  return {
+    ...empty,
+    candidateAdd,
+    inflightCreditPct,
+    forecast: carried + candidateAdd,
+  };
+}
+
+/**
+ * R11 view of one pool: is its pacing window about to close, how urgent is the
+ * quota it still holds, and what will that window read once in-flight work and
+ * this candidate land.
+ *
+ * `effective` is the ranking's own `pace − load.penalty`; pickPool passes the
+ * number it already computed, and any other caller (bullswarm pools) lets this
+ * recompute it from the pool.
+ *
+ * `windowLeftFraction` is (100 − elapsedPct) / 100, floored at
+ * MIN_WINDOW_LEFT_FRACTION. A pool whose reading carries no elapsedPct has no
+ * measured window position, so the fraction is 1 and urgency is just the
+ * surplus — never inflated for a number nobody produced (R8).
+ *
+ * @returns {{expiringSoon: boolean, window: string|null,
+ *            minutesToReset: number|null, windowLeftFraction: number|null,
+ *            effective: number|null, urgency: number|null,
+ *            forecast: number|null, ratePerMinute: number|null,
+ *            state: 'urgent'|'normal'|'draining'|null}}
+ */
+export function expiringSoonView(pool, opts = {}) {
+  const {
+    now = Date.now(),
+    candidateMinutes = null,
+    inflightPenaltyPct = DEFAULT_INFLIGHT_PENALTY_PCT,
+    effective = null,
+  } = opts;
+  const window = pool?.pacingWindow ?? null;
+  const leadMs = EXPIRING_SOON_MS[window] ?? null;
+  const minutesToReset = minutesUntilPacingReset(pool, now);
+  const notSoon = {
+    expiringSoon: false,
+    window,
+    minutesToReset,
+    windowLeftFraction: null,
+    effective: null,
+    urgency: null,
+    forecast: null,
+    ratePerMinute: null,
+    state: null,
+  };
+  if (leadMs == null || minutesToReset == null || minutesToReset * 60_000 > leadMs) {
+    return notSoon;
+  }
+
+  const eff =
+    num(effective)
+    ?? paceScore(pool, now) - inflightLoad(pool, { candidateMinutes, inflightPenaltyPct }).penalty;
+  const elapsed = num(pool?.elapsedPct);
+  const windowLeftFraction = Math.max(
+    MIN_WINDOW_LEFT_FRACTION,
+    elapsed == null ? 1 : (100 - elapsed) / 100,
+  );
+  const pacing = pacingForecast(pool, candidateMinutes, now, { inflightPenaltyPct });
+  const forecast = pacing.forecast;
+  const used = num(pool?.usedPct);
+  // An unmeasured pool's forecast is its reading: demand real headroom before
+  // handing it the lane ahead of everyone else.
+  const trusted =
+    pacing.ratePerMinute != null ||
+    (used != null && used <= PACING_FORECAST_BLOCK_PCT - UNMEASURED_URGENT_HEADROOM_PCT);
+  const state =
+    forecast != null && forecast >= PACING_FORECAST_BLOCK_PCT ? 'draining'
+    : eff > 0 && forecast != null && trusted ? 'urgent'
+    : 'normal';
+  return {
+    expiringSoon: true,
+    window,
+    minutesToReset,
+    windowLeftFraction,
+    effective: eff,
+    urgency: eff / windowLeftFraction,
+    forecast,
+    ratePerMinute: pacing.ratePerMinute,
+    state,
+  };
+}
+
 export function isExhausted(pool) {
   // Flat shape (buildPools) first, legacy meter shape second. A stale
   // meterSource reading must not permanently exclude a pool: if the reading
@@ -307,31 +683,50 @@ export function pickPool(lane, pools, opts = {}) {
   const eligible = laneCapable.filter((p) => p.modelPolicy?.eligible !== false);
 
   const scored = eligible.map((p) => {
-    const forecast = fiveHourForecast(p, candidateMins);
+    const forecast = fiveHourForecast(p, candidateMins, now);
     const load = inflightLoad(p, { candidateMinutes: candidateMins, inflightPenaltyPct });
     const pace = paceScore(p, now);
+    // R8c: pace minus the quota this pool's in-flight work and this
+    // assignment are expected to spend. Equals pace when nothing is in
+    // flight and no rate applies.
+    const effective = pace - load.penalty;
+    // R11: the same surplus, divided by how much of the pacing window is left
+    // to spend it in. All-null for a pool whose window is not about to close.
+    const expiring = expiringSoonView(p, {
+      now, candidateMinutes: candidateMins, inflightPenaltyPct, effective,
+    });
     return {
       pool: p,
       pace,
-      // R8c: pace minus the quota this pool's in-flight work and this
-      // assignment are expected to spend. Equals pace when nothing is in
-      // flight and no rate applies.
-      effective: pace - load.penalty,
+      effective,
       load,
       forecast,
-      // R8b: R7's tier, applied to the forecast instead of the reading.
-      tier: forecast.forecast != null && forecast.forecast >= FIVE_HOUR_NEAR_LIMIT_PCT ? 1 : 0,
+      expiring,
+      // urgent first, draining last, everything else in the middle — the tier
+      // R11 adds under R7's 5h tier and above the pace comparison.
+      urgencyRank: expiring.state === 'urgent' ? 0 : expiring.state === 'draining' ? 2 : 1,
+      // R8b: R7's tier, applied to the forecast instead of the reading — and
+      // R10: only for a pool further through its 5h quota than through its 5h
+      // window. A pool at 88% with 23 minutes left keeps its tier 0.
+      tier: forecast.nearLimit && !forecast.underClock ? 1 : 0,
       // A pool is gated only by a FORECAST at/above the burst line — a bare
       // reading keeps its current meaning (dispatch owns that gate), so pools
       // without a spend model behave exactly as before.
       gated: forecast.forecasted && forecast.forecast != null && forecast.forecast >= BURST_BLOCK_PCT,
     };
   });
-  // R8 before R7 before R2: forecast-gated pools last, then 5h headroom, then
-  // most-behind-after-load within the tier. The candidate list is reported in
-  // this exact preference order.
+  // R8 before R7 before R11 before R2: forecast-gated pools last, then 5h
+  // headroom, then urgent < normal < draining, then the group's own score —
+  // urgency among the urgent, most-behind-after-load everywhere else. The
+  // candidate list is reported in this exact preference order.
   scored.sort(
-    (a, b) => (a.gated ? 1 : 0) - (b.gated ? 1 : 0) || a.tier - b.tier || b.effective - a.effective,
+    (a, b) =>
+      (a.gated ? 1 : 0) - (b.gated ? 1 : 0) ||
+      a.tier - b.tier ||
+      a.urgencyRank - b.urgencyRank ||
+      (a.urgencyRank === 0
+        ? b.expiring.urgency - a.expiring.urgency
+        : b.effective - a.effective),
   );
 
   const candidates = scored.map((e) => ({
@@ -345,6 +740,9 @@ export function pickPool(lane, pools, opts = {}) {
     fiveHourUsedPct: e.forecast.raw,
     projectedFiveHourPct: e.forecast.projected,
     forecastFiveHourPct: e.forecast.forecast == null ? null : tenth(e.forecast.forecast),
+    // R10: how far into the 5h window this reading sits; null when the
+    // provider reported no reset time, in which case the fixed line applies.
+    fiveHourElapsedPct: e.forecast.elapsedPct == null ? null : tenth(e.forecast.elapsedPct),
     projectedWeeklyPct: num(e.pool.projectedWeeklyPct),
     // The window this pool is paced by, and the projection in it. Equal to
     // the weekly pair for every pool that declares no monthly quota window.
@@ -354,6 +752,16 @@ export function pickPool(lane, pools, opts = {}) {
     estimateSource: e.load.estimateSource,
     nearFiveHourLimit: e.tier === 1,
     forecastGated: e.gated,
+    // R11: when the pacing window resets, whether that is close enough to
+    // count, and the urgency/forecast that decided the pool's standing. Every
+    // field but the first is null for a pool whose window is not about to
+    // close — nothing changes for a number nobody produced (R8).
+    paceResetsInMinutes:
+      e.expiring.minutesToReset == null ? null : tenth(e.expiring.minutesToReset),
+    expiringSoon: e.expiring.expiringSoon,
+    urgency: e.expiring.urgency == null ? null : tenth(e.expiring.urgency),
+    forecastPacingPct: e.expiring.forecast == null ? null : tenth(e.expiring.forecast),
+    urgencyState: e.expiring.state,
   }));
   const gatedNames = scored.filter((e) => e.gated).map((e) => e.pool.name);
   const forecastReport = { candidateMinutes: candidateMins, gated: gatedNames };
@@ -393,6 +801,7 @@ export function pickPool(lane, pools, opts = {}) {
 
   let winnerEntry;
   let skippedNearLimit = [];
+  let skippedDraining = [];
   if (allGated) {
     winnerEntry = [...scored].sort(
       (a, b) =>
@@ -402,9 +811,21 @@ export function pickPool(lane, pools, opts = {}) {
   } else {
     // R7: selection happens only among pools with 5h headroom while any exists.
     const withHeadroom = open.filter((e) => e.tier === 0);
-    const selectable = withHeadroom.length ? withHeadroom : open;
+    const headroomSet = withHeadroom.length ? withHeadroom : open;
     skippedNearLimit = withHeadroom.length ? open.filter((e) => e.tier === 1) : [];
 
+    // R11, by the same mechanism and one rung below it: while any pool's
+    // quota is about to expire with room to spend it, that pool is the only
+    // selectable one — which is what puts urgency ahead of incumbency and of
+    // a configured effort assignment, both of which are resolved inside
+    // `selectable` below. A draining pool is the mirror image: out of
+    // selection until nothing else is left.
+    const urgentSet = headroomSet.filter((e) => e.urgencyRank === 0);
+    const notDraining = headroomSet.filter((e) => e.urgencyRank !== 2);
+    const selectable =
+      urgentSet.length ? urgentSet : notDraining.length ? notDraining : headroomSet;
+    skippedDraining = notDraining.length ? headroomSet.filter((e) => e.urgencyRank === 2) : [];
+
     const preferredEntry = preferredPool
       ? selectable.find((entry) => entry.pool.name === preferredPool)
       : null;
@@ -459,6 +880,7 @@ export function pickPool(lane, pools, opts = {}) {
     preferred: !allGated && Boolean(preferredPool) && winnerEntry.pool.name === preferredPool,
     effortTier: opts.effortTier,
     skippedNearLimit,
+    skippedDraining,
     gated: allGated ? [] : gatedEntries,
     gatedFallback: allGated,
     yieldedBusier,
@@ -535,6 +957,7 @@ function routingReason(
     preferred,
     effortTier,
     skippedNearLimit = [],
+    skippedDraining = [],
     gated = [],
     gatedFallback = false,
     yieldedBusier = [],
@@ -554,10 +977,21 @@ function routingReason(
     base = `configured ${effortTier ?? 'effort'} assignment (${
       [winnerEntry.pool.name, note, inflight].filter(Boolean).join(', ')
     })`;
+  } else if (winnerEntry.urgencyRank === 0) {
+    // R11: this pool did not win on the size of its surplus but on how little
+    // time is left to spend it, so the reason names the clock, the fraction of
+    // the window still to run, and the forecast that kept it out of draining.
+    base = urgencyClause(winnerEntry, [note, inflight].filter(Boolean).join(', '));
   } else {
-    base = `most-behind capable pool${
-      note ? (winnerEntry.tier === 0 ? ' with 5h headroom' : ' near its 5h limit') : ''
-    } (${detail})`;
+    // Three states, not two (R10): headroom, near the limit and tiered down,
+    // or near the limit but under the window's clock — where the note itself
+    // carries the explanation, so the label stays out of its way.
+    const standing =
+      !note ? ''
+      : winnerEntry.tier === 1 ? ' near its 5h limit'
+      : winnerEntry.forecast.underClock ? ''
+      : ' with 5h headroom';
+    base = `most-behind capable pool${standing} (${detail})`;
   }
   const clauses = [base];
   if (skippedNearLimit.length) {
@@ -573,6 +1007,15 @@ function routingReason(
       `forecast-gated at/above ${BURST_BLOCK_PCT}%: ${gated.map((e) => poolPctLabel(e)).join(', ')}`,
     );
   }
+  if (skippedDraining.length) {
+    // R11: a pool whose window is about to close was passed over anyway,
+    // because the run would spend what little it has left through the wall.
+    clauses.push(
+      `expiring but draining (forecast >= ${PACING_FORECAST_BLOCK_PCT}%): ${skippedDraining
+        .map((e) => `${e.pool.name} ${pacingPctText(e)}`)
+        .join(', ')}`,
+    );
+  }
   if (yieldedBusier.length) {
     clauses.push(
       `preferred over busier: ${yieldedBusier
@@ -583,21 +1026,67 @@ function routingReason(
   return clauses.join(' · ');
 }
 
-/** `<pool> <pct>%` using the forecast when one exists, else the raw reading. */
+/**
+ * R11's reason for an urgent winner:
+ * `expiring soon: grok resets in 2h02m, surplus 13.8 over 1.2% of the week
+ * left → urgency 1140, forecast 91.0%`. Urgency reads as a whole number: at
+ * this scale a tenth of a point is noise, and the candidate row carries the
+ * rounded value for anything that needs it.
+ */
+function urgencyClause(entry, detail) {
+  const { minutesToReset, windowLeftFraction, urgency, window } = entry.expiring;
+  const word = window === 'monthly' ? 'month' : 'week';
+  const left = tenth(windowLeftFraction * 100);
+  const tail = detail ? ` (${detail})` : '';
+  return (
+    `expiring soon: ${entry.pool.name} resets in ${formatResetsIn(minutesToReset)}, `
+    + `surplus ${tenth(entry.effective)} over ${left}% of the ${word} left `
+    + `→ urgency ${Math.round(urgency)}, forecast ${pacingPctText(entry)}${tail}`
+  );
+}
+
+/** `91.0%` — an expiring-soon pool's pacing forecast, or `?%` with no reading. */
+function pacingPctText(entry) {
+  const pct = entry.expiring.forecast;
+  return pct == null ? '?%' : `${Number(pct).toFixed(1)}%`;
+}
+
+/**
+ * `<pool> <pct>%` using the forecast when one exists, else the raw reading —
+ * and, for a pool at/above the near-limit line, where its 5h window stands
+ * (R10): `claude-code:wati 88.1% (92.3% elapsed)`. The clock is what decided
+ * the tier, so the number that decided it is named.
+ */
 function poolPctLabel(entry) {
   const pct = entry.forecast.forecasted ? entry.forecast.forecast : entry.forecast.raw;
-  return `${entry.pool.name}${pct == null ? '' : ` ${tenth(pct)}%`}`;
+  const clock = entry.forecast.nearLimit ? elapsedText(entry.forecast.elapsedPct) : null;
+  return `${entry.pool.name}${pct == null ? '' : ` ${tenth(pct)}%`}${clock ? ` (${clock})` : ''}`;
+}
+
+/** `92.3% elapsed`, or null when the provider reported no 5h reset time. */
+function elapsedText(elapsedPct) {
+  return elapsedPct == null ? null : `${Number(elapsedPct).toFixed(1)}% elapsed`;
 }
 
-/** `5h used 30%` or, when a forecast adds to it, `5h used 30% -> 41% projected`. */
+/**
+ * `5h used 30%` or, when a forecast adds to it, `5h used 30% -> 41% projected`.
+ *
+ * A forecast at/above the near-limit line also carries its window's clock —
+ * `, under the clock (92.3% elapsed)` when R10 exempts it from the tier,
+ * `, 20.0% elapsed` when the clock is what put it there.
+ */
 function fiveHourNote(entry) {
-  const { raw, forecast, forecasted } = entry.forecast;
+  const { raw, forecast, forecasted, nearLimit, underClock, elapsedPct } = entry.forecast;
+  const clock = nearLimit ? elapsedText(elapsedPct) : null;
+  const suffix = clock ? `, ${underClock ? `under the clock (${clock})` : clock}` : '';
   if (raw == null) {
-    return forecasted && forecast != null ? `5h projected ${tenth(forecast)}%` : null;
+    return forecasted && forecast != null ? `5h projected ${tenth(forecast)}%${suffix}` : null;
   }
   const reading = `5h used ${tenth(raw)}%`;
-  if (!forecasted || forecast == null || tenth(forecast) === tenth(raw)) return reading;
-  return `${reading} -> ${tenth(forecast)}% projected`;
+  if (!forecasted || forecast == null || tenth(forecast) === tenth(raw)) {
+    return `${reading}${suffix}`;
+  }
+  return `${reading} -> ${tenth(forecast)}% projected${suffix}`;
 }
 
 /** `2 in flight`, or null when the caller tracks no in-flight work here. */