tina4-nodejs 3.13.40 → 3.13.41

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.40)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.41)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -1209,7 +1209,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **off by default — opt-in via `TINA4_AUTO_CACHING=true`** (TTL `TINA4_AUTO_CACHING_TTL=5`s) which dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes (always in-process); default OFF because a request-scoped cache defaulting on is a read-after-write footgun (cached pre-write `SELECT MAX(id)` → duplicate PKs); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
 - **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. The KV API, the `responseCache` middleware, and the persistent DB query cache all route through this async backend set (native async clients, no child processes) — a network backend distributes them cross-instance, full parity with Python/PHP/Ruby; `memory` (default) keeps them in-process. `await` the async API (`cacheGet`/`cacheSet`/`clearCache`)
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
-- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
+- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars. **Reservation/visibility timeout** (file + MongoDB): a popped job is reserved for `TINA4_QUEUE_VISIBILITY_TIMEOUT` seconds (default 300; `visibilityTimeout` Queue option; `<= 0` disables) — if the consumer dies before `complete()`/`fail()`, the next `pop()` reclaims it (incrementing `attempts`, dead-lettering past `maxRetries`), so a crashed/evicted consumer never strands a job. RabbitMQ/Kafka delegate redelivery to the broker.
 - **Cache**: memory/Redis/file backends
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.40",
+  "version": "3.13.41",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/job.ts

@@ -40,6 +40,7 @@ export type QueueJob = JobData & JobLifecycle;
 export interface JobQueueBridge {
   _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
   _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
+  _completeJob(topic: string, job: QueueJob): void;
   getMaxRetries(): number;
 }
 
