docs(run-engine): state what the lease signal actually guarantees

The in-flight member is keyed only by message and queue id, so once another
consumer re-claims a reclaimed item the member exists again and an extend from
the previous consumer succeeds. The signal therefore only catches the window
where the item is back on the queue and unclaimed, which is narrower than the
comment and the changeset claimed.

Author: matt-aitken

.changeset/fair-queue-concurrency-slot-leak.md

@@ -2,4 +2,6 @@
 "@trigger.dev/redis-worker": patch
 ---
 
-Fair queue consumers no longer leak concurrency slots. A slot is now always released when a message completes or is put back on the queue, even when its in-flight record has already gone. Leaked slots were never reclaimed, so enough of them would permanently stall every queue belonging to that tenant.
+Fair queue consumers no longer leak the concurrency slots that gate a tenant's throughput. Slots were held by messages that had already finished, were never reclaimed, and once enough of them accumulated every queue belonging to that tenant stopped being served. Slots are now freed on the paths that previously skipped them, freed before the record needed to recover them is discarded, and released before a reclaimed message goes back on the queue. A failed release is now surfaced instead of being silently treated as success.
+
+Concurrency groups keyed on queue metadata rather than the tenant can still resolve to the wrong group when a consumer completes a message it did not enqueue, so this does not yet cover that case.

internal-packages/run-engine/src/batch-queue/index.ts

@@ -761,11 +761,14 @@ export class BatchQueue {
   // ============================================================================
 
   /**
-   * Keep extending a message's visibility deadline while its callback runs, and return a
-   * function that stops doing so. Without this an item slower than the visibility timeout
-   * is redelivered while still being processed, and the original consumer's completion
-   * then destroys the redelivery's in-flight record, silently dropping the item and
-   * leaving the batch short of its expected count forever.
+   * Keep extending a message's visibility deadline while its callback runs, so an item
+   * slower than the visibility timeout is not redelivered and executed a second time.
+   *
+   * `lostLease` reports that an extend found no in-flight entry, which means the item was
+   * reclaimed and is now back on the queue. It is a best-effort signal, not a fence: the
+   * in-flight member is keyed only by message and queue id, so once another consumer
+   * re-claims the item the member exists again and an extend from this consumer succeeds.
+   * Distinguishing owners would need a per-claim token in the member.
    */
   #startHeartbeat(
     messageId: string,