bunqueue 2.8.34 → 2.8.36

package/dist/application/operations/jobMoveOperations.js

@@ -0,0 +1,94 @@
+/**
+ * Job move operations that claim active jobs for delayed or DLQ state.
+ */
+import { processingShardIndex, shardIndex } from '../../shared/hash';
+import { withWriteLock } from '../../shared/lock';
+import { releaseClaimedJobOwnership } from './jobClaim';
+/** Move active job back to delayed. */
+export async function moveJobToDelayed(jobId, delay, ctx) {
+    const location = ctx.jobIndex.get(jobId);
+    if (location?.type !== 'processing')
+        return false;
+    const procIdx = processingShardIndex(jobId);
+    const job = await withWriteLock(ctx.processingLocks[procIdx], () => {
+        const claimed = ctx.processingShards[procIdx].get(jobId);
+        if (claimed) {
+            ctx.processingShards[procIdx].delete(jobId);
+            releaseClaimedJobOwnership(jobId, ctx);
+        }
+        return claimed;
+    });
+    if (!job)
+        return false;
+    const now = Date.now();
+    job.runAt = now + delay;
+    job.startedAt = null;
+    const idx = shardIndex(job.queue);
+    const queueName = job.queue;
+    await withWriteLock(ctx.shardLocks[idx], () => {
+        const shard = ctx.shards[idx];
+        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        shard.getQueue(job.queue).push(job);
+        const isDelayed = job.runAt > now;
+        shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
+        ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
+        shard.notify(job.queue);
+    });
+    ctx.storage?.updateRunAt(jobId, job.runAt);
+    ctx.eventsManager.broadcast({
+        eventType: "delayed" /* EventType.Delayed */,
+        jobId,
+        queue: queueName,
+        timestamp: Date.now(),
+        delay,
+    });
+    return true;
+}
+/** Discard a waiting or active job to the DLQ. */
+export async function discardJob(jobId, ctx) {
+    const location = ctx.jobIndex.get(jobId);
+    if (!location)
+        return false;
+    let job = null;
+    if (location.type === 'queue') {
+        job = await withWriteLock(ctx.shardLocks[location.shardIdx], () => {
+            const shard = ctx.shards[location.shardIdx];
+            const removed = shard.getQueue(location.queueName).remove(jobId);
+            if (removed)
+                shard.decrementQueued(jobId);
+            return removed;
+        });
+    }
+    else if (location.type === 'processing') {
+        const procIdx = processingShardIndex(jobId);
+        job = await withWriteLock(ctx.processingLocks[procIdx], () => {
+            const claimed = ctx.processingShards[procIdx].get(jobId) ?? null;
+            if (claimed) {
+                ctx.processingShards[procIdx].delete(jobId);
+                releaseClaimedJobOwnership(jobId, ctx);
+            }
+            return claimed;
+        });
+    }
+    if (!job)
+        return false;
+    const validJob = job;
+    const idx = shardIndex(validJob.queue);
+    const fromProcessing = location.type === 'processing';
+    const entry = await withWriteLock(ctx.shardLocks[idx], () => {
+        const shard = ctx.shards[idx];
+        if (fromProcessing) {
+            shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId);
+            shard.notify(validJob.queue);
+        }
+        else if (validJob.uniqueKey) {
+            shard.releaseUniqueKey(validJob.queue, validJob.uniqueKey);
+        }
+        const dlqEntry = shard.addToDlq(validJob);
+        ctx.jobIndex.set(jobId, { type: 'dlq', queueName: validJob.queue });
+        return dlqEntry;
+    });
+    ctx.storage?.saveDlqEntry(entry);
+    ctx.storage?.deleteJob(jobId);
+    return true;
+}

package/dist/application/operations/jobStateTransitions.js

