single pub sub lock fix

[creomobile]

What does this PR do?

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / internal
• Other:

Checklist

• I have read the Contributing guide.
• Tests added or updated, and the full suite passes locally (npm test).
• Docs / doc-blocks updated where relevant.
• The PR is focused on a single logical change.

Contribution terms (required)

• I have read and agree to the @imqueue Contribution Terms.
  I grant the project owner the right to license my contribution
  commercially, royalty-free, my contribution stays available under
  GPL-3.0, I keep my copyright, and I understand I will receive no fee for
  it. If I did not agree, I would not be submitting this contribution.

[github-actions]

Thank you for your contribution to @imqueue. Before this pull request can be merged, please read the @imqueue Contribution Terms and sign them by posting the following comment exactly:

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[Copilot]

Pull request overview

This PR addresses a single-listener edge case where a PgIpLock can be acquired later by the retry timer after the original listen() call has already returned, leaving the lock held but the intended LISTEN never executed. It introduces a late-acquire callback to complete the “second half” of the work (subscribing) when takeover happens asynchronously.

Changes:

• Add onAcquire() to the AnyLock contract and implement it in PgIpLock and NoLock.
• Refactor PgPubSub.listen() to delegate the actual LISTEN+emit into a new subscribe() method, enabling late-takeover subscription without re-acquiring the lock.
• Add tests covering onAcquire() behavior in PgIpLock.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/PgIpLock.spec.ts	Adds tests for the new late-acquire callback behavior.
src/types/AnyLock.ts	Extends lock interface with a new onAcquire() hook and docs.
src/PgPubSub.ts	Uses subscribe() for LISTEN+emit, wires late-takeover handler to complete subscription.
src/PgIpLock.ts	Implements onAcquire() and adds timer-driven acquire path that invokes it on success.
src/NoLock.ts	Implements onAcquire() as a no-op for the no-lock strategy.

Comments suppressed due to low confidence (1)

src/PgIpLock.ts:281

• Timer-driven retries can overlap if acquire() takes longer than acquireInterval, which risks multiple handler calls and also racing this.acquired updates. Use a simple in-flight guard + finally to ensure the guard is always cleared even if the handler throws.

    private async retryAcquire(): Promise<void> {
        if (this.acquired) {
            return;
        }

        try {
            if (await this.acquire()) {
                this.acquireHandler?.(this.publicChannel);
            }
        } catch (err) {
            this.options.logger.error(err);
        }
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Mikhus]

I have read the CLA Document and I hereby sign the CLA