bullswarm 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # bullswarm changelog
 
+## 0.28.1 — summary bytes on the wire, monthly pacing
+
+- `workflow runs result <id> --summary` was budgeted by `fitResultSummary`
+  against compact `JSON.stringify(summary)` (`RESULT_SUMMARY_BYTE_BUDGET =
+  4096` in `src/workflow/v2-outcome.js`) but `jsonOut` printed
+  `JSON.stringify(obj, null, 2)`, so the bytes on the wire exceeded the
+  budget. `--summary` now prints compact single-line JSON
+  (`JSON.stringify(obj)` in `src/workflow/runs-cli.js`); `--json` without
+  `--summary` still pretty-prints the full envelope, and `--summary --json`
+  stays identical to `--summary`. Measured on
+  `tests/fixtures/real-result-ze5xz2.json` through the summariser / CLI:
+  compact `--summary` is 3,786 bytes
+  (`tests/workflow-result-summary.test.js` prints `result-summary size:
+  full=57141 summary=3786`; same figure as
+  `Buffer.byteLength(JSON.stringify(summarizeV2Result(fixture)))`); the
+  full envelope as `--json` prints it is 60,709 bytes
+  (`JSON.stringify(envelope, null, 2)` plus the trailing newline
+  `console.log` adds — `tests/workflow-result-summary.test.js` prints
+  `result-summary cli: prettyFull=60709`).
+
+- Routing paced every pool by `windows.seven_day ?? windows.monthly`
+  (`paceSnapshot` in `src/meters/framework.js`), so command-code — whose real
+  budget is a monthly credit allocation — was paced by its weekly rate-limit
+  window. Live meter, captured 2026-09-09T10:45:28Z and evaluated at
+  2026-09-09T11:09:44.982Z: weekly `used 73.1% elapsed 91.8% surplus +18.7`
+  against monthly `used 79.4% elapsed 75.3% surplus -4.1`, with 14.43 of 70
+  credits left for the 7.66 days to the 2026-09-17T03:06:55Z reset. Routing
+  therefore called it "the most-behind capable pool" and kept sending it work
+  while its monthly budget was already 4.1 points overspent. Pacing is now per
+  pool: `pacingWindowFor({connector, subscription})` resolves
+  `state.strategy.subscriptions[pool].quotaWindow`, then
+  `connector.subscription.quotaWindow`, normalised to `weekly` | `monthly` |
+  `null` (any other label — including a pre-0.28.1 free-text one — is ignored
+  for pacing and keeps the old weekly-first order). `paceSnapshot(snapshot,
+  nowMs, {pacingWindow})` takes `monthly` → `windows.monthly ??
+  windows.seven_day`, `weekly`/`null` → `windows.seven_day ??
+  windows.monthly`, and returns `pacingWindow` naming the window actually
+  used. `src/lib/config.js` `buildPools` resolves the choice once per pool
+  (where the connector and the state both are) and re-paces `usedPct`,
+  `elapsedPct`, `pace` and `paceResetsAt` off `reading.windows`, so cache,
+  stale and live readings are paced identically; the pool view carries
+  `pacingWindow`. The 5h gate is untouched: `command-code` still gates on 5h
+  `25.2%`. Connectors already declared this — `command-code` and the kaihk
+  pools `monthly`, `claude-code`/`codex`/`grok` `weekly`; nothing read it for
+  pacing before.
+- The spend model follows the pacing window. `WINDOW_KEYS` (framework.js)
+  gains `monthly: {snapshot: 'monthly', history: 'monthly', windowMs: null}`,
+  and `rateForWindow` (`src/lib/spend.js`) derives the bootstrap window start
+  with `meta.windowMs ?? monthlyWindowMs(resetsAtMs)` — the calendar month
+  ending at the provider's `resets_at` (M2), never an assumed 30 days.
+  `attachSpend` now writes `pool.spend.monthly` and `pool.projectedMonthlyPct`
+  next to the fiveHour/weekly fields, plus `pool.spend.pacing = {window,
+  ratePerMinute, source, samples}` and `pool.projectedPacingPct` for the
+  window that paces the pool (default `weekly`, so a pool that declares
+  nothing keeps its old numbers). `inflightLoad` (`src/lib/route.js`) charges
+  the in-flight penalty from `spend.pacing?.ratePerMinute ??
+  spend.weekly?.ratePerMinute` with that rate's own source label, so the
+  surplus and the penalty are measured in the same window; candidate rows gain
+  `pacingWindow` and `projectedPacingPct` beside the unchanged
+  `projectedWeeklyPct`.
+- Operator control and display. `bullswarm strategy set-subscription <pool>
+  --quota-window <weekly|monthly>` now selects the window that paces routing
+  (help text in `src/help.js`) and validates it: anything else exits 2 with
+  `--quota-window must be weekly or monthly (or unknown to clear)`, and
+  `unknown` clears the override back to the connector's declaration. Labels
+  already stored are ignored for pacing, never rejected on read. `bullswarm
+  pools` names the window in the meter column — `cmd-fixture    cost=5
+  lanes=chore monthly used 79.4% elapsed 75.3% [cache] surplus=-4.1
+  inflight=0 5h=25.2% ready` — and `pools --json` entries carry
+  `pacingWindow`. `strategy refresh`/`show` print the window on each
+  subscription line (`command-code: GOAT · ... · monthly 79.4% used · surplus
+  -4.1`) and carry `pacingWindow` next to the free-text `quotaWindow` label in
+  `--json`; `strategy inventory --json` carries it per provider.
+- Tests: 738 -> 750, 0 failures. The new behaviour is covered in
+  `tests/meters.test.js` (the live command-code snapshot as a fixture, the
+  helper's precedence, `buildPools` pacing), `tests/spend.test.js` (monthly
+  bootstrap window start, `spend.pacing`/`projectedPacingPct`),
+  `tests/route.test.js` (the penalty on the pacing window; weekly-only pools
+  unchanged), `tests/strategy-cli.test.js` (`--quota-window` validation) and
+  `tests/assignments.test.js` (the `pools` meter column and `--json`
+  `pacingWindow`).
+
 ## 0.28.0 — context diet
 
 - `workflow runs result <id> --summary` prints a compact status-loop