@@ -7,6 +7,7 @@
  */
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { withWriteLock } from '../../shared/lock';
+import { releaseClaimedJobOwnership } from './jobClaim';
 /** Move active job back to waiting */
 export async function moveActiveToWait(jobId, ctx) {
     const location = ctx.jobIndex.get(jobId);
@@ -17,6 +18,7 @@ export async function moveActiveToWait(jobId, ctx) {
         const job = ctx.processingShards[procIdx].get(jobId);
         if (job) {
             ctx.processingShards[procIdx].delete(jobId);
+            releaseClaimedJobOwnership(jobId, ctx);
         }
         return job;
     });
@@ -73,6 +75,7 @@ export async function moveToWaitingChildren(jobId, ctx) {
         const job = ctx.processingShards[procIdx].get(jobId);
         if (job) {
             ctx.processingShards[procIdx].delete(jobId);
+            releaseClaimedJobOwnership(jobId, ctx);
         }
         return job;
     });

package/dist/application/operations/pull.js

@@ -35,6 +35,11 @@ function tryDequeueNextJob(shard, queue, now, ctx) {
             // Expired entries are not parked: they are genuinely removed from the
             // logical queue and therefore update counters/index exactly once.
             if (isExpired(job, now)) {
+                // Delete persistence before mutating the in-memory indexes. deleteJob
+                // also removes a pending buffered INSERT, so the expired job cannot be
+                // flushed after this pull or resurrect during crash recovery. This is
+                // synchronous and therefore keeps the shard critical section await-free.
+                ctx.storage?.deleteJob(job.id);
                 q.pop();
                 shard.decrementQueued(job.id);
                 ctx.jobIndex.delete(job.id);

package/dist/application/operations/push.js

@@ -2,80 +2,13 @@
  * Push Operations
  * Job push and batch push logic
  */
-import { createJob, generateJobId, jobId, } from '../../domain/types/job';
-import { withWriteLock } from '../../shared/lock';
+import { createJob } from '../../domain/types/job';
 import { shardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
 import { throughputTracker } from '../throughputTracker';
-/**
- * Handle custom ID idempotency check
- * Returns existing job if found, or new ID to use
- */
-function handleCustomId(input, shard, ctx) {
-    if (!input.customId) {
-        return { skip: false, id: generateJobId() };
-    }
-    const id = jobId(input.customId);
-    const existing = ctx.customIdMap.get(input.customId);
-    // Re-adding an existing custom id while its job is UNFINISHED is an idempotent
-    // no-op (BullMQ parity): return the existing job, never a second insert of the
-    // same deterministic id (which would collide on the jobs.id PRIMARY KEY). Three
-    // unfinished states are covered:
-    //   • waiting/delayed/prioritized — live in the priority queue → return the job.
-    //   • waiting-children — tracked under 'queue' but held in shard.waitingDeps (its
-    //     row is already persisted) → idempotent skip via the existing id.
-    //   • active (processing) — popped from the queue, still running on a worker; its
-    //     row survives on disk → idempotent skip via the existing id.
-    // PushContext has no processingShards, so for the latter two we cannot fetch the
-    // live Job here; pushJob rebuilds a placeholder { ...job, id } after createJob,
-    // exactly like handleDeduplication's active path. Completed (#92) and DLQ jobs
-    // are terminal and fall through to the reuse path below.
-    if (existing && !ctx.completedJobs.has(id)) {
-        const location = ctx.jobIndex.get(existing);
-        if (location?.type === 'queue') {
-            const existingJob = shard.getQueue(location.queueName).find(existing);
-            if (existingJob) {
-                return { skip: true, existingJob };
-            }
-            if (shard.waitingDeps.has(existing)) {
-                return { skip: true, existingId: id };
-            }
-        }
-        else if (location?.type === 'processing') {
-            return { skip: true, existingId: id };
-        }
-    }
-    // Reuse path: the id is free in the queue (no mapping, or the prior job is
-    // processing/completed). If the prior job COMPLETED, its row survives on disk
-    // (markCompleted does an UPDATE, not a DELETE) and it is still in completedJobs.
-    // Reusing the same deterministic id would then (a) make getJobState return
-    // 'completed' for the brand-new job and (b) collide on the `jobs.id` PRIMARY KEY
-    // at flush time. Evict the stale completed job so the reused id starts fresh as
-    // 'waiting' (#92). Checked regardless of customIdMap state — the mapping may have
-    // been cleared on completion, which would otherwise skip this path entirely.
-    if (ctx.completedJobs.has(id)) {
-        ctx.completedJobs.delete(id);
-        ctx.completedJobsData.delete(id);
-        ctx.jobResults.delete(id);
-        ctx.jobIndex.delete(id);
-        ctx.storage?.deleteJob(id); // removes the surviving row + result + any buffered insert
-    }
-    // NOTE on ORPHAN rows: a durable jobs row can outlive its in-memory tracking when
-    // obliterate() (fire-and-forget void over TCP) or a buffer flush races an in-flight
-    // durable insert. Reaching the reuse path with such a stale row no longer throws —
-    // the insert statements use ON CONFLICT(id) DO UPDATE (upsert), so the orphan is
-    // overwritten in place at insert time with ZERO per-push cost. We deliberately do
-    // NOT pre-delete here: deleteJob() is a synchronous DELETE + O(buffer) scan inside
-    // the shard lock and would halve customId push/addBulk throughput.
-    // A recycled custom id may carry a stale timeout marker from a prior job (which
-    // may have DLQ'd, so it is NOT in completedJobs above). Clear it so the new
-    // job's stall-retry recovery is not wrongly discarded — otherwise the
-    // timeout-resurrection guard would reintroduce #33/#75 duplicate execution for
-    // reused ids.
-    ctx.timedOutJobs?.delete(id);
-    ctx.customIdMap.set(input.customId, id);
-    return { skip: false, id };
-}
+import { handleCustomId } from './customId';
+import { insertJobToShard } from './pushInsert';
+import { withPushWriteLocks } from './pushLocks';
 /**
  * Handle unique key deduplication
  * Returns existing job ID if duplicate found and should skip, or allows insert
@@ -143,34 +76,6 @@ function handleDeduplication(job, input, queue, shard, ctx) {
     shard.registerUniqueKeyWithTtl(queue, job.uniqueKey, job.id, input.dedup?.ttl);
     return { skip: false };
 }
-/**
- * Insert job into shard (queue or waitingDeps)
- */
-function insertJobToShard(job, queue, shard, shardIdx, ctx) {
-    const hasDeps = job.dependsOn.length > 0;
-    const needsWaiting = hasDeps &&
-        !job.dependsOn.every((depId) => ctx.completedJobs.has(depId) || (ctx.depCompletions?.has(depId) ?? false));
-    const now = Date.now();
-    if (needsWaiting) {
-        shard.waitingDeps.set(job.id, job);
-        shard.registerDependencies(job.id, job.dependsOn);
-        job.timeline.push({ state: 'waiting-children', timestamp: now });
-        ctx.dashboardEmit?.('job:waiting-children', {
-            jobId: String(job.id),
-            queue,
-            dependsOn: job.dependsOn.map(String),
-        });
-    }
-    else {
-        shard.getQueue(queue).push(job);
-        const isDelayed = job.runAt > now;
-        shard.incrementQueued(job.id, isDelayed, job.createdAt, queue, job.runAt);
-        // Timeline: initial state based on scheduling and priority
-        const state = isDelayed ? 'delayed' : job.priority > 0 ? 'prioritized' : 'waiting';
-        job.timeline.push({ state, timestamp: now });
-    }
-    ctx.jobIndex.set(job.id, { type: 'queue', shardIdx, queueName: queue });
-}
 /**
  * Push a single job to queue
  * NOTE: customId check happens INSIDE lock to prevent race conditions
@@ -180,10 +85,10 @@ export async function pushJob(queue, input, ctx) {
     const idx = shardIndex(queue);
     const now = Date.now();
     let result;
-    await withWriteLock(ctx.shardLocks[idx], () => {
+    await withPushWriteLocks(queue, [input], ctx, (lockedShardIndexes) => {
         const shard = ctx.shards[idx];
         // Check custom ID idempotency INSIDE lock to prevent race conditions
-        const customIdResult = handleCustomId(input, shard, ctx);
+        const customIdResult = handleCustomId(input, ctx, lockedShardIndexes);
         if (customIdResult.skip) {
             // Idempotent re-add: return the live queued job if we have it, otherwise
             // (active / waiting-children) a placeholder carrying the existing id so the
@@ -247,11 +152,11 @@ export async function pushJobBatch(queue, inputs, ctx) {
     // path), exactly like a single durable push — otherwise addBulk silently
     // downgrades the documented "durable" guarantee.
     const durableJobs = [];
-    await withWriteLock(ctx.shardLocks[idx], () => {
+    await withPushWriteLocks(queue, inputs, ctx, (lockedShardIndexes) => {
         const shard = ctx.shards[idx];
         for (const input of inputs) {
             // Check custom ID idempotency
-            const customIdResult = handleCustomId(input, shard, ctx);
+            const customIdResult = handleCustomId(input, ctx, lockedShardIndexes);
             if (customIdResult.skip) {
                 // Idempotent re-add (queued, active, or waiting-children) — no insert.
                 resultIds.push('existingJob' in customIdResult

package/dist/application/operations/pushInsert.d.ts

@@ -0,0 +1,12 @@
+import type { Shard } from '../../domain/queue/shard';
+import type { Job, JobId } from '../../domain/types/job';
+import type { JobLocation } from '../../domain/types/queue';
+import type { SetLike } from '../../shared/lru';
+export interface PushInsertContext {
+    completedJobs: SetLike<JobId>;
+    depCompletions?: SetLike<JobId>;
+    jobIndex: Map<JobId, JobLocation>;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+}
+/** Insert a new job into the runnable heap or dependency wait set. */
+export declare function insertJobToShard(job: Job, queue: string, shard: Shard, shardIdx: number, ctx: PushInsertContext): void;

package/dist/application/operations/pushInsert.js

@@ -0,0 +1,25 @@
+/** Insert a new job into the runnable heap or dependency wait set. */
+export function insertJobToShard(job, queue, shard, shardIdx, ctx) {
+    const hasDeps = job.dependsOn.length > 0;
+    const needsWaiting = hasDeps &&
+        !job.dependsOn.every((depId) => ctx.completedJobs.has(depId) || (ctx.depCompletions?.has(depId) ?? false));
+    const now = Date.now();
+    if (needsWaiting) {
+        shard.waitingDeps.set(job.id, job);
+        shard.registerDependencies(job.id, job.dependsOn);
+        job.timeline.push({ state: 'waiting-children', timestamp: now });
+        ctx.dashboardEmit?.('job:waiting-children', {
+            jobId: String(job.id),
+            queue,
+            dependsOn: job.dependsOn.map(String),
+        });
+    }
+    else {
+        shard.getQueue(queue).push(job);
+        const isDelayed = job.runAt > now;
+        shard.incrementQueued(job.id, isDelayed, job.createdAt, queue, job.runAt);
+        const state = isDelayed ? 'delayed' : job.priority > 0 ? 'prioritized' : 'waiting';
+        job.timeline.push({ state, timestamp: now });
+    }
+    ctx.jobIndex.set(job.id, { type: 'queue', shardIdx, queueName: queue });
+}

package/dist/application/operations/pushLocks.d.ts

@@ -0,0 +1,14 @@
+import type { JobId, JobInput } from '../../domain/types/job';
+import type { JobLocation } from '../../domain/types/queue';
+import type { RWLock } from '../../shared/lock';
+interface PushLockContext {
+    shardLocks: RWLock[];
+    jobIndex: Map<JobId, JobLocation>;
+}
+/**
+ * Lock the target shard plus any shard owning a terminal custom-ID generation.
+ * The required set is rechecked after acquisition because jobIndex may change
+ * while an earlier lock is awaited.
+ */
+export declare function withPushWriteLocks<T>(queue: string, inputs: readonly JobInput[], ctx: PushLockContext, fn: (lockedShardIndexes: ReadonlySet<number>) => T): Promise<T>;
+export {};

package/dist/application/operations/pushLocks.js

@@ -0,0 +1,43 @@
+import { jobId } from '../../domain/types/job';
+import { shardIndex } from '../../shared/hash';
+function requiredShardIndexes(queue, inputs, jobIndex) {
+    const indexes = new Set([shardIndex(queue)]);
+    for (const input of inputs) {
+        if (!input.customId)
+            continue;
+        const location = jobIndex.get(jobId(input.customId));
+        if (location?.type === 'queue') {
+            indexes.add(location.shardIdx);
+        }
+        else if (location?.type === 'dlq') {
+            indexes.add(shardIndex(location.queueName));
+        }
+    }
+    return [...indexes].sort((a, b) => a - b);
+}
+/**
+ * Lock the target shard plus any shard owning a terminal custom-ID generation.
+ * The required set is rechecked after acquisition because jobIndex may change
+ * while an earlier lock is awaited.
+ */
+export async function withPushWriteLocks(queue, inputs, ctx, fn) {
+    while (true) {
+        const indexes = requiredShardIndexes(queue, inputs, ctx.jobIndex);
+        const guards = [];
+        try {
+            for (const index of indexes) {
+                guards.push(await ctx.shardLocks[index].acquireWrite());
+            }
+            const locked = new Set(indexes);
+            const current = requiredShardIndexes(queue, inputs, ctx.jobIndex);
+            if (current.some((index) => !locked.has(index)))
+                continue;
+            return fn(locked);
+        }
+        finally {
+            for (let i = guards.length - 1; i >= 0; i--) {
+                guards[i].release();
+            }
+        }
+    }
+}

package/dist/application/operations/queueControl.d.ts

@@ -30,7 +30,7 @@ export declare function isQueuePaused(queue: string, ctx: QueueControlContext):
 /** Drain all waiting jobs from queue */
 export declare function drainQueue(queue: string, ctx: QueueControlContext): number;
 /** Remove all queue data */
-export declare function obliterateQueue(queue: string, ctx: QueueControlContext): void;
+export declare function obliterateQueue(queue: string, ctx: QueueControlContext): JobId[];
 /** List all queue names */
 export declare function listAllQueues(ctx: QueueControlContext): string[];
 /**

package/dist/application/operations/queueControl.js

@@ -35,7 +35,7 @@ export function drainQueue(queue, ctx) {
 /** Remove all queue data */
 export function obliterateQueue(queue, ctx) {
     const idx = shardIndex(queue);
-    ctx.shards[idx].obliterate(queue);
+    return ctx.shards[idx].obliterate(queue);
 }
 /** List all queue names */
 export function listAllQueues(ctx) {

package/dist/application/queueManager.d.ts

@@ -6,7 +6,7 @@ import type { Job, JobId, JobInput, JobLock, LockToken } from '../domain/types/j
 import type { JobLocation, JobEvent } from '../domain/types/queue';
 import type { CronJob, CronJobInput } from '../domain/types/cron';
 import type { JobLogEntry, CreateWorkerOptions } from '../domain/types/worker';
-import type { StallConfig } from '../domain/types/stall';
+import { type StallConfig } from '../domain/types/stall';
 import type { DlqConfig, DlqEntry, DlqFilter, DlqStats } from '../domain/types/dlq';
 import { Shard } from '../domain/queue/shard';
 import { WebhookManager } from './webhookManager';
@@ -196,7 +196,7 @@ export declare class QueueManager {
     retryDlq(queue: string, jobId?: JobId, limit?: number): number;
     purgeDlq(queue: string): number;
     retryCompleted(queue: string, jobId?: JobId): number;
-    setRateLimit(queue: string, limit: number): void;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
     setConcurrency(queue: string, limit: number): void;
     clearConcurrency(queue: string): void;

package/dist/application/queueManager.js

@@ -3,6 +3,7 @@
  * Core orchestrator for all queue operations
  */
 import { DEFAULT_LOCK_TTL } from '../domain/types/job';
+import { DEFAULT_STALL_CONFIG } from '../domain/types/stall';
 import { Shard } from '../domain/queue/shard';
 import { SqliteStorage } from '../infrastructure/persistence/sqlite';
 import { CronScheduler } from '../infrastructure/scheduler/cronScheduler';
@@ -741,12 +742,12 @@ export class QueueManager {
         return count;
     }
     obliterate(queue) {
-        queueControl.obliterateQueue(queue, this.contextFactory.getQueueControlContext());
+        const shardJobs = queueControl.obliterateQueue(queue, this.contextFactory.getQueueControlContext());
         dlqOps.purgeDlqJobs(queue, this.contextFactory.getDlqContext());
-        // obliterateQueue() clears the waiting/delayed shard only. Active jobs in
-        // processingShards, plus completed/result/log/lock state in global indexes,
-        // plus SQLite rows, all survive unless we purge them here.
-        const toDrop = new Set();
+        // obliterateQueue() returns every queued, DLQ, and dependency-gated job it
+        // removed. Active jobs in processingShards, plus completed/result/log/lock
+        // state in global indexes, still need to be discovered and purged here.
+        const toDrop = new Set(shardJobs);
         for (const [jid, loc] of this.jobIndex) {
             if (loc.type === 'processing') {
                 const job = this.processingShards[loc.shardIdx]?.get(jid);
@@ -860,8 +861,8 @@ export class QueueManager {
         return dlqOps.retryCompletedJobs(queue, this.contextFactory.getRetryCompletedContext(), jobId);
     }
     // ============ Rate Limiting ============
-    setRateLimit(queue, limit) {
-        this.shards[shardIndex(queue)].setRateLimit(queue, limit);
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.shards[shardIndex(queue)].setRateLimit(queue, limit, durationMs, ttlMs);
         this.persistQueueState(queue);
     }
     clearRateLimit(queue) {
@@ -885,19 +886,37 @@ export class QueueManager {
         if (!this.storage)
             return;
         const state = this.shards[shardIndex(queue)].getState(queue);
+        const stallConfig = this.shards[shardIndex(queue)].getStallConfig(queue);
+        const hasCustomStallConfig = stallConfig.enabled !== DEFAULT_STALL_CONFIG.enabled ||
+            stallConfig.stallInterval !== DEFAULT_STALL_CONFIG.stallInterval ||
+            stallConfig.maxStalls !== DEFAULT_STALL_CONFIG.maxStalls ||
+            stallConfig.gracePeriod !== DEFAULT_STALL_CONFIG.gracePeriod;
         // When control-state returns fully to default (not paused, no limits), drop
         // the row instead of persisting an all-default placeholder. Keeps the table
         // free of noise rows for ephemeral queues that only ever call resume/clear*,
         // and recovers identically (absent row → default state).
-        if (!state.paused && state.rateLimit === null && state.concurrencyLimit === null) {
+        if (!state.paused &&
+            state.rateLimit === null &&
+            state.concurrencyLimit === null &&
+            !hasCustomStallConfig) {
             this.storage.deleteQueueState(queue);
             return;
         }
-        this.storage.saveQueueState(queue, state.paused, state.rateLimit, state.concurrencyLimit);
+        this.storage.saveQueueState(queue, {
+            paused: state.paused,
+            rateLimit: state.rateLimit,
+            concurrencyLimit: state.concurrencyLimit,
+            rateLimitDuration: state.rateLimitDuration,
+            rateLimitExpiresAt: state.rateLimitExpiresAt,
+            stallConfig,
+        });
     }
     /** Get rate limit and concurrency limit for a queue */
     getQueueLimits(queue) {
-        const state = this.shards[shardIndex(queue)].getState(queue);
+        const shard = this.shards[shardIndex(queue)];
+        // Lazy TTL expiry so reads never report a limit that no longer throttles.
+        shard.expireRateLimitIfNeeded(queue);
+        const state = shard.getState(queue);
         return { rateLimit: state.rateLimit, concurrencyLimit: state.concurrencyLimit };
     }
     /** Get all job results (for cloud telemetry) */
@@ -921,6 +940,7 @@ export class QueueManager {
     // ============ Stall & DLQ Config ============
     setStallConfig(queue, config) {
         this.shards[shardIndex(queue)].setStallConfig(queue, config);
+        this.persistQueueState(queue);
     }
     getStallConfig(queue) {
         return this.shards[shardIndex(queue)].getStallConfig(queue);

package/dist/application/stallDetection.js

@@ -66,6 +66,7 @@ async function handleStalledJob(job, action, ctx) {
     // Lock order: shardLocks BEFORE processingLocks (per lock hierarchy in CLAUDE.md)
     // Broadcast events AFTER verifying job is still stalled to avoid false positives
     let handled = false;
+    let handledAction = action;
     await withWriteLock(ctx.shardLocks[idx], async () => {
         await withWriteLock(ctx.processingLocks[procIdx], () => {
             // Verify job is still in processing (might have been handled already)
@@ -73,8 +74,10 @@ async function handleStalledJob(job, action, ctx) {
                 return; // Job already completed, don't broadcast stalled event
             }
             const shard = ctx.shards[idx];
-            if (action === "move_to_dlq" /* StallAction.MoveToDlq */) {
-                moveStalliedJobToDlq(job, ctx, shard, procIdx, idx);
+            const attemptsExhausted = job.attempts + 1 >= job.maxAttempts;
+            if (action === "move_to_dlq" /* StallAction.MoveToDlq */ || attemptsExhausted) {
+                handledAction = "move_to_dlq" /* StallAction.MoveToDlq */;
+                moveStalliedJobToDlq(job, ctx, shard, procIdx, attemptsExhausted);
             }
             else {
                 retryStalliedJob(job, ctx, shard, procIdx, idx);
@@ -87,23 +90,23 @@ async function handleStalledJob(job, action, ctx) {
         ctx.dashboardEmit?.('job:stalled', {
             jobId: String(job.id),
             queue: job.queue,
-            stallCount: job.stallCount + 1,
-            action,
+            stallCount: job.stallCount,
+            action: handledAction,
         });
         ctx.eventsManager.broadcast({
             eventType: "stalled" /* EventType.Stalled */,
             queue: job.queue,
             jobId: job.id,
             timestamp: Date.now(),
-            data: { stallCount: job.stallCount + 1, action },
+            data: { stallCount: job.stallCount, action: handledAction },
         });
         void ctx.webhookManager.trigger('stalled', String(job.id), job.queue, {
-            data: { stallCount: job.stallCount + 1, action },
+            data: { stallCount: job.stallCount, action: handledAction },
         });
     }
 }
 /** Move stalled job to DLQ */
-function moveStalliedJobToDlq(job, ctx, shard, procIdx, _idx) {
+function moveStalliedJobToDlq(job, ctx, shard, procIdx, attemptsExhausted) {
     ctx.processingShards[procIdx].delete(job.id);
     shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
     // Discard cron jobs with preventOverlap instead of sending to DLQ (#73).
@@ -112,7 +115,13 @@ function moveStalliedJobToDlq(job, ctx, shard, procIdx, _idx) {
         ctx.storage?.deleteJob(job.id);
         return;
     }
-    const entry = shard.addToDlq(job, "stalled" /* FailureReason.Stalled */, `Job stalled ${job.stallCount + 1} times`);
+    incrementStallCount(job);
+    job.attempts++;
+    job.startedAt = null;
+    job.lastHeartbeat = Date.now();
+    const entry = shard.addToDlq(job, attemptsExhausted ? "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */ : "stalled" /* FailureReason.Stalled */, attemptsExhausted
+        ? `Job stalled at max attempts (${job.maxAttempts})`
+        : `Job stalled ${job.stallCount} times`);
     ctx.jobIndex.set(job.id, { type: 'dlq', queueName: job.queue });
     ctx.storage?.saveDlqEntry(entry);
     ctx.storage?.deleteJob(job.id);

package/dist/client/queue/dlq.d.ts

@@ -3,7 +3,8 @@
  * Wraps dlqOps for Queue class usage
  */
 import type { TcpConnectionPool } from '../tcpPool';
-import type { DlqConfig, DlqEntry, DlqStats, DlqFilter } from '../types';
+import type { Job, DlqConfig, DlqEntry, DlqStats, DlqFilter } from '../types';
+import { type SimpleJobContext } from './jobProxy';
 interface DlqContext {
     name: string;
     embedded: boolean;
@@ -11,20 +12,41 @@ interface DlqContext {
 }
 /** Set DLQ configuration */
 export declare function setDlqConfig(ctx: DlqContext, config: Partial<DlqConfig>): void;
+/** Set DLQ configuration and resolve once the server has applied it. */
+export declare function setDlqConfigAsync(ctx: DlqContext, config: Partial<DlqConfig>): Promise<void>;
 /** Get DLQ configuration */
 export declare function getDlqConfig(ctx: DlqContext): DlqConfig;
 /** Get DLQ configuration (async, works in TCP mode) */
 export declare function getDlqConfigAsync(ctx: DlqContext): Promise<DlqConfig>;
 /** Get DLQ entries */
 export declare function getDlq<T>(ctx: DlqContext, filter?: DlqFilter): DlqEntry<T>[];
+type DlqQueryContext = DlqContext & Pick<SimpleJobContext, 'getJobState' | 'removeAsync' | 'retryJob' | 'getChildrenValues'>;
+/**
+ * Get the dead jobs in the DLQ, working over TCP too (wire command `Dlq`).
+ * Returns public Job objects; the wire does not carry DlqEntry metadata
+ * (reason, enteredAt, attempts) — that stays embedded-only via getDlq().
+ */
+export declare function getDlqJobsAsync<T>(ctx: DlqQueryContext, count?: number): Promise<Job<T>[]>;
 /** Get DLQ stats */
 export declare function getDlqStats(ctx: DlqContext): DlqStats;
 /** Retry DLQ entries */
 export declare function retryDlq(ctx: DlqContext, id?: string): number;
+/**
+ * Retry DLQ entries and resolve with the retried count once the server has
+ * processed it. The fire-and-forget retryDlq() always returns 0 over TCP and
+ * discards the server's count.
+ */
+export declare function retryDlqAsync(ctx: DlqContext, id?: string): Promise<number>;
 /** Retry DLQ entries by filter */
 export declare function retryDlqByFilter(ctx: DlqContext, filter: DlqFilter): number;
 /** Purge DLQ */
 export declare function purgeDlq(ctx: DlqContext): number;
+/**
+ * Purge the DLQ and resolve with the purged count once the server has
+ * processed it. The fire-and-forget purgeDlq() always returns 0 over TCP;
+ * purge-then-assert-empty patterns need this variant.
+ */
+export declare function purgeDlqAsync(ctx: DlqContext): Promise<number>;
 /** Retry completed job */
 export declare function retryCompleted(ctx: DlqContext, id?: string): number;
 /** Retry completed job (async) */