feat: payout ledger with bounded retry

Closes the gap the scheduler commit left open: a failed payday was retried
indefinitely with nothing but a log line to show for it.

Every attempt — paid, skipped and failed — is now written to
payroll.payouts and exposed at GET /api/v1/payouts. Failures are in the
ledger, not only in the log, because "why did nobody get paid on the 1st"
is the question the ledger exists to answer.

Ledger rows are self-describing: each copies the terms in force at the time
(amount, currency, both wallets) instead of pointing at the contract, and
there is no foreign key to contracts. A payout has to still read correctly
after its contract is edited, and deleting a contract must not take its
history with it. This is the one place duplicating a contract field is
right — the contract holds what is true now, a payout holds what was true
then.

Retries are bounded at 5 attempts per period, after which the contract is
paused rather than the period abandoned. A payday that cannot be funded is
a fact somebody has to act on; dropping it silently is the one outcome
payroll must never produce. Pausing does not advance the position, so
resuming after topping up retries the same payday. The attempt count is
derived from the ledger rather than a column on the contract, so it
survives a restart and stays auditable.

Also restores the explanatory comments on the broad `except Exception`
handlers, which ruff's RUF100 stripped along with their now-unused noqa
directives.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018jy52j9GRZ6XKa1Zt21LLj

views_api.py

@@ -21,7 +21,14 @@ from lnbits.utils.exchange_rates import allowed_currencies
 
 from . import crud, services
 from .accounts import list_directory_users, owns_wallet
-from .models import Contract, CreateContract, DirectoryUser, UpdateContract
+from .models import (
+    Contract,
+    CreateContract,
+    DirectoryUser,
+    Payout,
+    PayoutStatus,
+    UpdateContract,
+)
 
 payroll_api_router = APIRouter(dependencies=[Depends(check_super_user)])
 
@@ -215,3 +222,24 @@ async def api_cancel_contract(contract_id: str) -> Contract:
     mistake" escape hatch and discards the record entirely.
     """
     return await _transition(contract_id, services.cancel)
+
+
+# ---------------------------------------------------------------------------
+# Payout ledger
+# ---------------------------------------------------------------------------
+
+
+@payroll_api_router.get("/api/v1/payouts")
+async def api_list_payouts(
+    contract_id: str | None = None,
+    status: PayoutStatus | None = None,
+    limit: int = 200,
+) -> list[Payout]:
+    """Every payout attempt, newest first.
+
+    Includes failures and skips, not just successes — "why did nobody get
+    paid on the 1st" is the question this endpoint exists to answer.
+    """
+    return await crud.get_payouts(
+        contract_id=contract_id, status=status, limit=min(limit, 1000)
+    )