Add server-side background polling to recover stuck Lightning checkouts

[Copilot]

Lightning checkouts can get permanently stuck when the client fails to call POST /ln-checkout/:id/check-invoice after paying (browser crash, app switch, network failure). Recovery currently requires the user to manually navigate back to the checkout page.

Changes

• Background polling (poll_unpaid_invoices()): PurpleInvoiceManager now periodically iterates all incomplete checkout sessions with pending invoices and calls check_checkout_object_invoice() on each concurrently. Interval defaults to 60s, configurable via LN_INVOICE_POLLING_INTERVAL_MS.

• Idempotency guard in check_checkout_object_invoice: Early-returns for already-completed checkouts, preventing redundant LN node queries and double-processing under concurrent client + background poll scenarios.

• Fix silent payment processing failure: handle_successful_payment() was not awaited — if it threw, the checkout was marked completed = true while the account was never updated. Now the error propagates and the next poll will retry.

• Proper cleanup: disconnect() now clears the polling interval; test controller teardown calls disconnect() to prevent timer leaks.

// Server now recovers paid-but-unprocessed checkouts automatically:
this.polling_interval_timer = setInterval(
  () => this.poll_unpaid_invoices(),
  parseInt(process.env.LN_INVOICE_POLLING_INTERVAL_MS) || 60 * 1000
)

Tests

Added LN Flow — Background polling processes paid invoices without client check: pays an invoice, skips check-invoice, calls poll_unpaid_invoices() directly, and asserts the account is activated.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Lightning checkouts occasionally need a "nudge" to go through</issue_title>
<issue_description>In some rare occasions we receive reports of the checkout process not completely going through.

Usually going to the checkout session page gives the checkout a nudge it needs to complete itself.

We should determine the root cause and create mechanisms to prevent checkouts from being completely stuck.

</issue_description>

<agent_instructions>For more context, you can also locally clone a copy of https://github.com/damus-io/website locally to see the website code that interacts with this server functionality.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Lightning checkouts occasionally need a "nudge" to go through #26

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.