@@ -77,9 +159,10 @@
   39,288; compact `JSON.stringify` of the parsed envelope is 57,141.
   `summarizeV2Result` of that fixture is 3,786 bytes —
   `tests/workflow-result-summary.test.js` prints `result-summary size:
-  full=57141 summary=3786`. The 0.28.0 goal recorded the integrator's
-  inputs as 60,790 bytes; `wc -c` of the seven dependency out-files under
-  `.diet-inputs/` sums to 46,022 (out-surface 18,659, out-routing-cleanup
+  full=57141 summary=3786` (numbers re-measured in 0.28.1). The 0.28.0
+  goal recorded the integrator's inputs as 60,790 bytes; `wc -c` of the
+  seven dependency out-files under `.diet-inputs/` sums to 46,022
+  (out-surface 18,659, out-routing-cleanup
   10,202, out-state-bugs 7,052, out-docs 6,831, out-dead-kernel 1,377,
   out-verify-gate 974, out-dead-code 927) and the integrator task file is
   14,768 (`wc -c .diet-inputs/task-integrate-attempt-1.md`), which

package/README.md

@@ -51,7 +51,12 @@ 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. The
+   *cheaper* pool. Lanes are work-nature, never hard-coded to pools. Which
+   window paces one pool is the subscription window that pool's connector
+   declares (`quotaWindow`: weekly for claude-code, codex and grok; monthly
+   for command-code and the kaihk pools), overridable per pool with
+   `bullswarm strategy set-subscription <pool> --quota-window <weekly|monthly>`
+   — `bullswarm pools` names it in the meter column. 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.
@@ -656,6 +661,10 @@ These are UTF-8 byte counts, never tokens.
 requirement as `{ id, status, mandatory, evidenceCount, why }`, each action as
 `{ id, kind, lane, effort, status, pool, model, reasoning, wallSec, outFile,
 bytes }`, `concerns: { count, first }`, `usage`, and `next: { full, runDir, outputs }` — every output name is a basename inside `next.runDir`.
+`--summary` is single-line JSON (`JSON.stringify`), so the bytes on the wire
+match the 4,096-byte fitter budget. As printed by the CLI on
+`tests/fixtures/real-result-ze5xz2.json`, the compact summary is 3,786 bytes
+and the pretty full envelope (`--json` alone) is 60,709 bytes.
 The full `bullswarm.workflow.result.v2` envelope is unchanged and remains the
 default. Read it (`--json` alone) on a failed or partial run, or before judging
 evidence. A terminal `workflow watch` prints the same compact command as

package/package.json

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

@@ -249,8 +249,17 @@ bullswarm workflow runs show <id> --json   # routing reason + candidates
 - `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`.
+  pool's `spend.fiveHour` / `spend.weekly` / `spend.monthly` / `spend.pacing`
+  rates with `projectedFiveHourPct` / `projectedWeeklyPct` /
+  `projectedMonthlyPct` / `projectedPacingPct`.
+- The meter column names the window the pool is paced by, e.g.
+  `command-code   cost=1 lanes=analyze/build/chore monthly used 79.4% elapsed
+  75.3% [cache] surplus=-4.1 ...`. That window is the connector's declared
+  `quotaWindow` (monthly for command-code and the kaihk pools, weekly for
+  claude-code, codex and grok), overridable with `bullswarm strategy
+  set-subscription <pool> --quota-window <weekly|monthly>`; `pools --json`
+  carries it as `pacingWindow`, and `used%`/`elapsed%`/`surplus` are that
+  window's. The 5h reading still only gates.
 - `bullswarm strategy rungs --json` answers "what would this pool actually run
   on this tier, and what did it cost last time" in one row per pool and effort
   tier: the effective model and its source, the effective reasoning level and

package/src/cli.js

@@ -96,9 +96,14 @@ async function cmdPools(opts) {
   }
   for (const p of pools) {
     const src = p.meterSource;
+    // Name the window the numbers came from: `used`/`elapsed` mean different
+    // things for a weekly-paced and a monthly-paced pool, and the surplus
+    // routing compares is this window's. Only a real window reading is
+    // labeled — a declared meter has a number but no window.
+    const window = p.pacingWindow && p.elapsedPct != null ? `${p.pacingWindow} ` : '';
     const meter = src === 'none'
       ? 'unmetered'
-      : `used ${p.usedPct ?? '?'}% elapsed ${p.elapsedPct ?? '?'}% [${src}]`;
+      : `${window}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. When in-flight work makes

package/src/help.js

@@ -328,7 +328,7 @@ const poolsText = rich({
   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} rates with their source and sample count, and projectedFiveHourPct / projectedWeeklyPct', 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, 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',
@@ -660,15 +660,16 @@ const strategyIncludeModelText = rich({
 });
 
 const strategySetSubscriptionText = rich({
-  usage: 'bullswarm strategy set-subscription <pool> [--plan <name>] [--monthly-usd <n|unknown>] [--included-usd <n|unknown>] [--quota-window <name>]',
+  usage: 'bullswarm strategy set-subscription <pool> [--plan <name>] [--monthly-usd <n|unknown>] [--included-usd <n|unknown>] [--quota-window <weekly|monthly|unknown>]',
   purpose: "Record known subscription pricing for a pool so refresh's value-multiple math "
-    + '(included value vs. monthly cost) is accurate.',
+    + '(included value vs. monthly cost) is accurate, and choose the quota window '
+    + 'routing paces this pool by.',
   args: [{ name: '<pool>', desc: 'connector/pool name to record economics for' }],
   options: [
     { flag: '--plan <name>', desc: 'plan label to record', default: 'unchanged' },
     { flag: '--monthly-usd <n|unknown>', desc: 'monthly subscription price', default: 'unchanged' },
     { flag: '--included-usd <n|unknown>', desc: 'estimated included usage value', default: 'unchanged' },
-    { flag: '--quota-window <name>', desc: 'label for the quota reset window', default: 'unchanged' },
+    { flag: '--quota-window <weekly|monthly>', desc: 'the subscription window that PACES routing for this pool (used% vs elapsed% of it); unknown clears it back to the connector default', default: 'unchanged' },
   ],
   safety: ['writes state.strategy.subscriptions[pool] and invalidates the cached report'],
   examples: [{ cmd: 'bullswarm strategy set-subscription claude --plan max --monthly-usd 200 --included-usd 1000' }],

package/src/lib/config.js

@@ -8,6 +8,13 @@
 // Pace source (doctrine M2): the pacing object carries elapsed% computed
 // from the provider's resets_at. Declared meters fall back to the local
 // elapsed estimate and are visibly labeled.
+//
+// Pacing window (doctrine M3): WHICH window paces a pool is the pool's own
+// subscription window — `state.strategy.subscriptions[pool].quotaWindow`,
+// else `connector.subscription.quotaWindow` — resolved here, where both the
+// state and the connector are in hand, so a cache, stale or live reading is
+// paced identically. `p.pacingWindow` names the window the numbers on the
+// pool view actually came from.
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -15,7 +22,7 @@ import { loadState } from './state.js';
 import { paceScore, isQuarantined } from './route.js';
 // One strict numeric coercion for the whole codebase (src/lib/num.js).
 import { finiteOrNull } from './num.js';
-import { FIVE_HOUR_NEAR_LIMIT_PCT } from '../meters/framework.js';
+import { FIVE_HOUR_NEAR_LIMIT_PCT, pacingWindowFor, pickPacingWindow } from '../meters/framework.js';
 import { expandClaudeAccountConnectors } from './claude-accounts.js';
 import { expandOpenCodeKaihkConnectors } from './opencode-kaihk.js';
 
@@ -79,6 +86,13 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
       usedPct: null,
       elapsedPct: null,
       pace: null,
+      // The subscription window that paces this pool, before any reading:
+      // the operator's setting, else the connector's declaration, else null
+      // (default order). Replaced below by the window a reading really used.
+      pacingWindow: pacingWindowFor({
+        connector: conn,
+        subscription: state.strategy?.subscriptions?.[name] ?? null,
+      }),
       burstGate: false,
       // 5h window (doctrine M3): gates routing, never paces it.
       fiveHourUsedPct: null,
@@ -112,13 +126,15 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
       p.fiveHourResetsAt = fiveHour.resetsAt;
       p.nearFiveHourLimit = fiveHour.nearLimit;
     }
-    if (reading?.pacing) {
+    const paced = pacedReading(reading, p.pacingWindow);
+    if (paced) {
       // Provider-truth path (M1/M2)
       p.meterSource = reading.source; // live | cache | stale
-      p.usedPct = reading.pacing.usedPct;
-      p.elapsedPct = reading.pacing.elapsedPct;
-      p.pace = reading.pacing.surplus; // surplus = elapsed − used
-      p.paceResetsAt = reading.pacing.resetsAt;
+      p.usedPct = paced.pacing.usedPct;
+      p.elapsedPct = paced.pacing.elapsedPct;
+      p.pace = paced.pacing.surplus; // surplus = elapsed − used
+      p.paceResetsAt = paced.pacing.resetsAt;
+      p.pacingWindow = paced.window;
       p.burstGate = reading.burstGate === true;
       p.meterSnapshot = reading.snapshot ?? null;
     } else {
@@ -139,6 +155,28 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
   return { state, connectors, pools };
 }
 
+/**
+ * The window of a reading that paces this pool, and its name.
+ *
+ * `reading.windows` carries every window the provider reported, so the choice
+ * is made here rather than re-deriving it: 'monthly' takes monthly and falls
+ * back to weekly, anything else keeps the historical weekly-first order.
+ * A reading assembled without `windows` (a hand-built one, or an older code
+ * path) still carries `pacing`, which is used as-is — its window name is
+ * whatever the producer labeled, else the pool's declaration.
+ *
+ * @returns {{pacing: object, window: 'weekly'|'monthly'|null}|null}
+ */
+function pacedReading(reading, pacingWindow) {
+  if (!reading) return null;
+  if (reading.windows) {
+    const chosen = pickPacingWindow(reading.windows, pacingWindow);
+    if (chosen.pacing) return chosen;
+  }
+  if (!reading.pacing) return null;
+  return { pacing: reading.pacing, window: reading.pacingWindow ?? pacingWindow ?? 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

package/src/lib/forecast.js

@@ -74,8 +74,9 @@ export function attachForecast(pools, bullswarmDir, opts = {}) {
 }
 
 /**
- * The flat surplus points charged per in-flight agent when no weekly spend
- * rate is known, from core state when an operator configured one.
+ * The flat surplus points charged per in-flight agent when no spend rate is
+ * known for the pool's pacing window, from core state when an operator
+ * configured one.
  * `config.inflightPenaltyPct: 0` disables the tie-breaker entirely; anything
  * unusable falls back to route.js's documented default.
  */

package/src/lib/route.js

@@ -45,8 +45,9 @@ export const LANES = ['analyze', 'build', 'chore'];
 export const INCUMBENCY_MARGIN = 10; // surplus points a challenger must beat
 
 /**
- * Surplus points charged per in-flight agent when no weekly spend rate is
- * known for the pool. It is a tie-breaker, not a measurement: three points is
+ * Surplus points charged per in-flight agent when no spend rate is known for
+ * the pool's pacing window (or, failing that, its weekly one). It is a
+ * tie-breaker, not a measurement: three points is
  * under a third of INCUMBENCY_MARGIN, so it separates pools of similar pace
  * without ever overturning a real quota difference. Callers override it with
  * opts.inflightPenaltyPct.
@@ -140,30 +141,37 @@ export function fiveHourForecast(pool, candidateMinutes = null) {
 }
 
 /**
- * Weekly cost of the work a pool is already carrying plus the work being
- * routed to it (R8 rule c). The result is subtracted from the pace surplus so
- * that, between pools of similar pace, the quieter one wins.
+ * Pacing-window cost of the work a pool is already carrying plus the work
+ * being routed to it (R8 rule c). The result is subtracted from the pace
+ * surplus so that, between pools of similar pace, the quieter one wins.
+ *
+ * The rate is read from `spend.pacing` — the rate for the window this pool is
+ * actually paced by — and falls back to `spend.weekly` when no pacing rate is
+ * known (a pool paced monthly with no monthly rate, or a producer that
+ * attached only the weekly one). Charging a weekly rate against a monthly
+ * surplus would compare points from two different windows.
  *
  * Two bases, and the larger one is charged:
- *   1. a known weekly rate: rate × each in-flight record's remainingMinutes,
+ *   1. a known rate: rate × each in-flight record's remainingMinutes,
  *      plus rate × candidateMinutes — real projected percentage points (an
  *      in-flight agent whose remaining minutes nobody recorded is charged
  *      inflightPenaltyPct instead);
  *   2. the floor: inflightPenaltyPct per in-flight agent — a documented flat
  *      default, labeled `penalty` so no reader mistakes it for a measurement.
- * The floor exists because at real weekly rates (about 0.05 points per
- * worker-minute) a six-minute agent projects to under a point, which cannot
- * spread a burst across a pace gap of a few points; the measured projection
- * only ever raises the charge above the floor.
+ * The floor exists because at real subscription-window rates (about 0.05
+ * points per worker-minute) a six-minute agent projects to under a point,
+ * which cannot spread a burst across a pace gap of a few points; the measured
+ * projection only ever raises the charge above the floor.
  *
  * Only `inflight.records[].remainingMinutes` is read: `inflight.minutes` is
  * elapsed worker-minutes (src/lib/assignments.js attachInflight), which says
  * nothing about the quota still to be spent.
  *
  * estimateSource: `none` (nothing to charge), `penalty` (the flat floor set the
- * charge), or the producer's own `spend.weekly.source` label (`history` /
- * `bootstrap`) when the measured projection exceeded the floor; null when a
- * rate was used but the producer labeled no provenance for it.
+ * charge), or the source label of the rate that was used (`history` /
+ * `bootstrap`, from `spend.pacing` or `spend.weekly`) when the measured
+ * projection exceeded the floor; null when a rate was used but the producer
+ * labeled no provenance for it.
  *
  * @returns {{count: number, penalty: number, ratePerMinute: number|null,
  *            estimateSource: string|null}}
@@ -174,13 +182,16 @@ export function inflightLoad(pool, opts = {}) {
     inflightPenaltyPct = DEFAULT_INFLIGHT_PENALTY_PCT,
   } = opts;
   const count = Math.max(0, num(pool?.inflight?.count) ?? 0);
-  const rate = num(pool?.spend?.weekly?.ratePerMinute);
+  // 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 rate = num(paced?.ratePerMinute);
   const minutes = num(candidateMinutes);
   const penaltyPct = num(inflightPenaltyPct) ?? DEFAULT_INFLIGHT_PENALTY_PCT;
   const sourceLabel =
-    typeof pool?.spend?.weekly?.source === 'string' && pool.spend.weekly.source
-      ? pool.spend.weekly.source
-      : null;
+    typeof paced?.source === 'string' && paced.source ? paced.source : null;
 
   if (rate == null) {
     return {
@@ -238,8 +249,10 @@ export function isExhausted(pool) {
  *                        attached by the caller when it tracks them:
  *                        inflight {count, minutes, records:[{remainingMinutes}]},
  *                        spend {fiveHour:{ratePerMinute, source},
- *                        weekly:{ratePerMinute, source}}, projectedFiveHourPct,
- *                        projectedWeeklyPct.
+ *                        weekly:{...}, monthly:{...},
+ *                        pacing:{window, ratePerMinute, source}},
+ *                        pacingWindow, projectedFiveHourPct,
+ *                        projectedWeeklyPct, projectedPacingPct.
  * @param {object} [opts] { callerEligible=true, callerName='claude', now,
  *                        requiredCapabilities, preferredPool, effortTier,
  *                        callerSession, candidateMinutes=null (expected minutes
@@ -333,6 +346,10 @@ export function pickPool(lane, pools, opts = {}) {
     projectedFiveHourPct: e.forecast.projected,
     forecastFiveHourPct: e.forecast.forecast == null ? null : tenth(e.forecast.forecast),
     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.
+    pacingWindow: e.pool.pacingWindow ?? null,
+    projectedPacingPct: num(e.pool.projectedPacingPct),
     ratePerMinute: e.forecast.ratePerMinute,
     estimateSource: e.load.estimateSource,
     nearFiveHourLimit: e.tier === 1,

package/src/lib/spend.js

@@ -15,6 +15,8 @@
 
 import {
   WINDOW_KEYS,
+  monthlyWindowMs,
+  normalizePacingWindow,
   projectedUtilization,
 } from '../meters/framework.js';
 import { readMeterHistory } from '../meters/registry.js';
@@ -311,9 +313,13 @@ function rateForWindow(meta, { history, snapshot, workerMinutesBetween, nowMs })
   // 2. Bootstrap: the whole window so far — current utilization over the
   //    worker-minutes dispatched since the window opened (M2: the start comes
   //    from the provider's resets_at, never from a locally assumed start).
+  //    A window with no constant length (monthly) takes its length from that
+  //    same resets_at — the calendar month ending on it — so the start is
+  //    still the provider's, never a 30-day assumption.
   const resetsAtMs = num(Date.parse(latest?.resetsAt ?? ''));
-  if (latest && resetsAtMs != null && latest.usedPct > 0 && minutesBetween) {
-    const minutes = num(minutesBetween(resetsAtMs - meta.windowMs, nowMs));
+  const windowMs = meta.windowMs ?? (resetsAtMs != null ? monthlyWindowMs(resetsAtMs) : null);
+  if (latest && resetsAtMs != null && num(windowMs) != null && latest.usedPct > 0 && minutesBetween) {
+    const minutes = num(minutesBetween(resetsAtMs - windowMs, nowMs));
     if (minutes != null && minutes >= MIN_RATE_MINUTES) {
       return {
         ratePerMinute: round(latest.usedPct / minutes, 6),
@@ -336,7 +342,7 @@ function rateForWindow(meta, { history, snapshot, workerMinutesBetween, nowMs })
  * @param {{history?: Array<object>,
  *          workerMinutesBetween?: (fromMs: number, toMs: number) => number,
  *          nowMs?: number, snapshot?: object|null}} [opts]
- * @returns {{fiveHour: object, weekly: object}} each
+ * @returns {{fiveHour: object, weekly: object, monthly: object}} each
  *   `{ratePerMinute, source: 'history'|'bootstrap'|null, samples, windowUsedPct}`
  */
 export function spendRateFor(pool, opts = {}) {
@@ -374,10 +380,10 @@ function historyResolver({ history = null, readHistory = null, historyFor = null
 /**
  * Current utilization for one window of a pool view.
  *
- * The weekly branch reads the rate's own window utilization only: no producer
- * has ever written `pool.weeklyUsedPct` — buildPools writes `usedPct` (the
- * pacing window) and `fiveHourUsedPct` — so reading it first only made the
- * fall-through look conditional when it never was.
+ * The weekly and monthly branches read the rate's own window utilization
+ * only: no producer has ever written `pool.weeklyUsedPct` — buildPools writes
+ * `usedPct` (the pacing window) and `fiveHourUsedPct` — so reading it first
+ * only made the fall-through look conditional when it never was.
  */
 function currentUsedPct(pool, key, rate) {
   if (key === 'fiveHour') return num(pool?.fiveHourUsedPct) ?? rate.windowUsedPct ?? null;
@@ -387,8 +393,13 @@ function currentUsedPct(pool, key, rate) {
 /**
  * Attach the spend model to pool views in place:
  *
- *   pool.spend.fiveHour / pool.spend.weekly = {ratePerMinute, source, samples}
- *   pool.projectedFiveHourPct / pool.projectedWeeklyPct
+ *   pool.spend.fiveHour / .weekly / .monthly = {ratePerMinute, source, samples}
+ *   pool.spend.pacing = {window, ratePerMinute, source, samples} — the same
+ *       numbers for the window that PACES this pool (`pool.pacingWindow`,
+ *       default weekly), so the surplus routing compares and the load it
+ *       charges are measured in the same window.
+ *   pool.projectedFiveHourPct / pool.projectedWeeklyPct /
+ *   pool.projectedMonthlyPct / pool.projectedPacingPct
  *       = current utilization + rate × the remaining minutes of the pool's
  *         in-flight work (this candidate is NOT included — src/lib/route.js
  *         adds the assignment being routed on top).
@@ -428,20 +439,29 @@ export function attachSpend(pools, opts = {}) {
       remainingMinutes += remainingMinutesOf(record, nowMs) ?? 0;
     }
 
+    // The window this pool is paced by decides which rate routing charges.
+    // Default weekly: that is what every pool was paced by before 0.28.1, so
+    // a pool that declares nothing keeps exactly its old numbers.
+    const pacingWindow = normalizePacingWindow(pool?.pacingWindow) ?? 'weekly';
+    const rateOf = (key) => ({
+      ratePerMinute: rates[key].ratePerMinute,
+      source: rates[key].source,
+      samples: rates[key].samples,
+    });
+
     pool.spend = {
-      fiveHour: {
-        ratePerMinute: rates.fiveHour.ratePerMinute,
-        source: rates.fiveHour.source,
-        samples: rates.fiveHour.samples,
-      },
-      weekly: {
-        ratePerMinute: rates.weekly.ratePerMinute,
-        source: rates.weekly.source,
-        samples: rates.weekly.samples,
-      },
+      fiveHour: rateOf('fiveHour'),
+      weekly: rateOf('weekly'),
+      monthly: rateOf('monthly'),
+      pacing: { window: pacingWindow, ...rateOf(pacingWindow) },
     };
 
-    for (const [key, field] of [['fiveHour', 'projectedFiveHourPct'], ['weekly', 'projectedWeeklyPct']]) {
+    for (const [key, field] of [
+      ['fiveHour', 'projectedFiveHourPct'],
+      ['weekly', 'projectedWeeklyPct'],
+      ['monthly', 'projectedMonthlyPct'],
+      [pacingWindow, 'projectedPacingPct'],
+    ]) {
       const projection = projectedUtilization({
         usedPct: currentUsedPct(pool, key, rates[key]),
         ratePerMinute: rates[key].ratePerMinute,

package/src/lib/strategy.js

@@ -7,6 +7,7 @@ import { modelProfile } from './usage.js';
 import { openRouterMetadata } from './openrouter-models.js';
 import { isReasoningLevel, REASONING_LEVELS, resolveReasoningLevel } from './reasoning.js';
 import { attemptWindow } from './spend.js';
+import { pacingWindowFor } from '../meters/framework.js';
 // The canonical lane/effort tables. Imported, never restated: see
 // TIER_CONTEXTS below for the tier -> lane derivation they feed.
 import { DEFAULT_EFFORT_BY_LANE, KIND_DEFAULTS } from '../workflow/action-validator.js';
@@ -550,7 +551,12 @@ function subscriptionView(pool, state) {
     includedValueUsd,
     valueMultiple: monthlyPriceUsd > 0 && includedValueUsd != null
       ? Math.round((includedValueUsd / monthlyPriceUsd) * 100) / 100 : null,
+    // `quotaWindow` is the label as declared (it may name several windows,
+    // e.g. "weekly+monthly+5h"); `pacingWindow` is the one window routing
+    // actually paces this pool by — see src/meters/framework.js.
     quotaWindow: declared.quotaWindow ?? pool.connector?.meter?.window ?? null,
+    pacingWindow: pool.pacingWindow
+      ?? pacingWindowFor({ connector, subscription: state.strategy?.subscriptions?.[pool.name] }),
     quota: monthlyQuota,
     meterSource: pool.meterSource ?? 'none',
     usedPct: pool.usedPct ?? null,

package/src/meters/framework.js

@@ -9,7 +9,11 @@
 //   M3. Weekly/monthly windows pace routing; 5h windows are gates only
 //       (they never pace): >= BURST_BLOCK_PCT blocks dispatch outright and
 //       >= FIVE_HOUR_NEAR_LIMIT_PCT deprioritizes the pool while any pool
-//       with 5h headroom is eligible.
+//       with 5h headroom is eligible. WHICH of weekly/monthly paces one pool
+//       is the pool's own subscription window (`quotaWindow`), not a global
+//       preference: command-code buys a monthly credit allocation and only
+//       rate-limits weekly, so pacing it by its weekly window sends work to a
+//       pool whose real budget is already overspent.
 //   M4. Readers fail closed: an unreadable response is an error, not a
 //       zero. A stale cached reading is shown with its age.
 //   M5. Auth tokens are read from each CLI's native store; refresh
@@ -41,21 +45,69 @@ export function windowPace({ usedPct, resetsAtMs, windowMs, nowMs = Date.now() }
   };
 }
 
+/** The two windows that may pace a pool. 5h is never one of them (M3). */
+export const PACING_WINDOWS = ['weekly', 'monthly'];
+
+/**
+ * A quota-window label as pacing understands it, or null.
+ *
+ * Labels are free text on disk — `strategy set-subscription --quota-window`
+ * has always written whatever it was handed, and connectors describe meters
+ * with strings like "weekly+monthly+5h". Anything that is not exactly one
+ * pacing window is null: unknown, so pacing keeps its default order rather
+ * than guessing which window an operator meant.
+ */
+export function normalizePacingWindow(value) {
+  if (typeof value !== 'string') return null;
+  const name = value.trim().toLowerCase();
+  return PACING_WINDOWS.includes(name) ? name : null;
+}
+
+/**
+ * The window a pool's quota actually lives in: the operator's stored
+ * subscription first (`state.strategy.subscriptions[pool].quotaWindow`), then
+ * the connector's declaration (`connector.subscription.quotaWindow`).
+ *
+ * Precedence is by VALUE, not by validity: a stored label the operator set
+ * wins over the connector's even when it is unrecognised, and an unrecognised
+ * label resolves to null (today's default order) rather than silently falling
+ * through to a window the operator did not choose. `strategy set-subscription`
+ * now rejects labels that are neither, so only pre-0.28.1 state can hold one.
+ *
+ * @param {{connector?: object|null, subscription?: object|null}} [pool]
+ * @returns {'weekly'|'monthly'|null}
+ */
+export function pacingWindowFor({ connector = null, subscription = null } = {}) {
+  const declared = subscription?.quotaWindow ?? connector?.subscription?.quotaWindow ?? null;
+  return normalizePacingWindow(declared);
+}
+
 /**
  * Pace a snapshot per doctrine M3:
- *   - pacing window = weekly ?? monthly ?? none (never 5h)
+ *   - pacing window = the pool's own subscription window when it declares one
+ *     ('monthly' → monthly ?? weekly, 'weekly' → weekly ?? monthly), else the
+ *     default order weekly ?? monthly ?? none. Never 5h.
  *   - burst gate = 5h utilization >= BURST_BLOCK_PCT blocks dispatch
  *   - near limit  = 5h utilization >= FIVE_HOUR_NEAR_LIMIT_PCT: still
  *     dispatchable, but routing prefers any pool with 5h headroom
+ *
+ * `pacingWindow` on the result names the window the numbers actually came
+ * from ('weekly' | 'monthly' | null) — which is the requested one only when
+ * the provider reported it.
+ *
+ * @param {object|null} snapshot
+ * @param {number} [nowMs]
+ * @param {{pacingWindow?: string|null}} [opts]
  */
 export const BURST_BLOCK_PCT = 90;
 /** 5h utilization at/above which routing treats a pool as near its limit. */
 export const FIVE_HOUR_NEAR_LIMIT_PCT = 75;
 
-export function paceSnapshot(snapshot, nowMs = Date.now()) {
+export function paceSnapshot(snapshot, nowMs = Date.now(), opts = {}) {
   if (!snapshot) {
     return {
       pacing: null,
+      pacingWindow: null,
       burstGate: false,
       windows: {},
       fiveHourUsedPct: null,
@@ -81,7 +133,7 @@ export function paceSnapshot(snapshot, nowMs = Date.now()) {
     });
   }
 
-  const pacing = windows.seven_day ?? windows.monthly ?? null;
+  const chosen = pickPacingWindow(windows, opts.pacingWindow);
   const fiveHourUsed = snapshot.five_hour?.utilization;
   const fiveHourUsedPct = Number.isFinite(fiveHourUsed) ? fiveHourUsed : null;
   const burstGate = fiveHourUsedPct != null && fiveHourUsedPct >= BURST_BLOCK_PCT;
@@ -92,7 +144,8 @@ export function paceSnapshot(snapshot, nowMs = Date.now()) {
     : NaN;
 
   return {
-    pacing,
+    pacing: chosen.pacing,
+    pacingWindow: chosen.window,
     burstGate,
     windows,
     fiveHourUsedPct,
@@ -104,15 +157,38 @@ export function paceSnapshot(snapshot, nowMs = Date.now()) {
   };
 }
 
+/**
+ * The paced window out of a `windows` map, honouring the pool's declared
+ * window and falling back to the other one when the provider did not report
+ * the declared one (a reading with only a weekly window still paces).
+ *
+ * @param {{seven_day?: object|null, monthly?: object|null}} windows
+ * @param {string|null} [requested]
+ * @returns {{pacing: object|null, window: 'weekly'|'monthly'|null}}
+ */
+export function pickPacingWindow(windows = {}, requested = null) {
+  const order = normalizePacingWindow(requested) === 'monthly'
+    ? [['monthly', 'monthly'], ['seven_day', 'weekly']]
+    : [['seven_day', 'weekly'], ['monthly', 'monthly']];
+  for (const [key, name] of order) {
+    const pacing = windows?.[key] ?? null;
+    if (pacing) return { pacing, window: name };
+  }
+  return { pacing: null, window: null };
+}
+
 /**
  * Window names the spend model works in, mapped to where each one lives.
  *   - `snapshot`: the key a provider reading uses (`seven_day` for weekly)
  *   - `history`:  the key a history line uses (`weekly`)
- *   - `windowMs`: the window length, for deriving its start from resets_at (M2)
+ *   - `windowMs`: the window length, for deriving its start from resets_at
+ *     (M2) — null for the monthly window, whose length is the calendar month
+ *     ending at the provider's resets_at (monthlyWindowMs), not a constant.
  */
 export const WINDOW_KEYS = {
   fiveHour: { snapshot: 'five_hour', history: 'five_hour', windowMs: WINDOW_MS['5h'] },
   weekly: { snapshot: 'seven_day', history: 'weekly', windowMs: WINDOW_MS.weekly },
+  monthly: { snapshot: 'monthly', history: 'monthly', windowMs: null },
 };
 
 /**

package/src/strategy-cli.js

@@ -1,6 +1,7 @@
 import { loadState, updateState } from './lib/state.js';
 import { loadConnectors, buildPools, buildPoolsLive } from './lib/config.js';
 import { getAllMeterReadings } from './meters/registry.js';
+import { PACING_WINDOWS } from './meters/framework.js';
 import {
   discoverAllModels, buildStrategy, normalizeExcludedModels, resolveDispatchModel,
   selectedModelsForTier, setModelTierSelection, STRATEGY_TIERS,
@@ -60,6 +61,25 @@ function numberOrNull(value, label) {
   return n;
 }
 
+/**
+ * `--quota-window` is no longer a free-text label: it selects the window that
+ * PACES this pool (src/meters/framework.js pacingWindowFor), so a value
+ * pacing cannot act on is refused instead of being stored and ignored.
+ * `unknown`/`null` clears it, exactly like the price flags, which is the way
+ * back for a pre-0.28.1 label that is neither window.
+ */
+function quotaWindowValue(value) {
+  if (value === undefined) return undefined;
+  if (value === 'unknown' || value === 'null') return null;
+  const name = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!PACING_WINDOWS.includes(name)) {
+    throw new Error(
+      `--quota-window must be ${PACING_WINDOWS.join(' or ')} (or unknown to clear)`,
+    );
+  }
+  return name;
+}
+
 function refreshHoursValue(value) {
   const hours = Number(value ?? 24);
   if (!Number.isFinite(hours) || hours <= 0) throw new Error('refresh-hours must be a positive number');
@@ -72,7 +92,10 @@ function render(report, reasoning = null) {
     const value = sub.monthlyPriceUsd == null || sub.includedValueUsd == null
       ? 'value unknown'
       : `$${sub.monthlyPriceUsd}/mo → ~$${sub.includedValueUsd} included (${sub.valueMultiple}×)`;
-    lines.push(`  ${sub.pool}: ${sub.plan ?? 'plan unknown'} · ${value} · ${sub.usedPct ?? '?'}% used · surplus ${sub.surplus ?? '?'}`);
+    // Which window paces this pool is the difference between "behind" and
+    // "overspent" for the same reading, so the line names it.
+    const paced = sub.pacingWindow ? `${sub.pacingWindow} ` : '';
+    lines.push(`  ${sub.pool}: ${sub.plan ?? 'plan unknown'} · ${value} · ${paced}${sub.usedPct ?? '?'}% used · surplus ${sub.surplus ?? '?'}`);
   }
   lines.push('', 'tier suggestions:');
   for (const [tier, suggestion] of Object.entries(report.suggestions)) {
@@ -378,6 +401,9 @@ export function strategyInventory({ pools, state, report, evidence = null }) {
       enabled: pool.enabled !== false,
       usedPct: pool.usedPct ?? null,
       surplus: pool.pace ?? null,
+      // The window `usedPct` and `surplus` are measured in, and that routing
+      // paces this pool by (weekly | monthly | null = weekly-first default).
+      pacingWindow: pool.pacingWindow ?? null,
       // How many agents this pool is running right now, across every
       // Bullswarm process — the same count `bullswarm pools` reports.
       inflight: pool.inflight?.count ?? 0,
@@ -487,6 +513,9 @@ export async function loadStrategyInventory(bullswarmDir, {
     pool.usedPct = live.usedPct;
     pool.pace = live.surplus;
     pool.meterSource = live.meterSource;
+    // The report's numbers came from a window; carry its name with them so
+    // the inventory view does not label them with a different one.
+    pool.pacingWindow = live.pacingWindow ?? pool.pacingWindow ?? null;
   }
   // The control center previews real routing, so it reads the same live
   // in-flight ledger and spend rates every dispatch path does.
@@ -878,6 +907,7 @@ export async function cmdStrategy(args, {
       // Flag validation first, so a bad number fails before any lock is taken.
       const monthlyPriceUsd = numberOrNull(opts['monthly-usd'], 'monthly-usd');
       const includedValueUsd = numberOrNull(opts['included-usd'], 'included-usd');
+      const quotaWindow = quotaWindowValue(opts['quota-window']);
       const state = updateState(bullswarmDir, (fresh) => {
         fresh.strategy ??= {};
         fresh.strategy.subscriptions ??= {};
@@ -887,7 +917,7 @@ export async function cmdStrategy(args, {
           ...(opts.plan !== undefined ? { plan: opts.plan } : {}),
           ...(monthlyPriceUsd !== undefined ? { monthlyPriceUsd } : {}),
           ...(includedValueUsd !== undefined ? { includedValueUsd } : {}),
-          ...(opts['quota-window'] !== undefined ? { quotaWindow: opts['quota-window'] } : {}),
+          ...(quotaWindow !== undefined ? { quotaWindow } : {}),
         };
         delete fresh.strategy.lastReport;
       });
@@ -973,7 +1003,7 @@ export async function cmdStrategy(args, {
     throw new Error(strategyUsage());
   } catch (err) {
     console.error(`✗ ${err.message}`);
-    const usage = /^(usage:|missing |assignment needs |--apply changes|(?:strategy )?(?:apply|auto off|configure|set-provider|set-model|reset-tier|set-reasoning|reset-reasoning) changes|--tiers? must be|--level must be|--reasoning must be|reasoning(?:\.|\s)|refresh-hours must be|.* must be a non-negative number|unknown phase|unknown command|unknown pool|unknown tier|unknown model)/i.test(err.message);
+    const usage = /^(usage:|missing |assignment needs |--apply changes|(?:strategy )?(?:apply|auto off|configure|set-provider|set-model|reset-tier|set-reasoning|reset-reasoning) changes|--tiers? must be|--level must be|--reasoning must be|--quota-window must be|reasoning(?:\.|\s)|refresh-hours must be|.* must be a non-negative number|unknown phase|unknown command|unknown pool|unknown tier|unknown model)/i.test(err.message);
     return usage ? 2 : 1;
   }
 }

package/src/workflow/runs-cli.js

@@ -27,7 +27,11 @@ import { deserializeV2ResultEnvelope, summarizeV2Result } from './v2-outcome.js'
 import { helpText, usageLine } from '../help.js';
 import { flagName, unknownFlagExit } from '../lib/cli-flags.js';
 
-function jsonOut(obj, opts) { if (opts.json || opts.summary) console.log(JSON.stringify(obj, null, 2)); }
+function jsonOut(obj, opts) {
+  if (!(opts.json || opts.summary)) return;
+  // Summary is budgeted against compact JSON.stringify; --json alone stays pretty.
+  console.log(opts.summary ? JSON.stringify(obj) : JSON.stringify(obj, null, 2));
+}
 function err(msg, code = 1) { console.error(msg); return code; }
 
 // Every command that would drive a legacy run answers with the same sentence

package/src/workflow/v2-dispatch.js

@@ -225,7 +225,7 @@ export async function dispatchV2Action({
   };
   const coreDecisionLog = () => safeCoreState()?.decisionLog ?? [];
   // Operator-configurable, read once: the flat surplus cost of an in-flight
-  // agent on a pool whose weekly spend rate nobody has measured yet.
+  // agent on a pool whose pacing-window spend rate nobody has measured yet.
   const inflightPenaltyPct = inflightPenaltyFrom(safeCoreState());
   // One expectation for the whole action: lane and effort do not change
   // between attempts, and the spend model is memoized per process anyway. The