@ultimat3/jobs 28.0.0 → 29.1.0

package/CLAUDE.md

@@ -76,7 +76,8 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   `finiteCount()` (a count, caller's minimum); `worker-options.ts` is where `jobWorker` reads them.
   **`bun run finite-bounds` is a floor, never proof**: `concurrencyLimiter`'s five numbers are screened
   with min 0 (zero is a HARD STOP). **A row count is `finiteCount` (min 0)**; `retry.attempts` is one with min 1.
-- **`WorkerOptions.concurrency` is read by OWN key** (`worker-slots.test.ts`).
+- **`WorkerOptions.concurrency` is read by OWN key** (`worker-slots.test.ts`); `maxInFlight` BEFORE
+  the claim, its count back with the lease, before the `kick` (history).
 - **`job.concurrency` is enforced by `JobDriver.leases`** (one row per held slot in `x_job_leases`);
   `limits.ts` is the per-process fast path. No lease store + a declared `concurrency` makes `start()`
   throw `X_JOB_CONCURRENCY_UNENFORCEABLE`.
@@ -129,9 +130,8 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   out before `leader.release()`. Same two-hook rule; an ABANDONED round does not release
   (`jobs.scheduler.drain-abandoned`). `stillLeading()` is asked every round and before every task,
   and answers from memory inside `renewEveryMs`.
-- **`run-once` fires ONE catch-up**: the watermark rides the fire (`ScheduledFire.watermarkMs`,
-  `SQL_SCHEDULER_FIRE` `$4`), never a `markFired` behind it; `skip` fires the true latest missed
-  occurrence (`latestOccurrenceBy`, bisection).
+- **`run-once` fires ONE catch-up**: the watermark rides the fire (`ScheduledFire.watermarkMs`),
+  never a `markFired` behind it; `skip` fires the latest missed occurrence (`latestOccurrenceBy`).
 - **A lease for a run that never STARTED is `abandon()`ed, never `release()`d** — the rate stamp
   goes with it (`worker-admit.ts`). **A failed pass re-arms at the floor** (`worker-loop.ts`
   catch); `timers` is the test seam.
@@ -229,8 +229,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 - **`webhook()`**: ONE event to ONE endpoint, no steps; each attempt but a CANCELLED one recorded
   before the throw; `ledger.isDisabled` gates the socket. **The wire format is core's.** An org
   tenant reads `orgId` OFF THE INPUT; none, or not the run's org: TERMINAL `X_JOB_TENANT_MISMATCH`.
-- A `-fixture.ts` file does not ship; `backfill-pass-fixture.ts` raises a plain `Error` subclass on
-  purpose (it stands in for app code).
+- A `-fixture.ts` file does not ship; `backfill-pass-fixture.ts` raises a plain `Error` on purpose.
 
 ## Files
 
@@ -283,6 +282,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `worker-run.ts` | one claimed job, wired: heartbeat, slot renewal, run signal, span |
 | `run-signal.ts` | the signal ONE run is cancelled by |
 | `worker-fleet-slots.ts` | the fleet slot an in-flight job holds — take, renew, hand back — and the boot refusal |
+| `worker-process-cap.ts` / `worker-claim-sweep.ts` | `maxInFlight`'s count; the pass's asks, rotated |
 | `purge.ts` | `purge()` — a factory over `job()`: the retention sweep and its target seam |
 | `task.ts` | the `task()` primitive + registry + the handle's surface + `registerTask` |
 | `scheduler.ts` | `scheduler` role: the dispatch round, catch-up, leader election, the drain |
@@ -304,9 +304,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `errors-operator.ts` / `errors-requeue.ts` | the operator verbs' refusals; `requeue`'s |
 | `errors-tenant.ts` | `JobTenantMismatchError` |
 
-Which `-fixture.ts` harness each suite shares, and what each `.job.` suite proves:
-`docs/history/jobs.md`, "Moved 2026-10-01 — test harnesses".
-
-Commands: `bun test packages/jobs` · `bun run --filter @ultimat3/jobs typecheck`.
+Commands: `bun test packages/jobs` · `bun run --filter @ultimat3/jobs typecheck`. Test harnesses:
+history, "Moved 2026-10-01 — test harnesses".
 
 Why each rule above is shaped the way it is: [`docs/history/jobs.md`](../../docs/history/jobs.md).

package/README.md

@@ -816,7 +816,7 @@ or `ready` — so a new branch cannot land in one driver and not another. Its le
 
 | Role | Entry | Behaviour |
 |---|---|---|
-| `worker` | `jobWorker({ driver, context, queues, concurrency })` | per-queue pools, lease heartbeat, SIGTERM drain: stop claiming → finish in-flight → close. `concurrency` is a number for every queue or a table per queue; a queue it does not name gets core's `JOBS_CONCURRENCY_DEFAULT` (8 — this package's own default was 5 before 25.0.0) |
+| `worker` | `jobWorker({ driver, context, queues, concurrency, maxInFlight })` | per-queue pools under one optional process cap, lease heartbeat, SIGTERM drain: stop claiming → finish in-flight → close. `concurrency` is a number for every queue or a table per queue; a queue it does not name gets core's `JOBS_CONCURRENCY_DEFAULT` (8 — this package's own default was 5 before 25.0.0). `maxInFlight` caps the runs held across EVERY queue (app config `jobs.maxInFlight`; unset: no cap) — [Limits](#the-process-cap-maxinflight) |
 | `scheduler` | `jobScheduler({ driver, leader, state })` | one dispatch round at a time, catch-up policy, SIGTERM drain: stop dispatching → finish the round → release the lock |
 
 Both roles register the same **pair** of hooks and bound the `close` half the same way. The
@@ -1047,6 +1047,28 @@ cannot hold the cap, so `jobWorker().start()` **refuses to boot**
 Over any cap the claim is handed straight back without burning an attempt — one org's 50k-row
 import cannot starve the fleet.
 
+### The process cap: `maxInFlight`
+
+`jobWorker({ maxInFlight })` — `jobs.maxInFlight` in `app.config.ts` — is the most runs ONE worker
+process holds at once across every queue it serves: Sidekiq's `concurrency`. The per-queue slots
+(`concurrency`) still bound each queue under it. Unset, there is no process cap: the sum of the
+queue slots is the bound, as before.
+
+| Rule | Detail |
+|---|---|
+| read BEFORE the claim | a worker at the cap asks the queue for nothing; no row is claimed only to be shed. `LimitConfig.global` is the other kind: it sheds what was already claimed |
+| a finish frees one claim at once | the run's `finally` returns its count beside its limiter lease, then kicks a pass — no poll wait |
+| no idle slot while a queue has work | a pass splits the room it has over the queues it has not asked yet (`ceil(room / queues left)`); a queue with less work than its share leaves the rest to the queues after it, and a queue that filled its share is asked again while room is left |
+| no queue starves | queues are asked in the worker's order **rotated to start after the last queue given a job**, so on a worker at the cap each freed slot goes to the next queue in turn that has work. Three backlogged queues on `maxInFlight: 1` run `a, b, c, a, b, c` — never `a` until it drains. This holds while the loop IDLES at the cap too: once the cap has filled, an idle pass takes the rotated asks instead of the one-statement claim over every queue (which hands out the oldest row of any queue), until a pass finds no work at all. A first fill from empty is that one statement's, in the driver's order |
+| drain, heartbeat, lease | unchanged: SIGTERM stops claiming, held runs finish under the deadline, the cut-off hands back what is left |
+| refused | `0`, negative, fractional, `NaN`, `Infinity`: `X_INVARIANT` at `jobWorker()`, `X_CONFIG_INVALID` naming `jobs.maxInFlight` at boot |
+
+What a scaler reads, per process: `worker.stats()` → `inFlight` and `maxInFlight` (`null` when
+uncapped); the registry row's `concurrency` is the tighter of the cap and the slot sum; and two
+unlabelled gauges, `job_worker_in_flight` and `job_worker_capacity`, each the SUM over the live workers in the process (a stopped worker leaves both). Pods needed is
+`ceil((queue_depth + Σ job_worker_in_flight) / job_worker_capacity)`. A fleet-wide ceiling is a
+different number: `maxInFlight` × replicas, or `job.concurrency` for one job.
+
 ### One run per key
 
 A number caps the whole job. `{ key, limit, whenBusy }` caps it **per key** — "at most one run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "28.0.0",
+  "version": "29.1.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -26,17 +26,17 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.3"
+    "bun": ">=1.4.4"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "28.0.0",
-    "@ultimat3/db": "28.0.0",
-    "@ultimat3/entity": "28.0.0",
-    "@ultimat3/schema": "28.0.0",
-    "@ultimat3/time": "28.0.0"
+    "@ultimat3/core": "29.1.0",
+    "@ultimat3/db": "29.1.0",
+    "@ultimat3/entity": "29.1.0",
+    "@ultimat3/schema": "29.1.0",
+    "@ultimat3/time": "29.1.0"
   }
 }

