merge: combine PR #632 with broader pool-exhaustion fixes

.env.example

@@ -22,13 +22,19 @@ ROUTSTR_SECRET_KEY=
 
 # Database
 # DATABASE_URL=sqlite+aiosqlite:///keys.db
-# Keep total pool capacity across all workers below the database connection limit.
+# Pool controls are validated at boot, sourced only from the environment, and
+# logged at startup. Defaults intentionally bound capacity and fail quickly so
+# leaked connections are visible instead of hidden by overflow connections.
+# Keep total capacity across all workers below the database connection limit.
 # DATABASE_POOL_SIZE=5
 # DATABASE_MAX_OVERFLOW=0
 # DATABASE_POOL_TIMEOUT=5
 # DATABASE_POOL_RECYCLE=1800
 # DATABASE_POOL_PRE_PING=true
+# Warn when a checkout is held this many seconds.
 # DATABASE_POOL_HOLD_WARN_SECONDS=10
+# SQLite serialises writes; increasing its pool can trade pool timeouts for
+# "database is locked" errors rather than increasing write throughput.
 
 # Node Information
 # NAME=My Routstr Node
@@ -40,6 +46,7 @@ ROUTSTR_SECRET_KEY=
 # CASHU_MINTS="https://mint.minibits.cash/Bitcoin,https://mint.cubabitcoin.org,https://ecashmint.otrta.me"
 # MINT_OPERATION_CONCURRENCY=4
 # RECEIVE_LN_ADDRESS=
+# REFUND_SWEEP_CLAIM_TIMEOUT_SECONDS=900
 
 # Custom Pricing Configuration
 # MODEL_BASED_PRICING=true