@@ -48,8 +49,11 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
   const job: QueueJob = {
     ...data,
     complete() {
-      // Terminal — the job was already removed from the queue on pop().
+      // Terminal — the pending file was claimed on pop and a reservation record
+      // written; complete() drops the reservation so a dead-consumer reclaim
+      // never re-delivers an already-acked job. The job is done.
       job.status = "completed";
+      queue._completeJob(job.topic, job);
     },
     fail(reason = "") {
       // Record a failed attempt. `attempts` is incremented exactly once, inside

package/packages/core/src/queue.ts

@@ -51,6 +51,29 @@ export interface QueueConfig {
    * straight away. Parity with Python's retry_backoff.
    */
   retryBackoff?: number;
+  /**
+   * Reservation/visibility timeout (seconds). A popped job is reserved for this
+   * long; if the consumer dies before complete()/fail() (crash, OOM, k8s
+   * eviction) the next pop() reclaims it — incrementing attempts and
+   * re-enqueuing, or dead-lettering past maxRetries (at-least-once delivery).
+   * Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0
+   * disables the reclaim (a reservation then lasts until the consumer acks —
+   * the old at-most-once behaviour). File + MongoDB backends only;
+   * RabbitMQ/Kafka delegate visibility to the broker. Parity with Python's
+   * visibility_timeout.
+   */
+  visibilityTimeout?: number;
+}
+
+/**
+ * Reservation/visibility timeout in seconds, from env (default 300 = 5 min).
+ * Mirrors Python's _default_visibility_timeout().
+ */
+function defaultVisibilityTimeout(): number {
+  const raw = process.env.TINA4_QUEUE_VISIBILITY_TIMEOUT;
+  if (raw === undefined || raw === "") return 300;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : 300;
 }
 
 export interface ProcessOptions {
@@ -82,6 +105,7 @@ export class Queue {
   private topic: string;
   private _maxRetries: number;
   private _retryBackoff: number;
+  private _visibilityTimeout: number;
   private externalBackend: QueueBackendInterface | null = null;
   private liteBackend!: LiteBackend;
 
@@ -112,15 +136,19 @@ export class Queue {
     this.topic = resolvedConfig.topic ?? "default";
     this._maxRetries = resolvedConfig.maxRetries ?? 3;
     this._retryBackoff = resolvedConfig.retryBackoff ?? 0;
-    this.liteBackend = new LiteBackend(this.basePath);
+    this._visibilityTimeout = resolvedConfig.visibilityTimeout ?? defaultVisibilityTimeout();
+    this.liteBackend = new LiteBackend(this.basePath, this._visibilityTimeout);
 
     // Initialize external backends
     if (this.backendName === "rabbitmq") {
-      this.externalBackend = new RabbitMQBackend();
+      // Broker manages visibility/redelivery (unacked messages requeue on
+      // channel close) — the framework timeout is accepted but not used.
+      this.externalBackend = new RabbitMQBackend({ visibilityTimeout: this._visibilityTimeout });
     } else if (this.backendName === "kafka") {
-      this.externalBackend = new KafkaBackend();
+      // Consumer-group offsets manage redelivery — framework timeout N/A.
+      this.externalBackend = new KafkaBackend({ visibilityTimeout: this._visibilityTimeout });
     } else if (this.backendName === "mongodb" || this.backendName === "mongo") {
-      this.externalBackend = new MongoBackend();
+      this.externalBackend = new MongoBackend({ visibilityTimeout: this._visibilityTimeout });
     }
   }
 
@@ -410,6 +438,15 @@ export class Queue {
     return this._retryBackoff;
   }
 
+  /**
+   * Resolved reservation/visibility timeout (seconds). <= 0 means the reclaim
+   * is disabled. File + MongoDB backends honour it; RabbitMQ/Kafka delegate to
+   * the broker.
+   */
+  getVisibilityTimeout(): number {
+    return this._visibilityTimeout;
+  }
+
   /**
    * Record a failed attempt for a job. The backend increments `attempts`
    * exactly once and decides whether to re-enqueue (attempts < maxRetries,
@@ -425,4 +462,13 @@ export class Queue {
   _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
     this.liteBackend.retryJob(queue, job, delaySeconds);
   }
+
+  /**
+   * Acknowledge a completed job — drop its reservation record so the visibility
+   * reclaim never re-delivers it. No-op for external backends (they ack their
+   * own way; lite-backend reservations are file records).
+   */
+  _completeJob(queue: string, job: QueueJob): void {
+    this.liteBackend.completeJob(queue, job);
+  }
 }

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -27,6 +27,12 @@ import type { QueueJob } from "../queue.js";
 export interface KafkaConfig {
   brokers?: string;
   groupId?: string;
+  /**
+   * Accepted for API parity with the file/MongoDB backends and IGNORED —
+   * consumer-group offsets own redelivery, so the framework-level visibility
+   * timeout does not apply here.
+   */
+  visibilityTimeout?: number;
 }
 
 /**
@@ -134,7 +140,7 @@ export class KafkaBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): Required<KafkaConfig> {
+  getConfig(): Required<Omit<KafkaConfig, "visibilityTimeout">> {
     return { brokers: this.brokers, groupId: this.groupId };
   }
 

package/packages/core/src/queueBackends/liteBackend.ts

@@ -24,9 +24,19 @@ import { createJob, type JobQueueBridge } from "../job.js";
 export class LiteBackend {
   private basePath: string;
   private seq: number = 0;
+  /**
+   * Reservation/visibility timeout (seconds). A popped job is held in reserved/
+   * with availableAt = now + visibilityTimeout. If the consumer dies before
+   * complete()/fail() (crash, OOM, k8s eviction) the next pop() reclaims it once
+   * the window expires — incrementing attempts and re-enqueuing, or
+   * dead-lettering past maxRetries. <= 0 disables the reclaim (a reservation
+   * then lasts until the consumer acks — the old at-most-once behaviour).
+   */
+  private visibilityTimeout: number;
 
-  constructor(basePath: string = "data/queue") {
+  constructor(basePath: string = "data/queue", visibilityTimeout: number = 300) {
     this.basePath = basePath;
+    this.visibilityTimeout = visibilityTimeout;
   }
 
   private ensureDir(queue: string): string {
@@ -41,6 +51,24 @@ export class LiteBackend {
     return dir;
   }
 
+  private ensureReservedDir(queue: string): string {
+    const dir = join(this.basePath, queue, "reserved");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  private reservedPath(queue: string, jobId: string): string {
+    return join(this.ensureReservedDir(queue), `${jobId}.queue-data`);
+  }
+
+  private nowIso(): string {
+    return new Date().toISOString();
+  }
+
+  private futureIso(seconds: number): string {
+    return new Date(Date.now() + seconds * 1000).toISOString();
+  }
+
   private nextPrefix(): string {
     this.seq++;
     return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
@@ -111,22 +139,112 @@ export class LiteBackend {
     return candidates;
   }
 
+  /**
+   * Persist a reservation record so a dead consumer's job is reclaimable.
+   *
+   * Stores reservedAt + availableAt = now + visibilityTimeout. The next pop()
+   * reclaims this job once availableAt has passed (see reclaimExpired).
+   * complete()/fail()/retry() delete the record.
+   */
+  private writeReserved(queue: string, job: any): void {
+    const now = this.nowIso();
+    const vt = this.visibilityTimeout || 0;
+    const record = {
+      id: job.id,
+      payload: job.payload,
+      status: "reserved" as const,
+      priority: job.priority ?? 0,
+      attempts: job.attempts ?? 0,
+      error: job.error,
+      reservedAt: now,
+      availableAt: vt > 0 ? this.futureIso(vt) : now,
+      createdAt: job.createdAt ?? now,
+      topic: job.topic ?? queue,
+    };
+    writeFileSync(this.reservedPath(queue, record.id), JSON.stringify(record, null, 2));
+  }
+
+  /**
+   * Return expired reservations to the queue (at-least-once delivery).
+   *
+   * A reserved job whose availableAt <= now means its consumer never
+   * acknowledged in time (crash / OOM / pod eviction). Atomically claim it
+   * (delete the reservation file), increment attempts, and either re-enqueue it
+   * (so the next pop picks it up) or dead-letter it once it has hit maxRetries.
+   * Disabled when visibilityTimeout <= 0.
+   */
+  private reclaimExpired(queue: string, maxRetries: number, now: string): void {
+    if (!this.visibilityTimeout || this.visibilityTimeout <= 0) return;
+    const reservedDir = this.ensureReservedDir(queue);
+
+    let filenames: string[];
+    try {
+      filenames = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return;
+    }
+
+    for (const filename of filenames) {
+      const filePath = join(reservedDir, filename);
+      let record: any;
+      try {
+        record = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+      if (record.availableAt && record.availableAt > now) continue; // still valid
+      // Atomically claim the expired reservation by deleting its file.
+      try {
+        unlinkSync(filePath);
+      } catch {
+        continue; // another worker reclaimed it first
+      }
+
+      const attempts = (record.attempts ?? 0) + 1;
+      const error = "reservation timed out — consumer did not acknowledge within the visibility timeout";
+      const job: QueueJob = {
+        id: record.id,
+        payload: record.payload,
+        status: "reserved",
+        createdAt: record.createdAt ?? now,
+        attempts,
+        delayUntil: null,
+        priority: record.priority ?? 0,
+        topic: record.topic ?? queue,
+        error,
+      } as QueueJob;
+
+      if (attempts >= maxRetries) {
+        this.deadLetter(queue, job, error);
+      } else {
+        this.requeue(queue, job, 0, error);
+      }
+    }
+  }
+
   pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    // First return any reservations whose consumer died mid-flight.
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       const filePath = join(dir, filename);
-      // Claim the job by deleting the file.
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      // Write the reservation BEFORE claiming the pending file, so a crash
+      // between claim and reserve can never strand the job. Only the worker
+      // that wins the unlink owns — and returns — it.
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
-        continue; // Already consumed by another worker
+        // Already consumed by another worker — drop the speculative reservation.
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+        continue;
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       return createJob(job as any, bridge);
     }
 
@@ -135,34 +253,61 @@ export class LiteBackend {
 
   popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
     const results: QueueJob[] = [];
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       if (results.length >= count) break;
       const filePath = join(dir, filename);
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
         continue; // Already consumed by another worker
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       results.push(createJob(job as any, bridge));
     }
 
     return results;
   }
 
+  /**
+   * Delete a job's reservation record (best-effort).
+   */
+  private clearReservation(queue: string, jobId: string): void {
+    try {
+      unlinkSync(this.reservedPath(queue, jobId));
+    } catch {
+      // no reservation record — nothing to clear
+    }
+  }
+
+  /**
+   * Acknowledge a completed job — drop its reservation record so the visibility
+   * reclaim never re-delivers an already-acked job.
+   */
+  completeJob(queue: string, job: QueueJob): void {
+    this.clearReservation(queue, job.id);
+  }
+
   // Status aliases that live in the failed/ directory (dead-lettered jobs)
   // rather than as pending files in the queue directory.
   private static readonly DEAD_STATES = ["failed", "dead", "dead_letter"];
 
   size(queue: string, status: string = "pending"): number {
     const isDead = LiteBackend.DEAD_STATES.includes(status);
-    const scanDir = isDead ? this.ensureFailedDir(queue) : this.ensureDir(queue);
+    const isReserved = status === "reserved";
+    const scanDir = isDead
+      ? this.ensureFailedDir(queue)
+      : isReserved
+        ? this.ensureReservedDir(queue)
+        : this.ensureDir(queue);
 
     let files: string[];
     try {
@@ -171,9 +316,9 @@ export class LiteBackend {
       return 0;
     }
 
-    if (isDead) {
-      // Every file in failed/ is a dead-letter; count them all regardless of
-      // the exact stored status string.
+    if (isDead || isReserved) {
+      // Every file in failed/ (or reserved/) matches the requested status;
+      // count them all regardless of the exact stored status string.
       return files.length;
     }
 
@@ -215,6 +360,20 @@ export class LiteBackend {
     } catch {
       // ignore
     }
+
+    // Also clear reservation records.
+    const reservedDir = join(dir, "reserved");
+    try {
+      if (existsSync(reservedDir)) {
+        const files = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          unlinkSync(join(reservedDir, file));
+          count++;
+        }
+      }
+    } catch {
+      // ignore
+    }
     return count;
   }
 
@@ -416,7 +575,18 @@ export class LiteBackend {
 
       if (job.status !== "pending") continue;
       if (job.id === id) {
-        try { unlinkSync(filePath); } catch { /* already consumed */ }
+        job.topic = queue;
+        job.priority = job.priority ?? 0;
+        // Reserve (so a dead consumer's job is reclaimable) then claim the
+        // pending file — mirrors pop().
+        this.writeReserved(queue, job);
+        try {
+          unlinkSync(filePath);
+        } catch {
+          try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+          continue; // already consumed
+        }
+        job.status = "reserved";
         return job;
       }
     }
@@ -479,6 +649,8 @@ export class LiteBackend {
    * (attempts >= maxRetries) it is moved to the dead-letter store.
    */
   failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff: number = 0): void {
+    // Clear the reservation — the consumer acknowledged (with a failure).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
     if (job.attempts < maxRetries) {
@@ -495,6 +667,8 @@ export class LiteBackend {
    * distinct from the automatic failJob() path.
    */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    // Clear the reservation — the consumer acknowledged (with an explicit retry).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
     this.requeue(queue, job, delaySeconds ?? 0, undefined);

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -32,6 +32,15 @@ export interface MongoConfig {
   password?: string;
   database?: string;
   collection?: string;
+  /**
+   * Reservation/visibility timeout (seconds). A dequeued message is held
+   * reserved with availableAt = now + timeout; reclaim returns it once that
+   * passes (consumer died mid-flight, before complete()/fail()). <= 0 disables
+   * the reclaim. Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300.
+   */
+  visibilityTimeout?: number;
+  /** Max attempts before the reclaim dead-letters a job instead of re-delivering. */
+  maxRetries?: number;
 }
 
 export interface QueueBackend {
@@ -58,6 +67,8 @@ export class MongoBackend implements QueueBackend {
   private password: string;
   private database: string;
   private collection: string;
+  private visibilityTimeout: number;
+  private maxRetries: number;
 
   constructor(config?: MongoConfig) {
     this.host = config?.host ?? process.env.TINA4_MONGO_HOST ?? "localhost";
@@ -68,6 +79,16 @@ export class MongoBackend implements QueueBackend {
     this.database = config?.database ?? process.env.TINA4_MONGO_DB ?? "tina4";
     this.collection = config?.collection ?? process.env.TINA4_MONGO_COLLECTION ?? "tina4_queue";
 
+    // Reservation/visibility timeout (seconds): config wins, else env, else 300.
+    if (config?.visibilityTimeout !== undefined) {
+      this.visibilityTimeout = config.visibilityTimeout;
+    } else {
+      const raw = process.env.TINA4_QUEUE_VISIBILITY_TIMEOUT;
+      const parsed = raw === undefined || raw === "" ? 300 : Number(raw);
+      this.visibilityTimeout = Number.isFinite(parsed) ? parsed : 300;
+    }
+    this.maxRetries = config?.maxRetries ?? 3;
+
     // Connection URI precedence: explicit config.uri > TINA4_MONGO_URI
     // > TINA4_QUEUE_URL > a URI built from the host/port/auth field vars.
     const explicitUri = config?.uri ?? process.env.TINA4_MONGO_URI ?? process.env.TINA4_QUEUE_URL;
@@ -84,15 +105,34 @@ export class MongoBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): { uri: string; database: string; collection: string } {
-    return { uri: this.uri, database: this.database, collection: this.collection };
+  getConfig(): { uri: string; database: string; collection: string; visibilityTimeout: number } {
+    return {
+      uri: this.uri,
+      database: this.database,
+      collection: this.collection,
+      visibilityTimeout: this.visibilityTimeout,
+    };
   }
 
   /**
-   * Execute a MongoDB operation synchronously via a child process.
+   * Resolved reservation/visibility timeout (seconds). <= 0 disables the
+   * reclaim. Exposed for testing/introspection.
    */
-  private execSync(operation: string, queue: string, data?: string): string {
-    const script = `
+  getVisibilityTimeout(): number {
+    return this.visibilityTimeout;
+  }
+
+  /**
+   * Build the Node script that performs one MongoDB queue operation in a child
+   * process. Exposed (not private) so tests can assert the visibility-timeout
+   * behaviour without a live MongoDB — the script's pop branch advances
+   * availableAt = now + visibilityTimeout and stamps reservedAt (the core fix),
+   * and the reclaim branch flips an expired { status: reserved } back to
+   * pending with attempts incremented (dead-lettering past maxRetries),
+   * disabled when visibilityTimeout <= 0.
+   */
+  buildScript(operation: string, queue: string, data?: string): string {
+    return `
       async function main() {
         let mongodb;
         try {
@@ -109,6 +149,8 @@ export class MongoBackend implements QueueBackend {
         const operation = ${JSON.stringify(operation)};
         const queueName = ${JSON.stringify(queue)};
         const data = ${JSON.stringify(data ?? "")};
+        const visibilityTimeout = ${JSON.stringify(this.visibilityTimeout)};
+        const maxRetries = ${JSON.stringify(this.maxRetries)};
 
         const client = new MongoClient(uri, {
           connectTimeoutMS: 5000,
@@ -121,7 +163,7 @@ export class MongoBackend implements QueueBackend {
           const col = db.collection(collName);
 
           // Ensure indexes on first use
-          await col.createIndex({ queue: 1, status: 1, delayUntil: 1 });
+          await col.createIndex({ queue: 1, status: 1, availableAt: 1 });
           await col.createIndex({ queue: 1, createdAt: 1 });
 
           if (operation === "push") {
@@ -129,19 +171,59 @@ export class MongoBackend implements QueueBackend {
             await col.insertOne({ ...job, queue: queueName });
             process.stdout.write("__PUSHED__");
           }
+          else if (operation === "reclaim") {
+            // Return reservations whose visibility window expired (at-least-once
+            // delivery). A doc left { status: reserved, availableAt <= now } had
+            // its consumer die before acknowledging — flip it back to pending
+            // with attempts incremented, or dead-letter once attempts hit the
+            // limit. Disabled when visibilityTimeout <= 0.
+            let reclaimed = 0;
+            if (visibilityTimeout > 0) {
+              while (true) {
+                const now = new Date().toISOString();
+                const doc = await col.findOneAndUpdate(
+                  { queue: queueName, status: "reserved", availableAt: { $lte: now } },
+                  { $set: { status: "pending", availableAt: now, reservedAt: null }, $inc: { attempts: 1 } },
+                  { sort: { availableAt: 1 }, returnDocument: "after" },
+                );
+                const updated = doc && doc.value ? doc.value : (doc && doc._id ? doc : null);
+                if (!updated) break;
+                reclaimed++;
+                if ((updated.attempts || 0) >= maxRetries) {
+                  await col.insertOne({
+                    ...updated,
+                    _id: undefined,
+                    status: "dead",
+                    queue: queueName + ".dead_letter",
+                    error: "reservation timed out — consumer did not acknowledge within the visibility timeout",
+                  });
+                  await col.deleteOne({ _id: updated._id, queue: queueName });
+                }
+              }
+            }
+            process.stdout.write(String(reclaimed));
+          }
           else if (operation === "pop") {
             const now = new Date().toISOString();
+            // The claim advances availableAt = now + visibilityTimeout and
+            // stamps reservedAt so reclaim can return the job if the consumer
+            // dies before complete()/fail() — this is the fix for the "reserved
+            // forever" bug (previously availableAt was left unchanged).
+            const future = new Date(Date.now() + visibilityTimeout * 1000).toISOString();
             const result = await col.findOneAndUpdate(
               {
                 queue: queueName,
                 status: "pending",
                 $or: [
+                  { availableAt: null },
+                  { availableAt: { $exists: false } },
+                  { availableAt: { $lte: now } },
                   { delayUntil: null },
                   { delayUntil: { $lte: now } },
                 ],
               },
-              { $set: { status: "reserved" } },
-              { sort: { createdAt: 1 }, returnDocument: "before" },
+              { $set: { status: "reserved", reservedAt: now, availableAt: future } },
+              { sort: { priority: -1, createdAt: 1 }, returnDocument: "before" },
             );
 
             if (result && result.value) {
@@ -181,6 +263,13 @@ export class MongoBackend implements QueueBackend {
 
       main();
     `;
+  }
+
+  /**
+   * Execute a MongoDB operation synchronously via a child process.
+   */
+  private execSync(operation: string, queue: string, data?: string): string {
+    const script = this.buildScript(operation, queue, data);
 
     try {
       const result = execFileSync(process.execPath, ["-e", script], {
@@ -215,6 +304,11 @@ export class MongoBackend implements QueueBackend {
   }
 
   pop(queue: string): QueueJob | null {
+    // Reclaim any reservations whose consumer died before acking, then take the
+    // next available message (at-least-once delivery). Disabled at timeout <= 0.
+    if (this.visibilityTimeout > 0) {
+      this.execSync("reclaim", queue);
+    }
     const result = this.execSync("pop", queue);
     if (!result || result === "__EMPTY__") return null;
 

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -28,6 +28,12 @@ export interface RabbitMQConfig {
   username?: string;
   password?: string;
   vhost?: string;
+  /**
+   * Accepted for API parity with the file/MongoDB backends and IGNORED — the
+   * broker owns redelivery (unacked messages requeue on channel close), so the
+   * framework-level visibility timeout does not apply here.
+   */
+  visibilityTimeout?: number;
 }
 
 /**
@@ -200,7 +206,7 @@ export class RabbitMQBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): Required<RabbitMQConfig> {
+  getConfig(): Required<Omit<RabbitMQConfig, "visibilityTimeout">> {
     return {
       host: this.host,
       port: this.port,