package/src/claim-exhausted.ts

@@ -1,12 +1,13 @@
 // The claim round's half of a burial: a row the claim settled `dead` (`ClaimOptions.onExhausted`)
 // has no body to end it and no settle to announce it, so the pass that buried it says so — one log
-// line an operator can alert on, and the job's `onSettled`, exactly as a dead letter a worker
-// settled itself would get.
+// line an operator can alert on, its `jobs_total` count, and the job's `onSettled`, exactly as a
+// dead letter a worker settled itself would get.
 
 import type { Ctx } from '@ultimat3/core';
-import { logger, renderThrowable } from '@ultimat3/core';
+import { logger, recordJob, renderThrowable } from '@ultimat3/core';
 import type { JobRecord } from './driver';
 import { getJob } from './job';
+import { JOB_OUTCOME_LABELS } from './metrics';
 import { announceSettled } from './settled';
 
 export interface AnnounceExhaustedOptions {
@@ -38,6 +39,8 @@ export async function announceExhausted(
     const error = record.lastError ?? '';
     const outcome = record.state === 'failed' ? 'dropped' : 'dead-lettered';
     if (outcome === 'dropped') dropped += 1;
+    const label = JOB_OUTCOME_LABELS[outcome];
+    if (label !== null) recordJob(record.queue, label);
     // `error`, not `warn`: nobody recovered from this one, and a job that outlives every worker
     // that takes it is a crash loop somebody has to look at.
     logger.error('jobs.claim.exhausted', {

package/src/metrics.ts

@@ -56,3 +56,27 @@ export function recordQueueOldestReady(queue: string, oldestReadyMs: number): vo
 export function recordQueueDeadJobs(queue: string, dead: number): void {
   queueDeadJobs.record(dead, { queue });
 }
+
+/**
+ * What an autoscaler sizes a worker fleet with: `ceil((queue_depth + Σ in_flight) / capacity)`
+ * pods. Unlabelled — one series per PROCESS, which is what `maxInFlight` caps and what one worker
+ * pod is; the scrape's own `instance` label tells pods apart, and `sum` across them is the fleet.
+ */
+export const workerInFlight: Gauge = gauge('job_worker_in_flight', {
+  unit: '{job}',
+  description: 'Jobs this worker process is running right now, across every queue it serves',
+});
+
+export const workerCapacity: Gauge = gauge('job_worker_capacity', {
+  unit: '{job}',
+  description:
+    'The most jobs this worker process runs at once: maxInFlight, or the sum of its queue slots when tighter or unset',
+});
+
+export function recordWorkerInFlight(held: number): void {
+  workerInFlight.record(held);
+}
+
+export function recordWorkerCapacity(capacity: number): void {
+  workerCapacity.record(capacity);
+}

package/src/worker-claim-sweep.ts

@@ -0,0 +1,113 @@
+// Single responsibility: which queue one claim pass asks, in what order and for how many — under
+// each queue's own slots AND the process cap (`maxInFlight`, `worker-process-cap.ts`). The worker
+// owns what a claim DOES; this owns the plan, so the fairness rule is one file a test can drive.
+//
+// THE FAIRNESS RULE. Queues are asked in the worker's order ROTATED to start after the last queue
+// that was given a job, and a pass splits the room it has left evenly over the queues it has not
+// asked yet (`ceil(room / queues left)`); a queue that filled its share is asked again, in the same order, while room is left. So a free slot goes to some queue
+// with work whenever any has it, and a backlogged queue cannot monopolise a capped worker: each
+// slot a finish frees goes to the next queue in turn — at the cap too, where the loop idles between
+// finishes. An idle worker whose cap has not filled asks once over every queue (one statement, the
+// driver's order), so a first fill from empty is the driver's; the turn holds from the cap on.
+
+import { type ClaimAsk, claimAsks } from './worker-admit';
+
+/** What one claim answered: runs ADMITTED (a shed or a refusal holds nothing), per queue. */
+export type ClaimAnswer = ReadonlyMap<string, number>;
+
+export interface ClaimSweepInput {
+  /** The worker's queues, in its own order. */
+  readonly queues: readonly string[];
+  /** A queue's free slots, re-read before every ask — a run admitted or finished moves it. */
+  readonly freeSlots: (queue: string) => number;
+  /** Room under the process cap, re-read likewise; `Infinity` with none. */
+  readonly processFree: () => number;
+  /** The loop is idling: one statement over every open queue (`claimAsks`), unless contended. */
+  readonly idle: boolean;
+  /** May the pass still claim? Re-read per ask — a `stop()` between two queues is a stop now. */
+  readonly claiming: () => boolean;
+  readonly claim: (ask: ClaimAsk) => Promise<ClaimAnswer>;
+}
+
+export interface ClaimSweep {
+  /** One pass. Resolves once every ask it made has been answered. */
+  pass(input: ClaimSweepInput): Promise<void>;
+}
+
+/** `queues` from `start`, wrapping. */
+const rotated = (queues: readonly string[], start: number): readonly string[] =>
+  queues.length === 0
+    ? queues
+    : [...queues.slice(start % queues.length), ...queues.slice(0, start % queues.length)];
+
+/** The cursor lives across passes: that is what makes the rotation a turn, not a shuffle. */
+export function createClaimSweep(): ClaimSweep {
+  let cursor = 0;
+  /**
+   * The cap has been FULL since the last pass that found the queues empty. A worker at the cap
+   * finds nothing, so its loop idles, and an idle pass is ONE statement over every queue — rows in
+   * the DRIVER's order, the oldest of any queue, never by turn. So while contended, an idle pass
+   * takes the rotated sweep; once a rotated idle pass finds no work at all, the worker is idle for
+   * real and goes back to its one-statement pass. Set by the cap filling, not by runs held: at
+   * `maxInFlight: 1` a finish leaves none held at the very pass that must pick the next queue.
+   */
+  let contended = false;
+
+  const served = (queues: readonly string[], answer: ClaimAnswer): number => {
+    let admitted = 0;
+    for (const [queue, count] of answer) {
+      if (count <= 0) continue;
+      admitted += count;
+      const index = queues.indexOf(queue);
+      if (index !== -1) cursor = index + 1;
+    }
+    return admitted;
+  };
+
+  return {
+    async pass(input) {
+      const order = rotated(input.queues, cursor);
+      if (input.processFree() <= 0) {
+        contended = true;
+        return;
+      }
+      if (input.idle && !contended) {
+        const room = input.processFree();
+        for (const ask of claimAsks(order, input.freeSlots, true)) {
+          if (!input.claiming()) return;
+          served(input.queues, await input.claim({ ...ask, limit: Math.min(ask.limit, room) }));
+        }
+        if (input.processFree() <= 0) contended = true;
+        return;
+      }
+      let admitted = 0;
+      let asking = order;
+      while (asking.length > 0) {
+        const again: string[] = [];
+        for (const [index, queue] of asking.entries()) {
+          if (!input.claiming()) return;
+          const room = input.processFree();
+          if (room <= 0) {
+            contended = true;
+            return;
+          }
+          const share = Math.ceil(room / (asking.length - index));
+          const free = Math.max(0, input.freeSlots(queue));
+          const limit = Math.min(free, share);
+          if (limit <= 0) continue;
+          const answer = await input.claim({ queues: [queue], limit });
+          const got = served(input.queues, answer);
+          admitted += got;
+          // Its SHARE bound it, not its slots, and it filled it with runs that STARTED: it may
+          // hold more, for room a quieter queue left. A shed is not "more" — asking again would
+          // claim the same capped rows back and forth. With no cap the share never binds, so an
+          // uncapped pass is one ask per queue, as it always was.
+          if (limit < free && got >= limit) again.push(queue);
+        }
+        asking = again;
+      }
+      if (input.processFree() <= 0) contended = true;
+      else if (input.idle && admitted === 0) contended = false;
+    },
+  };
+}

package/src/worker-process-cap.ts

@@ -0,0 +1,83 @@
+// Single responsibility: `WorkerOptions.maxInFlight` — the one count of runs this worker holds
+// across EVERY queue, and the room it leaves. Sidekiq's `concurrency`: the per-queue slots bound
+// each pool, this bounds the process. Read BEFORE a claim, so a worker at the cap asks the queue
+// for nothing and no row is claimed only to be shed.
+
+import { finiteCount } from '@ultimat3/core';
+import { recordWorkerCapacity, recordWorkerInFlight } from './metrics';
+
+export interface ProcessCap {
+  /** The cap as declared, `undefined` when the worker has none. */
+  readonly max: number | undefined;
+  /** Room left under the cap: `Infinity` with no cap, never below 0. */
+  free(): number;
+  /** Runs counted against the cap right now. */
+  held(): number;
+  /**
+   * One run admitted. The answer hands its count back, ONCE however often it is called — the
+   * run's `finally` and nothing else, at the same instant its limiter lease goes back, so the
+   * `kick` that follows sees the room it made.
+   */
+  take(): () => void;
+  /** The worker serves again (`start()`): counted in the process gauges. */
+  revive(): void;
+  /** The worker stopped: out of the process gauges, its capacity with it. */
+  retire(): void;
+}
+
+interface Counted {
+  held: number;
+  readonly capacity: number;
+}
+
+/**
+ * Every worker this PROCESS has live. The two gauges are unlabelled, one series per process, so
+ * they carry the SUM: a second `jobWorker` in one process used to reset the first's in-flight to 0
+ * and overwrite its capacity, and each later update published one worker's count as the whole.
+ */
+const live = new Set<Counted>();
+
+const publish = (): void => {
+  let held = 0;
+  let capacity = 0;
+  for (const worker of live) {
+    held += worker.held;
+    capacity += worker.capacity;
+  }
+  recordWorkerInFlight(held);
+  recordWorkerCapacity(capacity);
+};
+
+/** `maxInFlight`, refused when it is not a whole number ≥ 1 — `jobWorker`'s other counts' rule. */
+export function createProcessCap(max: number | undefined, slots: number): ProcessCap {
+  if (max !== undefined) finiteCount('jobWorker', 'maxInFlight', max, 1);
+  // What a scaler divides by: the most this worker can run, whichever bound is tighter.
+  const counted: Counted = { held: 0, capacity: max === undefined ? slots : Math.min(max, slots) };
+  live.add(counted);
+  publish();
+  return {
+    max,
+    free: () => (max === undefined ? Number.POSITIVE_INFINITY : Math.max(0, max - counted.held)),
+    held: () => counted.held,
+    take() {
+      counted.held += 1;
+      publish();
+      let returned = false;
+      return () => {
+        if (returned) return;
+        returned = true;
+        counted.held -= 1;
+        publish();
+      };
+    },
+    revive() {
+      if (live.has(counted)) return;
+      live.add(counted);
+      publish();
+    },
+    retire() {
+      if (!live.delete(counted)) return;
+      publish();
+    },
+  };
+}

package/src/worker-types.ts

@@ -18,6 +18,13 @@ export interface WorkerOptions {
    * (or no `concurrency` at all) runs at core's `JOBS_CONCURRENCY_DEFAULT`, 8 — 5 before 25.0.0.
    */
   readonly concurrency?: number | Readonly<Record<string, number>>;
+  /**
+   * The most runs this process holds at once, across EVERY queue — Sidekiq's `concurrency`. The
+   * per-queue slots still bound each queue under it. A worker at the cap claims nothing until a
+   * run ends; a freed slot goes to the next queue in turn that has work (`worker-claim-sweep.ts`).
+   * Unset: no process cap, the sum of the queue slots. A whole number ≥ 1, else `X_INVARIANT`.
+   */
+  readonly maxInFlight?: number;
   readonly limiter?: Limiter;
   readonly clock?: Clock;
   readonly events?: EventLookup;
@@ -52,6 +59,8 @@ export interface WorkerStats {
   readonly queues: readonly string[];
   readonly state: 'idle' | 'running' | 'draining' | 'stopped';
   readonly inFlight: number;
+  /** `WorkerOptions.maxInFlight`, `null` when uncapped — what a scaler divides the backlog by. */
+  readonly maxInFlight: number | null;
   readonly processed: number;
   readonly failed: number;
   readonly suspended: number;

package/src/worker.ts

@@ -22,13 +22,15 @@ import type { JobExecution } from './execute';
 import { registeredJobs } from './job';
 import { concurrencyLimiter } from './limits';
 import { JOB_OUTCOME_LABELS } from './metrics';
-import { claimAsks, createAdmission } from './worker-admit';
+import { type ClaimAsk, createAdmission } from './worker-admit';
+import { type ClaimAnswer, createClaimSweep } from './worker-claim-sweep';
 import { armWorkerCutoff, type DrainCutoff } from './worker-drain-cutoff';
 import { assertConcurrencyEnforceable, createFleetSlots } from './worker-fleet-slots';
 import { createHeldRuns } from './worker-held';
 import type { ClaimLoop } from './worker-loop';
 import { createClaimLoop } from './worker-loop';
 import { resolveWorkerTimings } from './worker-options';
+import { createProcessCap } from './worker-process-cap';
 import { createQueueDepthPublisher } from './worker-queue-depth';
 import type { WorkerRegistration } from './worker-registry';
 import { reportUnregisteredQueues, startWorkerRegistry } from './worker-registry';
@@ -46,6 +48,9 @@ export function jobWorker(options: WorkerOptions): Worker {
   const { visibilityTimeoutMs, pollIntervalMs, heartbeatIntervalMs, slotsFor } =
     resolveWorkerTimings(options);
   const limiter = options.limiter ?? concurrencyLimiter({});
+  const slots = queues.reduce((total, queue) => total + slotsFor(queue), 0);
+  const cap = createProcessCap(options.maxInFlight, slots); // read before each claim
+  const sweep = createClaimSweep();
   const driverLeases = options.driver.leases;
   // `job.concurrency`, held as a row every replica sees. The TTL is the visibility timeout and the
   // renewal rides the lease heartbeat's interval — `worker-fleet-slots.ts` says why both.
@@ -132,28 +137,19 @@ export function jobWorker(options: WorkerOptions): Worker {
   const claiming = (): boolean => state !== 'draining' && state !== 'stopped';
 
   /**
-   * One claim pass: every queue asked once, and everything it hands back STARTED. It does not wait
-   * for the jobs — a slot is free again the moment its own job settles and the limiter releases
-   * the lease, so the next pass refills exactly that slot. Waiting for the whole batch made a pool
-   * as slow as its slowest member and, because the pass walks every queue before it waits, left
-   * every OTHER queue idle behind one long-running job too.
+   * One claim pass: everything it hands back STARTED, never waited for — a slot is free again the
+   * moment its own job settles, so the next pass refills exactly that slot. Waiting for the batch
+   * made a pool as slow as its slowest member, and every OTHER queue idle behind it.
    */
   const claimRound = async (): Promise<readonly Promise<JobExecution>[]> => {
     await publishQueueDepth();
     const started: Promise<JobExecution>[] = [];
     let found = false;
 
-    const asks = claimAsks(
-      queues,
-      (queue) => slotsFor(queue) - limiter.inFlight({ queue }),
-      loop.idle(),
-    );
-
-    for (const ask of asks) {
-      // Re-read per claim, not once at the top: a `stop()` between two queues means "stop
-      // claiming" now, not at the next tick. What this round already holds still runs to the end
-      // — that is the drain, and `stop()` waits for it.
-      if (!claiming()) break;
+    // One ask; WHICH queue, how many and in what order is `worker-claim-sweep.ts`'s (`maxInFlight`
+    // and the turn). It re-reads `claiming()` per ask: a `stop()` mid-pass stops claiming now.
+    const claimOne = async (ask: ClaimAsk): Promise<ClaimAnswer> => {
+      const admitted = new Map<string, number>();
       // A lease that lapsed on a row's final attempt is settled by the claim itself and handed to
       // `onExhausted`, never out as work: this round is the only thing that can count it, log it
       // and tell the job. `dropExhausted` is the policy the row does not carry.
@@ -172,16 +168,9 @@ export function jobWorker(options: WorkerOptions): Worker {
       if (claimed.length > 0) found = true;
       if (buried.length > 0) {
         found = true;
-        const ended = await announceExhausted({
-          exhausted: buried,
-          workerId,
-          context: options.context,
-        });
-        tally.buried(ended);
-        for (const row of buried) {
-          const label = JOB_OUTCOME_LABELS[row.state === 'failed' ? 'dropped' : 'dead-lettered'];
-          if (label !== null) recordJob(row.queue, label);
-        }
+        tally.buried(
+          await announceExhausted({ exhausted: buried, workerId, context: options.context }),
+        );
       }
 
       for (const [index, job] of claimed.entries()) {
@@ -199,6 +188,8 @@ export function jobWorker(options: WorkerOptions): Worker {
           continue;
         }
         const { lease } = admission;
+        admitted.set(queue, (admitted.get(queue) ?? 0) + 1);
+        const returnCap = cap.take(); // `maxInFlight`'s count, handed back beside the lease
 
         // The claimed job is the process's in-flight work, counted where the DRAIN can see it:
         // core's own in-flight wait sits between `accept` and `inflight` and exists for exactly
@@ -215,10 +206,8 @@ export function jobWorker(options: WorkerOptions): Worker {
         const running = runClaimed(job, admission.refusal)
           .then((execution) => {
             tally.count(execution);
-            // The other half of this package's metrics contract: `queue_depth` says how much work
-            // is waiting, `jobs_total` says whether any of it is succeeding. Depth alone cannot
-            // tell a drained queue from a queue nothing ever claimed. Labelled by QUEUE and
-            // OUTCOME only — a label per job name is unbounded in an app's own vocabulary.
+            // `jobs_total`, beside `queue_depth`: depth cannot tell a drained queue from one nothing
+            // claimed. QUEUE and OUTCOME only — a job-name label is unbounded in an app's vocabulary.
             const label = JOB_OUTCOME_LABELS[execution.outcome];
             if (label !== null) recordJob(queue, label);
             // Handed back with a time on it — a retry's backoff, a sleep's wake: this worker
@@ -230,17 +219,15 @@ export function jobWorker(options: WorkerOptions): Worker {
           })
           .finally(async () => {
             lease.release();
+            returnCap();
             // The slot is free NOW. A full worker asks the queue for nothing, so its loop backs
             // off like an idle one — and waiting that out with a backlog behind the job that
             // just finished is throughput lost to a timer.
             loop.kick();
-            // AWAITED, never `void`: the slot is a row in `x_job_leases`, so the DELETE was still
-            // on the wire when the teardown's `allSettled` returned and `driver.close()` took the
-            // connection out from under it — a `concurrency: 1` job unclaimable by the pod
-            // replacing this one for a whole visibility window after every deploy. `release`
-            // swallows its own failures, so awaiting it cannot reject a job that finished; the
-            // `finally` is for the one that could, because a lost `finishWork()` is an in-flight
-            // count that never returns to zero and a drain that waits out its whole budget.
+            // AWAITED, never `void`: the slot is a row in `x_job_leases`, and a DELETE still on the
+            // wire at `driver.close()` left a `concurrency: 1` job unclaimable by the replacement
+            // pod for a visibility window. `release` swallows its own failures; the `finally` is
+            // for the one that could not, as a lost `finishWork()` holds the drain its whole budget.
             try {
               await releaseSlot();
             } finally {
@@ -272,7 +259,17 @@ export function jobWorker(options: WorkerOptions): Worker {
           },
         );
       }
-    }
+      return admitted;
+    };
+
+    await sweep.pass({
+      queues,
+      freeSlots: (queue) => slotsFor(queue) - limiter.inFlight({ queue }),
+      processFree: cap.free,
+      idle: loop.idle(),
+      claiming,
+      claim: claimOne,
+    });
 
     // The loop's next wait: the floor while passes find work, doubling to the ceiling while they
     // do not (`idle-backoff.ts`). Reported by the pass itself, so `tick()` and the timer agree.
@@ -403,6 +400,7 @@ export function jobWorker(options: WorkerOptions): Worker {
       // and the budget with it, or the next manual stop would inherit a deadline already spent.
       cutoff?.dispose();
       cutoff = undefined;
+      cap.retire(); // out of the process gauges until a `start()` serves again
       drainSignal = new AbortController();
       budget = createDrainBudget();
     }
@@ -444,6 +442,7 @@ export function jobWorker(options: WorkerOptions): Worker {
       // `x jobs show` and the manifest both confirm a guarantee that does not exist.
       assertConcurrencyEnforceable(options.driver);
       state = 'running';
+      cap.revive();
       logger.info('jobs.worker.started', { workerId, queues });
       reportUnregisteredQueues(workerId, queues);
       registration = startWorkerRegistry({
@@ -451,7 +450,7 @@ export function jobWorker(options: WorkerOptions): Worker {
         workerId,
         host: options.host,
         queues,
-        concurrency: queues.reduce((slots, queue) => slots + slotsFor(queue), 0),
+        concurrency: Math.min(slots, cap.max ?? slots),
         inFlight: () => inFlight.ids(),
         // The visibility timeout, renewed on the heartbeat interval: a killed worker leaves the
         // registry on exactly the schedule the queue takes its jobs back.
@@ -490,6 +489,7 @@ export function jobWorker(options: WorkerOptions): Worker {
         queues,
         state,
         inFlight: inFlight.size,
+        maxInFlight: cap.max ?? null,
         ...tally.snapshot(),
         pollDelayMs: loop.delayMs(),
         queueDepth: [...(await options.driver.stats())],