bunqueue 2.8.5 → 2.8.7

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

@@ -57,7 +57,7 @@ export declare function ackJob(jobId: JobId, result: unknown, ctx: AckContext):
 /**
  * Mark job as failed
  */
-export declare function failJob(jobId: JobId, error: string | undefined, ctx: AckContext): Promise<void>;
+export declare function failJob(jobId: JobId, error: string | undefined, ctx: AckContext, unrecoverable?: boolean): Promise<void>;
 /**
  * Acknowledge multiple jobs - optimized batch processing
  * Groups jobs by shard to minimize lock acquisitions: O(shards) instead of O(n)

package/dist/application/operations/ack.js

@@ -112,7 +112,7 @@ function moveFailedJobToDlq(job, jobId, error, shard, ctx) {
 /**
  * Mark job as failed
  */
-export async function failJob(jobId, error, ctx) {
+export async function failJob(jobId, error, ctx, unrecoverable = false) {
     const procIdx = processingShardIndex(jobId);
     const job = await withWriteLock(ctx.processingLocks[procIdx], () => {
         const job = ctx.processingShards[procIdx].get(jobId);
@@ -134,7 +134,7 @@ export async function failJob(jobId, error, ctx) {
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
-        if (canRetry(job)) {
+        if (!unrecoverable && canRetry(job)) {
             const now = Date.now();
             job.runAt = now + calculateBackoff(job);
             shard.getQueue(job.queue).push(job);

package/dist/application/queueManager.d.ts

@@ -79,7 +79,7 @@ export declare class QueueManager {
         result: unknown;
         token?: string;
     }>): Promise<void>;
-    fail(jobId: JobId, error?: string, token?: string): Promise<void>;
+    fail(jobId: JobId, error?: string, token?: string, unrecoverable?: boolean): Promise<void>;
     /**
      * Check if a failed lock verification is a genuine ownership conflict.
      * If the job is still in processing with a different lock, throw.

package/dist/application/queueManager.js

@@ -358,7 +358,7 @@ export class QueueManager {
             lockMgr.releaseLock(item.id, lockCtx, item.token);
         }
     }
-    async fail(jobId, error, token) {
+    async fail(jobId, error, token, unrecoverable = false) {
         const lockCtx = this.contextFactory.getLockContext();
         if (token && !lockMgr.verifyLock(jobId, token, lockCtx)) {
             this.throwIfOwnershipConflict(jobId, lockCtx);
@@ -367,7 +367,7 @@ export class QueueManager {
                 return;
         }
         try {
-            await failJob(jobId, error, this.contextFactory.getAckContext());
+            await failJob(jobId, error, this.contextFactory.getAckContext(), unrecoverable);
         }
         catch (err) {
             // Job removed from processing by stall detection. The stall retry

package/dist/application/statsManager.js

@@ -3,6 +3,16 @@
  * Provides system metrics and memory compaction utilities
  */
 import { SHARD_COUNT, shardIndex } from '../shared/hash';
+/** Count jobs belonging to `queueName` across one or more job iterables. */
+function countByQueue(sources, queueName) {
+    let count = 0;
+    for (const src of sources) {
+        for (const job of src)
+            if (job.queue === queueName)
+                count++;
+    }
+    return count;
+}
 /**
  * Get queue statistics - uses running counters + priority scan
  */
@@ -14,7 +24,10 @@ export function getStats(ctx, cronScheduler) {
         delayed += shardStats.delayedJobs;
         dlq += shardStats.dlqJobs;
         active += ctx.processingShards[i].size;
-        waitingChildren += ctx.shards[i].waitingChildren.size;
+        // getJobState reports BOTH waitingChildren (flow parents) and waitingDeps
+        // (jobs blocked on dependsOn) as state 'waiting-children', and getJobs lists
+        // both — so the count must include both or it undercounts vs state/list (#95 class).
+        waitingChildren += ctx.shards[i].waitingChildren.size + ctx.shards[i].waitingDeps.size;
         // Scan queues to split waiting vs prioritized (BullMQ v5 compat)
         for (const queue of ctx.shards[i].queues.values()) {
             for (const job of queue.values()) {
@@ -174,13 +187,10 @@ export function getQueueJobCounts(queueName, ctx) {
     }
     // Count failed (DLQ) jobs for this queue
     const failed = shard.getDlq(queueName).length;
-    // Count waiting-children jobs (parents waiting for child completion)
-    let waitingChildrenCount = 0;
-    for (const job of shard.waitingChildren.values()) {
-        if (job.queue === queueName) {
-            waitingChildrenCount++;
-        }
-    }
+    // Count waiting-children jobs. getJobState/getJobs treat BOTH waitingChildren
+    // (flow parents) and waitingDeps (jobs blocked on dependsOn) as 'waiting-children',
+    // so count both to stay consistent with state/list (#95 class).
+    const waitingChildrenCount = countByQueue([shard.waitingChildren.values(), shard.waitingDeps.values()], queueName);
     // Per-queue cumulative counters
     const perQueue = ctx.perQueueMetrics?.get(queueName);
     const totalCompleted = Number(perQueue?.totalCompleted ?? 0n);

package/dist/client/queue/dlq.js

@@ -64,7 +64,7 @@ export function retryDlq(ctx, id) {
     if (ctx.embedded)
         return dlqOps.retryDlqEmbedded(ctx.name, id);
     if (ctx.tcp)
-        void ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, id });
+        void ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, jobId: id });
     return 0;
 }
 /** Retry DLQ entries by filter */

package/dist/client/queue/operations/management.js

@@ -77,7 +77,8 @@ export async function cleanAsync(ctx, grace, limit, type) {
         queue: ctx.name,
         grace,
         limit,
-        type,
+        // Handler reads `state`; sending `type` made the state filter a no-op.
+        state: type,
     });
     if (!response.ok)
         return [];
@@ -107,7 +108,8 @@ export async function promoteJobs(ctx, opts) {
     });
     if (!response.ok)
         return 0;
-    return (response.promoted ?? 0);
+    // Handler returns `count`; reading `promoted` always yielded 0.
+    return (response.count ?? 0);
 }
 /** Promote a single job */
 export async function promoteJob(ctx, id) {

package/dist/client/queue/queue.js

@@ -63,6 +63,7 @@ export class Queue {
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,
+                    maxCommandTimeouts: connOpts.maxCommandTimeouts,
                     pipelining: connOpts.pipelining,
                     maxInFlight: connOpts.maxInFlight,
                 });
@@ -76,6 +77,7 @@ export class Queue {
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,
+                    maxCommandTimeouts: connOpts.maxCommandTimeouts,
                     pipelining: connOpts.pipelining,
                     maxInFlight: connOpts.maxInFlight,
                 });

package/dist/client/queue/scheduler.js

@@ -65,6 +65,9 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
     const dedupFields = buildCronDedup(jobTemplate);
     const jobOptions = buildCronJobOptions(ctx.defaultJobOptions, jobTemplate);
     const cronName = toCronName(ctx, schedulerId);
+    // Priority of spawned jobs: carried on the top-level Cron field (the handler
+    // reads cmd.priority), which buildCronJobOptions does not cover.
+    const priority = jobTemplate?.opts?.priority ?? ctx.defaultJobOptions?.priority;
     if (ctx.embedded) {
         const manager = getSharedManager();
         manager.addCron({
@@ -73,6 +76,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
             data,
             schedule: cronPattern,
             repeatEvery,
+            priority,
             timezone: repeatOpts.timezone ?? 'UTC',
             skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
             immediately: repeatOpts.immediately,
@@ -94,6 +98,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
         data,
         schedule: cronPattern,
         repeatEvery,
+        priority,
         timezone: repeatOpts.timezone,
         skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
         immediately: repeatOpts.immediately,

package/dist/client/tcp/client.d.ts

@@ -73,6 +73,15 @@ export declare class TcpClient extends EventEmitter {
     /** Send ping to check connection health */
     ping(): Promise<boolean>;
     private handlePingFailure;
+    /**
+     * A command timed out. On a half-open socket (peer gone, no FIN/RST) writes
+     * keep succeeding but no response ever returns — every command times out
+     * while the socket still looks "connected". The health-check ping is one way
+     * to notice, but it can be disabled or slower than real traffic, leaving a
+     * worker's PULL loop to time out forever without ever reconnecting (#94).
+     * Treat a sustained run of timeouts as a dead link and force a reconnect.
+     */
+    private handleCommandTimeout;
     private forceReconnect;
     /** Get connection health metrics */
     getHealth(): ConnectionHealth;

package/dist/client/tcp/client.js

@@ -79,6 +79,7 @@ export class TcpClient extends EventEmitter {
         this.health = new HealthTracker({
             pingInterval: this.options.pingInterval,
             maxPingFailures: this.options.maxPingFailures,
+            maxCommandTimeouts: this.options.maxCommandTimeouts,
         });
         this.reconnect = new ReconnectManager({
             maxReconnectAttempts: this.options.maxReconnectAttempts,
@@ -258,15 +259,44 @@ export class TcpClient extends EventEmitter {
             this.emit('health', { type: 'ping_failed' });
         }
     }
+    /**
+     * A command timed out. On a half-open socket (peer gone, no FIN/RST) writes
+     * keep succeeding but no response ever returns — every command times out
+     * while the socket still looks "connected". The health-check ping is one way
+     * to notice, but it can be disabled or slower than real traffic, leaving a
+     * worker's PULL loop to time out forever without ever reconnecting (#94).
+     * Treat a sustained run of timeouts as a dead link and force a reconnect.
+     */
+    handleCommandTimeout() {
+        if (this.health.recordCommandTimeout()) {
+            this.emit('health', { type: 'unhealthy', reason: 'max_command_timeouts' });
+            this.forceReconnect();
+        }
+    }
     forceReconnect() {
         if (this.reconnect.isClosed())
             return;
         if (this.socket) {
-            this.socket.end();
+            // end() can throw on an already-errored/half-dead socket. Swallow it:
+            // failing to close the corpse must NOT abort the reconnect path below,
+            // or the connection would stay wedged forever (the #94 failure mode).
+            try {
+                this.socket.end();
+            }
+            catch {
+                /* socket already torn down */
+            }
             this.socket = null;
         }
         this.connected = false;
         this.health.stopPing();
+        // Settle every in-flight/queued command NOW. Otherwise their per-command
+        // timeouts keep ticking and fire AFTER the fresh socket is up — each stale
+        // timeout bumps the new connection's dead-link counter and can re-trigger
+        // forceReconnect in a loop (a reconnect storm that never stabilises). It
+        // also unblocks awaiting callers (e.g. a Worker's PULL) immediately instead
+        // of making them wait out the full commandTimeout on a corpse.
+        this.commands.rejectAll(new Error('Connection lost'));
         if (this.reconnect.canReconnect())
             this.reconnect.scheduleReconnect(() => this.connect());
     }
@@ -343,6 +373,8 @@ export class TcpClient extends EventEmitter {
                 if (removed) {
                     this.health.recordError();
                     next.reject(new Error('Command timeout'));
+                    // In-flight command got no response: count it toward dead-link detection.
+                    this.handleCommandTimeout();
                 }
             }, this.options.commandTimeout);
             next.timeout = newTimeout;
@@ -365,17 +397,20 @@ export class TcpClient extends EventEmitter {
         let pendingRef;
         const promise = new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
-                // Try to remove from queue first
+                // Try to remove from queue first. A still-queued command never reached
+                // the socket (e.g. waiting on connect), so it is NOT evidence of a dead
+                // link — reject it but don't count it toward dead-link detection.
                 if (this.commands.remove(id)) {
                     this.health.recordError();
                     reject(new Error('Command timeout'));
                     return;
                 }
-                // Try to remove from in-flight
+                // Try to remove from in-flight: this one WAS sent and got no response.
                 const removed = this.commands.removeByReqId(reqId);
                 if (removed) {
                     this.health.recordError();
                     reject(new Error('Command timeout'));
+                    this.handleCommandTimeout();
                 }
             }, this.options.commandTimeout);
             pendingRef = {

package/dist/client/tcp/connection.js

@@ -42,6 +42,17 @@ export async function createConnection(target, connectTimeout, events) {
             },
             open(sock) {
                 cleanup();
+                // Enable TCP keepalive so the OS probes idle connections and surfaces a
+                // dead peer (suspended host, NAT/LB drop) via an error/close event,
+                // instead of a half-open socket lingering until tcp_retries2 (~15 min).
+                // Best-effort: not all platforms honor the delay, and older Bun builds
+                // may lack the method — never let it abort connection setup. See #94.
+                try {
+                    sock.setKeepAlive?.(true, 15000);
+                }
+                catch {
+                    /* keepalive unsupported on this platform/runtime */
+                }
                 socketData.write = (d) => sock.write(d);
                 socketData.end = () => sock.end();
                 connectionResolved = true;

package/dist/client/tcp/health.d.ts

@@ -7,6 +7,11 @@ import type { ConnectionHealth } from './types';
 export interface HealthConfig {
     pingInterval: number;
     maxPingFailures: number;
+    /**
+     * Consecutive command timeouts before the link is concluded dead (0 = off).
+     * Optional for backward compatibility; defaults to 3 when omitted.
+     */
+    maxCommandTimeouts?: number;
 }
 /**
  * Tracks connection health metrics
@@ -14,6 +19,7 @@ export interface HealthConfig {
 export declare class HealthTracker {
     private readonly config;
     private consecutivePingFailures;
+    private consecutiveCommandTimeouts;
     private lastSuccessAt;
     private lastErrorAt;
     private connectedAt;
@@ -35,6 +41,14 @@ export declare class HealthTracker {
     recordPingSuccess(latencyMs: number): void;
     /** Record ping failure, returns true if max failures reached */
     recordPingFailure(): boolean;
+    /**
+     * Record a command timeout. Returns true when the configured consecutive
+     * threshold is reached (and the feature is enabled), signalling the caller to
+     * force a reconnect. Any intervening success resets the counter, so this only
+     * fires on a sustained run of timeouts — the signature of a dead/half-open
+     * socket where writes succeed but no response ever comes back.
+     */
+    recordCommandTimeout(): boolean;
     /** Get current health metrics */
     getHealth(state: 'connected' | 'connecting' | 'disconnected' | 'closed'): ConnectionHealth;
     /** Start ping timer */

package/dist/client/tcp/health.js

@@ -2,12 +2,15 @@
  * TCP Health Tracker
  * Monitors connection health with ping and latency tracking
  */
+/** Default consecutive command-timeout threshold when not configured. */
+const DEFAULT_MAX_COMMAND_TIMEOUTS = 3;
 /**
  * Tracks connection health metrics
  */
 export class HealthTracker {
     config;
     consecutivePingFailures = 0;
+    consecutiveCommandTimeouts = 0;
     lastSuccessAt = null;
     lastErrorAt = null;
     connectedAt = null;
@@ -23,6 +26,9 @@ export class HealthTracker {
     recordSuccess(latencyMs) {
         this.lastSuccessAt = Date.now();
         this.totalCommands++;
+        // A real response proves the link is alive: the prior timeouts were not a
+        // sustained run, so reset the dead-link counter ("consecutive" must mean it).
+        this.consecutiveCommandTimeouts = 0;
         this.recordLatency(latencyMs);
     }
     /** Record command error */
@@ -38,10 +44,13 @@ export class HealthTracker {
     recordConnected() {
         this.connectedAt = Date.now();
         this.consecutivePingFailures = 0;
+        this.consecutiveCommandTimeouts = 0;
     }
     /** Record ping success */
     recordPingSuccess(latencyMs) {
+        // A successful ping is also proof the link is alive — clear both suspicions.
         this.consecutivePingFailures = 0;
+        this.consecutiveCommandTimeouts = 0;
         this.recordLatency(latencyMs);
     }
     /** Record ping failure, returns true if max failures reached */
@@ -51,6 +60,20 @@ export class HealthTracker {
         this.totalErrors++;
         return this.consecutivePingFailures >= this.config.maxPingFailures;
     }
+    /**
+     * Record a command timeout. Returns true when the configured consecutive
+     * threshold is reached (and the feature is enabled), signalling the caller to
+     * force a reconnect. Any intervening success resets the counter, so this only
+     * fires on a sustained run of timeouts — the signature of a dead/half-open
+     * socket where writes succeed but no response ever comes back.
+     */
+    recordCommandTimeout() {
+        const max = this.config.maxCommandTimeouts ?? DEFAULT_MAX_COMMAND_TIMEOUTS;
+        if (max <= 0)
+            return false;
+        this.consecutiveCommandTimeouts++;
+        return this.consecutiveCommandTimeouts >= max;
+    }
     /** Get current health metrics */
     getHealth(state) {
         const avgLatency = this.latencyHistory.length > 0
@@ -63,6 +86,7 @@ export class HealthTracker {
             lastErrorAt: this.lastErrorAt,
             avgLatencyMs: Math.round(avgLatency * 100) / 100,
             consecutivePingFailures: this.consecutivePingFailures,
+            consecutiveCommandTimeouts: this.consecutiveCommandTimeouts,
             totalCommands: this.totalCommands,
             totalErrors: this.totalErrors,
             uptimeMs: this.connectedAt ? Date.now() - this.connectedAt : 0,

package/dist/client/tcp/types.d.ts

@@ -26,6 +26,14 @@ export interface ConnectionOptions {
     pingInterval?: number;
     /** Max consecutive ping failures before forcing reconnect (default: 3) */
     maxPingFailures?: number;
+    /**
+     * Max consecutive command timeouts (with no intervening success) before the
+     * connection is concluded dead and reconnect is forced (default: 3, 0 to
+     * disable). This is the recovery path for a half-open socket when the
+     * health-check ping is disabled or slower than real traffic — a worker whose
+     * PULLs keep timing out no longer stalls forever waiting on the ping. See #94.
+     */
+    maxCommandTimeouts?: number;
     /** Enable pipelining - multiple commands in flight (default: true) */
     pipelining?: boolean;
     /** Max commands in flight when pipelining (default: 100) */
@@ -45,6 +53,8 @@ export interface ConnectionHealth {
     avgLatencyMs: number;
     /** Consecutive ping failures */
     consecutivePingFailures: number;
+    /** Consecutive command timeouts with no intervening success */
+    consecutiveCommandTimeouts: number;
     /** Total commands sent */
     totalCommands: number;
     /** Total errors */

package/dist/client/tcp/types.js

@@ -15,6 +15,7 @@ export const DEFAULT_CONNECTION = {
     autoReconnect: true,
     pingInterval: 30000,
     maxPingFailures: 3,
+    maxCommandTimeouts: 3,
     pipelining: true,
     maxInFlight: 100,
 };

package/dist/client/tcpPool.js

@@ -29,6 +29,7 @@ export class TcpConnectionPool {
             autoReconnect: options.autoReconnect ?? true,
             pingInterval: options.pingInterval ?? 30000,
             maxPingFailures: options.maxPingFailures ?? 3,
+            maxCommandTimeouts: options.maxCommandTimeouts ?? 3,
             pipelining: options.pipelining ?? true,
             maxInFlight: options.maxInFlight ?? 100,
         };
@@ -46,6 +47,7 @@ export class TcpConnectionPool {
                 autoReconnect: this.options.autoReconnect,
                 pingInterval: this.options.pingInterval,
                 maxPingFailures: this.options.maxPingFailures,
+                maxCommandTimeouts: this.options.maxCommandTimeouts,
             });
             this.clients.push(client);
         }

package/dist/client/types.d.ts

@@ -376,6 +376,12 @@ export interface ConnectionOptions {
     pingInterval?: number;
     /** Command timeout in ms (default: 30000) */
     commandTimeout?: number;
+    /**
+     * Consecutive command timeouts (no intervening success) before the connection
+     * is concluded dead and a reconnect is forced (default: 3, 0 to disable).
+     * Recovery path for a half-open socket independent of the health-check ping. See #94.
+     */
+    maxCommandTimeouts?: number;
     /** Enable TCP pipelining (default: true) */
     pipelining?: boolean;
     /** Max commands in flight per connection (default: 100) */

package/dist/client/worker/worker.js

@@ -47,6 +47,7 @@ function createTcpPool(opts, concurrency) {
         poolSize,
         pingInterval: connOpts.pingInterval,
         commandTimeout: connOpts.commandTimeout,
+        maxCommandTimeouts: connOpts.maxCommandTimeouts,
         pipelining: connOpts.pipelining,
         maxInFlight: connOpts.maxInFlight,
     });
@@ -397,9 +398,12 @@ export class Worker extends EventEmitter {
             cmd: 'ExtendLocks',
             ids: jobIds,
             tokens,
-            duration,
+            // Protocol expects a per-id `durations` array, and the handler returns
+            // `count` (not `extended`). Sending `duration`/reading `extended` made
+            // batch lock renewal silently keep the old TTL.
+            durations: jobIds.map(() => duration),
         });
-        const extended = response.extended;
+        const extended = response.count;
         return extended ?? 0;
     }
     // ============ Lifecycle ============
@@ -734,6 +738,7 @@ export class Worker extends EventEmitter {
             workerId: this.workerId,
             useLocks: this.opts.useLocks,
             pollTimeout: this.opts.pollTimeout,
+            lockDuration: this.opts.lockDuration,
         };
     }
     /** Apply worker-level removeOnComplete/removeOnFail defaults to a job */

package/dist/client/worker/workerPull.d.ts

@@ -9,6 +9,8 @@ export interface PullConfig {
     readonly workerId: string;
     readonly useLocks: boolean;
     readonly pollTimeout: number;
+    /** Lock TTL in ms to request from the server on a lock-based pull. */
+    readonly lockDuration?: number;
 }
 export declare function pullEmbedded(config: PullConfig, count: number): Promise<Array<{
     job: InternalJob;

package/dist/client/worker/workerPull.js

@@ -6,13 +6,14 @@ import { getSharedManager } from '../manager';
 import { parseJobFromResponse } from './jobParser';
 export async function pullEmbedded(config, count) {
     const manager = getSharedManager();
-    // Use lock-based pull only when useLocks is enabled
+    // Use lock-based pull only when useLocks is enabled. Pass lockDuration so the
+    // configured lock TTL is honored in embedded mode too (undefined → server default).
     if (config.useLocks) {
         if (count === 1) {
-            const { job, token } = await manager.pullWithLock(config.name, config.workerId, 0);
+            const { job, token } = await manager.pullWithLock(config.name, config.workerId, 0, config.lockDuration);
             return job ? [{ job, token }] : [];
         }
-        const { jobs, tokens } = await manager.pullBatchWithLock(config.name, count, config.workerId, 0);
+        const { jobs, tokens } = await manager.pullBatchWithLock(config.name, count, config.workerId, 0, config.lockDuration);
         return jobs.map((job, i) => ({ job, token: tokens[i] || null }));
     }
     // No locks - use regular pull
@@ -26,16 +27,22 @@ export async function pullEmbedded(config, count) {
 export async function pullTcp(config, tcp, count, closing) {
     if (closing)
         return [];
-    // Build pull command - only request locks if useLocks is enabled
+    // Build pull command - only request locks if useLocks is enabled.
+    // `count` belongs to the batch PULLB; a single PULL doesn't need it.
     const cmd = {
         cmd: count === 1 ? 'PULL' : 'PULLB',
         queue: config.name,
         timeout: config.pollTimeout,
-        count,
     };
+    if (count > 1)
+        cmd.count = count;
     // Only request lock ownership when useLocks is enabled
     if (config.useLocks) {
         cmd.owner = config.workerId;
+        // Propagate the configured lock TTL so the server doesn't always fall back
+        // to its 30s default (WorkerOptions.lockDuration was previously ignored).
+        if (config.lockDuration !== undefined)
+            cmd.lockTtl = config.lockDuration;
     }
     const response = await tcp.send(cmd);
     if (!response.ok)

package/dist/domain/types/command.d.ts

@@ -98,6 +98,8 @@ export interface FailCommand extends BaseCommand {
     readonly id: string;
     readonly error?: string;
     readonly token?: string;
+    /** Skip all remaining retries and fail terminally (UnrecoverableError over TCP). */
+    readonly unrecoverable?: boolean;
 }
 export interface GetJobCommand extends BaseCommand {
     readonly cmd: 'GetJob';
@@ -309,6 +311,8 @@ export interface AddLogCommand extends BaseCommand {
 export interface GetLogsCommand extends BaseCommand {
     readonly cmd: 'GetLogs';
     readonly id: string;
+    readonly start?: number;
+    readonly end?: number;
 }
 export interface HeartbeatCommand extends BaseCommand {
     readonly cmd: 'Heartbeat';

package/dist/infrastructure/server/handlers/advanced.js

@@ -4,6 +4,45 @@
  */
 import * as resp from '../../../domain/types/response';
 import { jobId } from '../../../domain/types/job';
+/**
+ * Coerce a value to a finite number, or return undefined if it can't be.
+ * Guards config endpoints against non-numeric input (e.g. `"abc"`) that would
+ * otherwise reach numeric comparisons as NaN and silently break behaviour
+ * (a string `stallInterval` disabled stall detection entirely).
+ */
+function toFiniteNumber(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Sanitize the numeric fields of a config object: coerce numeric strings, drop
+ * non-numeric garbage (so the manager's merge keeps the existing/default value
+ * instead of storing NaN). Booleans and unknown keys pass through untouched.
+ */
+function sanitizeConfigNumbers(config, numericKeys) {
+    if (!config || typeof config !== 'object')
+        return config;
+    const numeric = new Set(numericKeys);
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (!numeric.has(key)) {
+            out[key] = value; // booleans / unknown keys pass through untouched
+            continue;
+        }
+        if (value === null) {
+            out[key] = null; // valid for nullable fields (e.g. dlq maxAge)
+            continue;
+        }
+        const n = toFiniteNumber(value);
+        // coerce numeric strings; omit non-numeric garbage so the manager's merge
+        // keeps the existing/default value instead of storing NaN
+        if (n !== undefined)
+            out[key] = n;
+    }
+    return out;
+}
 // ============ Job Management ============
 /** Handle Update command - update job data */
 export async function handleUpdate(cmd, ctx, reqId) {
@@ -122,8 +161,11 @@ export function handleCount(cmd, ctx, reqId) {
 // ============ Rate Limiting ============
 /** Handle RateLimit command */
 export function handleRateLimit(cmd, ctx, reqId) {
-    ctx.queueManager.setRateLimit(cmd.queue, cmd.limit);
-    ctx.queueManager.emitDashboardEvent('ratelimit:set', { queue: cmd.queue, max: cmd.limit });
+    const limit = toFiniteNumber(cmd.limit);
+    if (limit === undefined)
+        return resp.error('limit must be a finite number', reqId);
+    ctx.queueManager.setRateLimit(cmd.queue, limit);
+    ctx.queueManager.emitDashboardEvent('ratelimit:set', { queue: cmd.queue, max: limit });
     return resp.ok(undefined, reqId);
 }
 /** Handle RateLimitClear command */
@@ -134,10 +176,13 @@ export function handleRateLimitClear(cmd, ctx, reqId) {
 }
 /** Handle SetConcurrency command */
 export function handleSetConcurrency(cmd, ctx, reqId) {
-    ctx.queueManager.setConcurrency(cmd.queue, cmd.limit);
+    const limit = toFiniteNumber(cmd.limit);
+    if (limit === undefined)
+        return resp.error('limit must be a finite number', reqId);
+    ctx.queueManager.setConcurrency(cmd.queue, limit);
     ctx.queueManager.emitDashboardEvent('concurrency:set', {
         queue: cmd.queue,
-        concurrency: cmd.limit,
+        concurrency: limit,
     });
     return resp.ok(undefined, reqId);
 }
@@ -150,10 +195,11 @@ export function handleClearConcurrency(cmd, ctx, reqId) {
 // ============ Config Commands ============
 /** Handle SetStallConfig command */
 export function handleSetStallConfig(cmd, ctx, reqId) {
-    ctx.queueManager.setStallConfig(cmd.queue, cmd.config);
+    const config = sanitizeConfigNumbers(cmd.config, ['stallInterval', 'maxStalls', 'gracePeriod']);
+    ctx.queueManager.setStallConfig(cmd.queue, config);
     ctx.queueManager.emitDashboardEvent('config:stall-changed', {
         queue: cmd.queue,
-        config: cmd.config,
+        config,
     });
     return resp.ok(undefined, reqId);
 }
@@ -164,10 +210,16 @@ export function handleGetStallConfig(cmd, ctx, reqId) {
 }
 /** Handle SetDlqConfig command */
 export function handleSetDlqConfig(cmd, ctx, reqId) {
-    ctx.queueManager.setDlqConfig(cmd.queue, cmd.config);
+    const config = sanitizeConfigNumbers(cmd.config, [
+        'autoRetryInterval',
+        'maxAutoRetries',
+        'maxAge',
+        'maxEntries',
+    ]);
+    ctx.queueManager.setDlqConfig(cmd.queue, config);
     ctx.queueManager.emitDashboardEvent('config:dlq-changed', {
         queue: cmd.queue,
-        config: cmd.config,
+        config,
     });
     return resp.ok(undefined, reqId);
 }

package/dist/infrastructure/server/handlers/core.js

@@ -189,7 +189,7 @@ export async function handleAckBatch(cmd, ctx, reqId) {
 export async function handleFail(cmd, ctx, reqId) {
     try {
         const jid = jobId(cmd.id);
-        await ctx.queueManager.fail(jid, cmd.error, cmd.token);
+        await ctx.queueManager.fail(jid, cmd.error, cmd.token, cmd.unrecoverable);
         // Unregister job from client tracking
         ctx.queueManager.unregisterClientJob(ctx.clientId, jid);
         return resp.ok(undefined, reqId);

package/dist/infrastructure/server/handlers/cron.js

@@ -40,6 +40,7 @@ export function handleCron(cmd, ctx, reqId) {
                 repeatEvery: cron.repeatEvery,
                 nextRun: cron.nextRun,
                 timezone: cron.timezone,
+                priority: cron.priority,
             },
             reqId,
         };

package/dist/infrastructure/server/handlers/monitoring.js

@@ -18,8 +18,13 @@ export function handleAddLog(cmd, ctx, reqId) {
 }
 export function handleGetLogs(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
-    const logs = ctx.queueManager.getLogs(jid);
-    return resp.data({ logs }, reqId);
+    const all = ctx.queueManager.getLogs(jid);
+    // Honor optional pagination (start/end inclusive) the client already sends.
+    const total = all.length;
+    const logs = cmd.start === undefined && cmd.end === undefined
+        ? all
+        : all.slice(cmd.start ?? 0, (cmd.end ?? total - 1) + 1);
+    return resp.data({ logs, count: total }, reqId);
 }
 // ============ Worker Heartbeat ============
 export function handleHeartbeat(cmd, ctx, reqId) {

package/dist/infrastructure/server/http.js

@@ -59,6 +59,17 @@ export function createHttpServer(queueManager, config) {
     });
     // Helper to get CORS origin string
     const getCorsOrigin = () => (corsOrigins.has('*') ? '*' : Array.from(corsOrigins).join(', '));
+    // Attach CORS to responses built outside the routeRequest pipeline (health,
+    // ready, prometheus, debug) so browser dashboards can read them cross-origin
+    // (audit #16-20). Response headers are mutable for normally-constructed
+    // Responses; this never overwrites an existing value set by the endpoint.
+    const withCors = async (r) => {
+        const res = await r;
+        if (!res.headers.has('Access-Control-Allow-Origin')) {
+            res.headers.set('Access-Control-Allow-Origin', getCorsOrigin());
+        }
+        return res;
+    };
     // Fetch handler
     const fetch = async (req, server) => {
         const url = new URL(req.url);
@@ -69,26 +80,26 @@ export function createHttpServer(queueManager, config) {
         }
         // Health endpoints (no auth, no rate limit)
         if (path === '/health') {
-            return healthEndpoint(queueManager, wsHandler.size, sseHandler.size);
+            return withCors(healthEndpoint(queueManager, wsHandler.size, sseHandler.size));
         }
         if (path === '/healthz' || path === '/live') {
-            return new Response('OK', { status: 200 });
+            return withCors(new Response('OK', { status: 200 }));
         }
         if (path === '/ready') {
-            return jsonResponse({ ok: true, ready: true });
+            return jsonResponse({ ok: true, ready: true }, 200, corsOrigins);
         }
         // Debug endpoints (require auth)
         if (path === '/gc' && req.method === 'POST') {
             const denied = checkAuth(req, authTokens);
             if (denied)
                 return denied;
-            return gcEndpoint(queueManager);
+            return withCors(gcEndpoint(queueManager));
         }
         if (path === '/heapstats' && req.method === 'GET') {
             const denied = checkAuth(req, authTokens);
             if (denied)
                 return denied;
-            return heapStatsEndpoint(queueManager);
+            return withCors(heapStatsEndpoint(queueManager));
         }
         // Rate limiting
         const clientIp = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
@@ -131,7 +142,10 @@ export function createHttpServer(queueManager, config) {
                     return denied;
             }
             return new Response(queueManager.getPrometheusMetrics(), {
-                headers: { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' },
+                headers: {
+                    'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+                    'Access-Control-Allow-Origin': getCorsOrigin(),
+                },
             });
         }
         // Check authentication for other endpoints

package/dist/infrastructure/server/httpRouteJobs.js

@@ -79,6 +79,7 @@ async function routeJobManagement(req, path, method, ctx, cors) {
             cmd: 'ChangePriority',
             id: priorityMatch[1],
             priority: body['priority'],
+            lifo: body['lifo'],
         }, ctx);
         return jsonResponse(r, r.ok ? 200 : 400, cors);
     }
@@ -250,7 +251,12 @@ export async function routeJobRoutes(req, path, method, ctx, cors) {
         const body = await parseJsonBody(req, cors);
         if (body instanceof Response)
             return body;
-        const r = await handleCommand({ cmd: 'ACK', id: ackMatch[1], result: body['result'] }, ctx);
+        const r = await handleCommand({
+            cmd: 'ACK',
+            id: ackMatch[1],
+            result: body['result'],
+            token: body['token'],
+        }, ctx);
         return jsonResponse(r, r.ok ? 200 : 400, cors);
     }
     // POST /jobs/:id/fail
@@ -259,7 +265,13 @@ export async function routeJobRoutes(req, path, method, ctx, cors) {
         const body = await parseJsonBody(req, cors);
         if (body instanceof Response)
             return body;
-        const r = await handleCommand({ cmd: 'FAIL', id: failMatch[1], error: body['error'] }, ctx);
+        const r = await handleCommand({
+            cmd: 'FAIL',
+            id: failMatch[1],
+            error: body['error'],
+            token: body['token'],
+            unrecoverable: body['unrecoverable'],
+        }, ctx);
         return jsonResponse(r, r.ok ? 200 : 400, cors);
     }
     // Delegate to sub-routers

package/dist/infrastructure/server/httpRouteQueueConfig.js

@@ -26,8 +26,23 @@ export async function routeQueueConfigRoutes(req, path, method, ctx, cors) {
     const dlqMatch = path.match(RE_QUEUE_DLQ);
     if (dlqMatch && method === 'GET') {
         const queue = decodeURIComponent(dlqMatch[1]);
-        const entries = ctx.queueManager.getDlqEntries(queue);
-        return jsonResponse({ ok: true, entries }, 200, cors);
+        const all = ctx.queueManager.getDlqEntries(queue);
+        // Optional pagination so a dashboard can page large DLQs. Non-numeric params
+        // are ignored (treated as absent) rather than producing an empty/garbage slice.
+        const params = new URL(req.url).searchParams;
+        const toInt = (v) => {
+            if (v === null)
+                return undefined;
+            const n = Number(v);
+            return Number.isFinite(n) ? Math.trunc(n) : undefined;
+        };
+        const limit = toInt(params.get('limit'));
+        const offset = toInt(params.get('offset'));
+        const start = Math.max(0, offset ?? 0);
+        const entries = limit === undefined && offset === undefined
+            ? all
+            : all.slice(start, start + (limit !== undefined ? Math.max(0, limit) : all.length));
+        return jsonResponse({ ok: true, entries, total: all.length }, 200, cors);
     }
     // POST /queues/:queue/dlq/retry
     const dlqRetryMatch = path.match(RE_QUEUE_DLQ_RETRY);
@@ -79,7 +94,8 @@ export async function routeQueueConfigRoutes(req, path, method, ctx, cors) {
         const r = await handleCommand({
             cmd: 'SetConcurrency',
             queue,
-            limit: body['limit'],
+            // Accept the natural `concurrency` field for this endpoint as well as `limit`.
+            limit: (body['concurrency'] ?? body['limit']),
         }, ctx);
         return jsonResponse(r, 200, cors);
     }

package/dist/infrastructure/server/httpRouteQueues.js

@@ -105,7 +105,19 @@ async function routeJobOps(req, path, method, ctx, cors) {
     if (listMatch && method === 'GET') {
         const queue = decodeURIComponent(listMatch[1]);
         const url = new URL(req.url);
-        const stateValues = url.searchParams.getAll('state');
+        // Accept `state`, `status` (dashboard/REST convention), and `states` as
+        // aliases, each repeatable and comma-separated. Previously only `state` was
+        // read, so `?status=failed` silently fell through to an unfiltered list and
+        // returned the whole queue (#95). A state name never contains a comma, so
+        // splitting is safe.
+        const stateValues = [
+            ...url.searchParams.getAll('state'),
+            ...url.searchParams.getAll('status'),
+            ...url.searchParams.getAll('states'),
+        ]
+            .flatMap((v) => v.split(','))
+            .map((s) => s.trim())
+            .filter(Boolean);
         const state = stateValues.length === 0
             ? undefined
             : stateValues.length === 1

package/dist/infrastructure/server/httpRouteResources.js

@@ -40,6 +40,10 @@ export async function routeResourceRoutes(req, path, method, ctx, cors) {
             uniqueKey: body['uniqueKey'],
             dedup: body['dedup'],
             skipMissedOnRestart: body['skipMissedOnRestart'],
+            immediately: body['immediately'],
+            skipIfNoWorker: body['skipIfNoWorker'],
+            preventOverlap: body['preventOverlap'],
+            jobOptions: body['jobOptions'],
         }, ctx);
         return jsonResponse(r, r.ok ? 200 : 400, cors);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.5",
+  "version": "2.8.7",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
   "type": "module",
   "main": "dist/main.js",