lint

Fix provider forwarding upstream

Dockerfile.full

@@ -4,7 +4,7 @@ FROM node:23-alpine AS ui-builder
 WORKDIR /app/ui
 
 # Install pnpm
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
 # Copy UI source
 COPY ui/package.json ui/pnpm-lock.yaml* ./

docs/provider/configuration.md

@@ -78,9 +78,15 @@ Which mints to accept payments from:
 
 Automatic profit withdrawal:
 
-| Setting               | Description                     |
-| --------------------- | ------------------------------- |
-| **Lightning Address** | Your LN address for withdrawals |
+| Setting                              | Description                                                                                                | Default |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------- |
+| **Lightning Address**                | Your LN address for withdrawals                                                                            | —       |
+| **Minimum Payout (sat)**             | Min available balance (in sats) before profit is paid out. Applies to both `sat` and `msat` mints (auto-converted). | `210`   |
+| **Payout Interval (seconds)**        | How often the payout loop wakes up and checks balances                                                     | `900`   |
+
+All payout amounts must be positive. Set the minimums above your wallet's
+minimum-invoice constraint (typically 1 sat) and high enough to amortise
+routing fees.
 
 ### Security
 
@@ -126,6 +132,8 @@ Use environment variables for:
 | `ENABLE_ANALYTICS_SHARING` | Enable usage analytics sharing to Nostr | `true`                         |
 | `CASHU_MINTS`        | Comma-separated mint URLs         | `https://mint.minibits.cash/Bitcoin` |
 | `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | —                                    |
+| `MIN_PAYOUT_SAT`     | Min payout balance in sats (applies to all mints) | `210`                |
+| `PAYOUT_INTERVAL_SECONDS` | Payout loop interval (seconds) | `900`                            |
 | `TOR_PROXY_URL`      | SOCKS5 proxy for Tor              | `socks5://127.0.0.1:9050`            |
 | `CORS_ORIGINS`       | Allowed CORS origins              | `*`                                  |
 | `RELAYS`             | Nostr relays (comma-separated)    | (default set)                        |

routstr/balance.py

@@ -211,8 +211,20 @@ async def _refund_cache_set(authorization: str, value: dict[str, str]) -> None:
         _refund_cache[key] = (expiry, value)
 
 
+async def _lookup_key_no_create(
+    bearer_value: str, session: AsyncSession
+) -> ApiKey | None:
+    """Look up an existing API key without creating one Used by the refund endpoint"""
+    if bearer_value.startswith("sk-"):
+        return await session.get(ApiKey, bearer_value[3:])
+    if bearer_value.startswith("cashu"):
+        hashed = hashlib.sha256(bearer_value.encode()).hexdigest()
+        return await session.get(ApiKey, hashed)
+    return None
+
+
 async def _restore_balance(
-    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int
+    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int, mint_url: str
 ) -> None:
     """Restore balance after a failed refund mint attempt."""
     restore_stmt = (
@@ -227,7 +239,7 @@ async def _restore_balance(
     await session.commit()
     logger.info(
         "refund_wallet_endpoint: balance restored after mint failure",
-        extra={"hashed_key": hashed_key, "restored_balance": balance},
+        extra={"hashed_key": hashed_key, "restored_balance": balance, "mint_url": mint_url},
     )
 
 
@@ -282,7 +294,12 @@ async def refund_wallet_endpoint(
         )
 
     bearer_value: str = authorization[7:]
-    key: ApiKey = await validate_bearer_key(bearer_value, session)
+    key: ApiKey | None = await _lookup_key_no_create(bearer_value, session)
+    if key is None:
+        raise HTTPException(
+            status_code=401,
+            detail="Key not found. Deposit first via /v1/wallet/create before requesting a refund.",
+        )
 
     if key.total_balance <= 0:
         if cached := await _refund_cache_get(bearer_value):
@@ -337,21 +354,26 @@ async def refund_wallet_endpoint(
         )
 
     # --- MINT: balance is locked at zero, safe to create the refund token ---
+    # Proofs from untrusted mints are swapped to primary_mint on receive.
+    # Use primary_mint unless key.refund_mint_url is an explicitly trusted mint.
+    effective_refund_mint = (
+        key.refund_mint_url
+        if key.refund_mint_url and key.refund_mint_url in settings.cashu_mints
+        else settings.primary_mint
+    )
     try:
         if key.refund_address:
-            from .core.settings import settings as global_settings
-
             await send_to_lnurl(
                 remaining_balance,
                 key.refund_currency or "sat",
-                key.refund_mint_url or global_settings.primary_mint,
+                effective_refund_mint,
                 key.refund_address,
             )
             result = {"recipient": key.refund_address}
         else:
             refund_currency = key.refund_currency or "sat"
             token = await send_token(
-                remaining_balance, refund_currency, key.refund_mint_url
+                remaining_balance, refund_currency, effective_refund_mint
             )
             result = {"token": token}
 
@@ -373,21 +395,32 @@ async def refund_wallet_endpoint(
 
     except HTTPException:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved, key.refund_mint_url or "")
         raise
     except Exception as e:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved, key.refund_mint_url or "")
         error_msg = str(e)
+        logger.error(
+            "refund_wallet_endpoint: mint/send failed",
+            extra={
+                "error": error_msg,
+                "error_type": type(e).__name__,
+                "hashed_key": key.hashed_key,
+                "remaining_balance": remaining_balance,
+                "refund_currency": key.refund_currency,
+                "refund_mint_url": key.refund_mint_url,
+                "has_refund_address": bool(key.refund_address),
+            },
+        )
         if (
             "mint" in error_msg.lower()
             or "connection" in error_msg.lower()
-            or isinstance(e, Exception)
-            and "ConnectError" in str(type(e))
+            or "ConnectError" in str(type(e))
         ):
-            raise HTTPException(status_code=503, detail="Mint service unavailable")
+            raise HTTPException(status_code=503, detail=f"Mint service unavailable: {error_msg}")
         else:
-            raise HTTPException(status_code=500, detail="Refund failed")
+            raise HTTPException(status_code=500, detail=f"Refund failed: {error_msg}")
 
     await _refund_cache_set(bearer_value, result)
 

routstr/core/admin.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, RootModel
+from pydantic.v1 import ValidationError as PydanticValidationError
 from sqlmodel import select
 
 from ..payment.models import _row_to_model, list_models
@@ -160,8 +161,13 @@ async def update_settings(request: Request, update: SettingsUpdate) -> dict:
         if field in settings_data:
             del settings_data[field]
 
-    async with create_session() as session:
-        new_settings = await SettingsService.update(settings_data, session)
+    try:
+        async with create_session() as session:
+            new_settings = await SettingsService.update(settings_data, session)
+    except PydanticValidationError as e:
+        # Surface validation issues (e.g. non-positive payout amounts)
+        # as a clean 400 instead of a 500.
+        raise HTTPException(status_code=400, detail=e.errors()) from e
     data = new_settings.dict()
     if "upstream_api_key" in data:
         data["upstream_api_key"] = "[REDACTED]" if data["upstream_api_key"] else ""

routstr/core/main.py

@@ -30,6 +30,7 @@ from .db import create_session, init_db, run_migrations
 from .exceptions import general_exception_handler, http_exception_handler
 from .logging import get_logger, setup_logging
 from .middleware import LoggingMiddleware
+from .not_found import _NOT_FOUND_HTML, not_found_catch_all  # noqa: F401
 from .settings import SettingsService
 from .settings import settings as global_settings
 from .version import __version__

routstr/core/not_found.py

@@ -0,0 +1,55 @@
+"""Shared 404 handler used by the proxy catch-all and tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse, JSONResponse, Response
+
+_NOT_FOUND_HTML_FILE = Path(__file__).parent.parent.parent / "ui_out" / "404.html"
+
+
+def _read_not_found_html() -> str | None:
+    try:
+        return _NOT_FOUND_HTML_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+_NOT_FOUND_HTML: str | None = _read_not_found_html()
+
+
+def build_not_found_response(request: Request, path: str) -> Response:
+    """Return a 404 response.
+
+    HTML 404 page only for GET requests from browsers (Accept: text/html).
+    All POST requests and API clients receive a JSON 404.
+    """
+    accept = request.headers.get("accept", "").lower()
+    prefers_html = (
+        request.method == "GET"
+        and "text/html" in accept
+        and "application/json" not in accept
+    )
+    request_id = getattr(request.state, "request_id", "unknown")
+
+    if prefers_html and _NOT_FOUND_HTML is not None:
+        return HTMLResponse(content=_NOT_FOUND_HTML, status_code=404)
+
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": {
+                "message": f"Path '/{path}' not found",
+                "type": "not_found",
+                "code": 404,
+            },
+            "request_id": request_id,
+        },
+    )
+
+
+async def not_found_catch_all(request: Request, path: str) -> Response:
+    """ASGI handler form of :func:`build_not_found_response`."""
+    return build_not_found_response(request, path)

routstr/core/settings.py

@@ -41,6 +41,15 @@ class Settings(BaseSettings):
     primary_mint: str = Field(default="", env="PRIMARY_MINT_URL")
     primary_mint_unit: str = Field(default="sat", env="PRIMARY_MINT_UNIT")
 
+    # Lightning payout configuration
+    # Minimum available balance (in satoshis) before profit is paid out over
+    # Lightning
+    min_payout_sat: int = Field(default=210, gt=0, env="MIN_PAYOUT_SAT")
+    # Interval (seconds) between periodic payout attempts. Must be positive.
+    payout_interval_seconds: int = Field(
+        default=900, gt=0, env="PAYOUT_INTERVAL_SECONDS"
+    )
+
     # Pricing
     # Default behavior: derive pricing from MODELS
     # If fixed_pricing is True -> use fixed_cost_per_request and ignore tokens

routstr/proxy.py

@@ -17,6 +17,7 @@ from .core.db import (
     get_session,
 )
 from .core.exceptions import UpstreamError
+from .core.not_found import build_not_found_response
 from .core.settings import settings
 from .payment.helpers import (
     calculate_discounted_max_cost,
@@ -150,10 +151,31 @@ async def refresh_model_maps_periodically() -> None:
             )
 
 
+_API_PATH_PREFIXES = (
+    "v1/",
+    "responses",
+    "chat/",
+    "completions",
+    "models",
+    "embeddings",
+    "audio/",
+    "images/",
+    "moderations",
+    "providers",
+)
+
+
 @proxy_router.api_route("/{path:path}", methods=["GET", "POST"], response_model=None)
 async def proxy(
     request: Request, path: str, session: AsyncSession = Depends(get_session)
 ) -> Response | StreamingResponse:
+    # GET requests must hit a known API prefix; otherwise return a 404 (HTML
+    # for browsers, JSON for API clients). POST requests are always forwarded
+    # so that OpenAI-style endpoints work with or without the `v1/` prefix
+    # (e.g. `/chat/completions` as well as `/v1/chat/completions`).
+    if request.method == "GET" and not path.startswith(_API_PATH_PREFIXES):
+        return build_not_found_response(request, path)
+
     headers = dict(request.headers)
 
     is_responses_api = path.startswith("v1/responses") or path.startswith("responses")

routstr/upstream/base.py

@@ -42,11 +42,23 @@ from ..payment.models import (
 from ..payment.price import sats_usd_price
 from ..wallet import recieve_token, send_token
 from . import messages_dispatch
+from .count_tokens import count_tokens_locally
 from .litellm_routing import detect_litellm_prefix
 
 logger = get_logger(__name__)
 
 
+def _is_json_content_type(content_type: str | None) -> bool:
+    """Return True when the upstream response should be parsed as JSON.
+    """
+    if not content_type:
+        return False
+    main = content_type.split(";", 1)[0].strip().lower()
+    if main in ("application/json", "text/json"):
+        return True
+    return main.startswith("application/") and main.endswith("+json")
+
+
 class TopupData(BaseModel):
     """Universal top-up data schema for Lightning Network invoices."""
 
@@ -523,7 +535,8 @@ class BaseUpstreamProvider:
     async def forward_upstream_error_response(
         self, request: Request, path: str, upstream_response: httpx.Response
     ) -> Response:
-        """Log upstream errors and forward the upstream response unchanged."""
+        """Log upstream errors and forward the response in a JSON envelope.
+        """
         status_code = upstream_response.status_code
         headers = dict(upstream_response.headers)
         content_type = headers.get("content-type") or headers.get("Content-Type", "")
@@ -545,9 +558,10 @@ class BaseUpstreamProvider:
 
         message, upstream_code = self._extract_upstream_error_message(body_bytes)
         body_preview = body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        is_json_body = _is_json_content_type(content_type)
 
         logger.warning(
-            "Forwarding upstream error response as-is",
+            "Forwarding upstream error response",
             extra={
                 "path": path,
                 "provider": self.provider_type,
@@ -559,6 +573,7 @@ class BaseUpstreamProvider:
                 "body_preview": body_preview,
                 "body_read_error": body_read_error,
                 "method": request.method,
+                "json_normalized": not is_json_body,
             },
         )
 
@@ -586,17 +601,40 @@ class BaseUpstreamProvider:
         ):
             headers.pop(header_name, None)
 
-        if not content_type:
-            headers.pop("content-type", None)
-            headers.pop("Content-Type", None)
+        if is_json_body:
+            if not content_type:
+                headers.pop("content-type", None)
+                headers.pop("Content-Type", None)
+            media_type = content_type or None
+            return Response(
+                content=body_bytes,
+                status_code=status_code,
+                headers=headers,
+                media_type=media_type,
+            )
 
-        media_type = content_type or None
+        # Non-JSON upstream error (HTML, plain text, empty, ...). Wrap it in
+        # the standard JSON envelope so callers don't need a second parser.
+        for header_name in ("content-type", "Content-Type"):
+            headers.pop(header_name, None)
+
+        envelope = {
+            "error": {
+                "message": message or "Upstream returned a non-JSON error response",
+                "type": "upstream_error",
+                "code": upstream_code or status_code,
+                "upstream_status": status_code,
+                "upstream_content_type": content_type or None,
+                "upstream_body_preview": body_preview or None,
+            },
+            "request_id": getattr(request.state, "request_id", None),
+        }
 
         return Response(
-            content=body_bytes,
+            content=json.dumps(envelope).encode(),
             status_code=status_code,
             headers=headers,
-            media_type=media_type,
+            media_type="application/json",
         )
 
     async def handle_streaming_chat_completion(
@@ -2159,6 +2197,12 @@ class BaseUpstreamProvider:
         """
         path = self.normalize_request_path(path, model_obj)
 
+        if (
+            path.endswith("messages/count_tokens")
+            and not self.supports_anthropic_messages
+        ):
+            return count_tokens_locally(request_body, model_obj)
+
         if (
             path.endswith("messages")
             and not path.endswith("count_tokens")
@@ -3357,6 +3401,12 @@ class BaseUpstreamProvider:
 
         request_body = await request.body()
 
+        if (
+            path.endswith("messages/count_tokens")
+            and not self.supports_anthropic_messages
+        ):
+            return count_tokens_locally(request_body, model_obj)
+
         if (
             path.endswith("messages")
             and not path.endswith("count_tokens")

routstr/upstream/count_tokens.py

@@ -0,0 +1,108 @@
+"""Local handling of Anthropic ``/v1/messages/count_tokens`` for upstreams
+that do not natively expose the endpoint.
+
+Most non-Anthropic upstreams (OpenAI-compat, Gemini OpenAI-compat,
+OpenRouter chat-completions, generic providers) return 400/404 when asked
+to ``POST /messages/count_tokens``. Claude Code and other Anthropic SDK
+clients call this endpoint before each turn to size context windows and
+trigger compaction, so a failure breaks the whole chat.
+
+We answer locally. ``litellm.token_counter`` understands the Anthropic
+message shape and the per-model tokenizers, so we prefer it. If it raises
+(unknown model, encoding lookup failure, ...), we fall back to the
+project's own ``estimate_tokens`` heuristic, which is always defined and
+never raises.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import litellm
+from fastapi.responses import Response
+
+from ..core import get_logger
+from ..payment.helpers import estimate_tokens
+from ..payment.models import Model
+
+logger = get_logger(__name__)
+
+
+def _parse_request_body(request_body: bytes | None) -> dict[str, Any]:
+    if not request_body:
+        return {}
+    try:
+        parsed = json.loads(request_body)
+    except (ValueError, TypeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _count_with_litellm(model: str, body: dict[str, Any]) -> int:
+    messages = body.get("messages")
+    if not isinstance(messages, list):
+        messages = []
+
+    system = body.get("system")
+    if isinstance(system, str) and system:
+        messages = [{"role": "system", "content": system}, *messages]
+    elif isinstance(system, list):
+        text = "".join(
+            block.get("text", "")
+            for block in system
+            if isinstance(block, dict) and block.get("type") == "text"
+        )
+        if text:
+            messages = [{"role": "system", "content": text}, *messages]
+
+    tools = body.get("tools") if isinstance(body.get("tools"), list) else None
+
+    return int(
+        litellm.token_counter(
+            model=model,
+            messages=messages,
+            tools=tools,
+        )
+    )
+
+
+def count_tokens_locally(
+    request_body: bytes | None,
+    model_obj: Model | None,
+) -> Response:
+    """Return an Anthropic-compatible count_tokens response without
+    touching the upstream. Always returns 200; never raises."""
+    body = _parse_request_body(request_body)
+
+    model_name = ""
+    if model_obj is not None:
+        model_name = model_obj.forwarded_model_id or model_obj.id or ""
+    if not model_name:
+        body_model = body.get("model")
+        if isinstance(body_model, str):
+            model_name = body_model
+
+    input_tokens: int
+    try:
+        input_tokens = _count_with_litellm(model_name, body)
+    except Exception as exc:
+        messages = body.get("messages")
+        fallback_messages = messages if isinstance(messages, list) else []
+        input_tokens = estimate_tokens(fallback_messages)
+        logger.debug(
+            "litellm token_counter failed; using local estimator",
+            extra={
+                "model": model_name,
+                "error": str(exc),
+                "error_type": type(exc).__name__,
+                "estimated_tokens": input_tokens,
+            },
+        )
+
+    payload = {"input_tokens": max(0, int(input_tokens))}
+    return Response(
+        content=json.dumps(payload).encode(),
+        status_code=200,
+        media_type="application/json",
+    )

routstr/upstream/routstr.py

@@ -18,6 +18,10 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
     provider_type = "routstr"
     default_base_url = None
     platform_url = None
+    # Upstream Routstr nodes serve `/v1/messages` natively, so forward the
+    # request as-is instead of round-tripping through litellm's
+    # Anthropic→OpenAI translator.
+    supports_anthropic_messages = True
 
     def __init__(
         self,
@@ -43,6 +47,13 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
         )
         self.settings = provider_settings or {}
 
+    def normalize_request_path(
+        self, path: str, model_obj: "Model | None" = None
+    ) -> str:
+        """Preserve the ``v1/`` prefix when forwarding to an upstream Routstr.
+        """
+        return path.lstrip("/")
+
     @classmethod
     def from_db_row(
         cls, provider_row: "UpstreamProviderRow"

routstr/wallet.py

@@ -48,6 +48,8 @@ async def recieve_token(
     if token_obj.mint not in settings.cashu_mints:
         return await swap_to_primary_mint(token_obj, wallet)
 
+    await wallet.load_mint(keyset_id=token_obj.keysets[0])
+
     wallet.verify_proofs_dleq(token_obj.proofs)
     await wallet.split(proofs=token_obj.proofs, amount=0, include_fees=True)
 
@@ -56,17 +58,56 @@ async def recieve_token(
 
 async def send(amount: int, unit: str, mint_url: str | None = None) -> tuple[int, str]:
     """Internal send function - returns amount and serialized token"""
-    wallet: Wallet = await get_wallet(mint_url or settings.primary_mint, unit)
-    proofs = get_proofs_per_mint_and_unit(
-        wallet, mint_url or settings.primary_mint, unit
+    effective_mint_url = mint_url or settings.primary_mint
+    wallet: Wallet = await get_wallet(effective_mint_url, unit)
+    proofs = get_proofs_per_mint_and_unit(wallet, effective_mint_url, unit)
+    proofs_for_mint = sum(p.amount for p in proofs)
+
+    # Fallback: proofs from untrusted source mints are swapped to primary_mint
+    # during receive, so the user's preferred refund_mint_url may have no proofs
+    # even though the global wallet has the balance.
+    if proofs_for_mint < amount and effective_mint_url != settings.primary_mint:
+        logger.info(
+            f"send: insufficient proofs at {effective_mint_url} "
+            f"(have {proofs_for_mint}, need {amount}), falling back to primary_mint={settings.primary_mint}"
+        )
+        effective_mint_url = settings.primary_mint
+        wallet = await get_wallet(effective_mint_url, unit)
+        proofs = get_proofs_per_mint_and_unit(wallet, effective_mint_url, unit)
+        proofs_for_mint = sum(p.amount for p in proofs)
+
+    all_mint_urls = list({k.mint_url for k in wallet.keysets.values()})
+    proof_summary = {
+        f"{k.mint_url}/{k.unit.name}": sum(p.amount for p in wallet.proofs if p.id == k.id)
+        for k in wallet.keysets.values()
+    }
+    # Show ALL proofs in DB by keyset_id, regardless of whether the loaded wallet
+    # knows about that keyset. This reveals proofs orphaned under stale keysets.
+    raw_proofs_by_keyset: dict[str, int] = {}
+    for p in wallet.proofs:
+        raw_proofs_by_keyset[p.id] = raw_proofs_by_keyset.get(p.id, 0) + p.amount
+    logger.info(
+        f"send: proof inventory | mint={effective_mint_url} unit={unit} amount={amount} "
+        f"primary_mint={settings.primary_mint} proofs_for_mint={proofs_for_mint} "
+        f"all_mints={all_mint_urls} by_keyset={proof_summary} "
+        f"raw_proofs_by_keyset_id={raw_proofs_by_keyset} "
+        f"total_wallet_proofs={sum(p.amount for p in wallet.proofs)}"
     )
 
+    # Reserve proofs only after serialization succeeds — if serialize_proofs or
+    # swap_to_send fails mid-way, proofs stay unreserved so dashboard balance
+    # doesn't go negative.
     send_proofs, _ = await wallet.select_to_send(
-        proofs, amount, set_reserved=True, include_fees=False
-    )
-    token = await wallet.serialize_proofs(
-        send_proofs, include_dleq=False, legacy=False, memo=None
+        proofs, amount, set_reserved=False, include_fees=False
     )
+    try:
+        token = await wallet.serialize_proofs(
+            send_proofs, include_dleq=False, legacy=False, memo=None
+        )
+    except Exception:
+        await wallet.set_reserved_for_send(send_proofs, reserved=False)
+        raise
+    await wallet.set_reserved_for_send(send_proofs, reserved=True)
     return amount, token
 
 
@@ -81,10 +122,11 @@ async def _calculate_swap_amount(
     token_mint_url: str,
     token_wallet: Wallet,
     primary_wallet: Wallet,
+    proofs: list,
 ) -> int:
     """
     Calculate the amount to mint on the primary mint after accounting for
-    potential swap fees (melt fees) on the foreign mint.
+    melt fees and NUT-02 input fees on the foreign mint.
     """
     if settings.primary_mint_unit == "sat":
         receive_amount = amount_msat // 1000
@@ -111,10 +153,11 @@ async def _calculate_swap_amount(
         dummy_melt_quote = await token_wallet.melt_quote(dummy_mint_quote.request)
 
         fee_reserve = dummy_melt_quote.fee_reserve
+        input_fees = token_wallet.get_fees_for_proofs(proofs)
         if token_unit == "sat":
-            fee_msat = fee_reserve * 1000
+            fee_msat = (fee_reserve + input_fees) * 1000
         else:
-            fee_msat = fee_reserve
+            fee_msat = fee_reserve + input_fees
 
         amount_msat_after_fee = amount_msat - fee_msat
 
@@ -124,13 +167,14 @@ async def _calculate_swap_amount(
             minted_amount = int(amount_msat_after_fee)
 
         if minted_amount <= 0:
-            raise ValueError(f"Fees ({fee_reserve} {token_unit}) exceed token amount")
+            raise ValueError(f"Fees ({fee_reserve + input_fees} {token_unit}) exceed token amount")
 
         logger.info(
             "swap_to_primary_mint: fee estimation result",
             extra={
                 "token_amount_sat": amount_msat // 1000,
                 "estimated_fee_sat": fee_msat // 1000,
+                "input_fees": input_fees,
                 "minted_amount": minted_amount,
                 "minted_unit": settings.primary_mint_unit,
             },
@@ -191,6 +235,7 @@ async def swap_to_primary_mint(
         token_obj.mint,
         token_wallet,
         primary_wallet,
+        token_obj.proofs,
     )
 
     mint_quote = await primary_wallet.request_mint(minted_amount)
@@ -200,13 +245,15 @@ async def swap_to_primary_mint(
     )
 
     melt_quote = await token_wallet.melt_quote(mint_quote.request)
-    total_needed = melt_quote.amount + melt_quote.fee_reserve
+    input_fees = token_wallet.get_fees_for_proofs(token_obj.proofs)
+    total_needed = melt_quote.amount + melt_quote.fee_reserve + input_fees
     logger.info(
         "swap_to_primary_mint: melt quote received",
         extra={
             "melt_quote_id": melt_quote.quote,
             "melt_amount": melt_quote.amount,
             "melt_fee_reserve": melt_quote.fee_reserve,
+            "input_fees": input_fees,
             "total_needed": total_needed,
             "token_amount": token_amount,
         },
@@ -219,6 +266,7 @@ async def swap_to_primary_mint(
                 "token_amount": token_amount,
                 "melt_amount": melt_quote.amount,
                 "melt_fee_reserve": melt_quote.fee_reserve,
+                "input_fees": input_fees,
                 "total_needed": total_needed,
                 "shortfall": total_needed - token_amount,
             },
@@ -226,7 +274,7 @@ async def swap_to_primary_mint(
         raise ValueError(
             f"Token amount ({token_amount} {token_obj.unit}) is insufficient to cover "
             f"melt fees. Needed: {total_needed} {token_obj.unit} "
-            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve})"
+            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve} + input_fees: {input_fees})"
         )
 
     try:
@@ -257,19 +305,66 @@ async def swap_to_primary_mint(
         extra={"minted_amount": minted_amount, "mint_quote_id": mint_quote.quote},
     )
 
+    await primary_wallet.load_proofs(reload=True)
+    pre_mint_balance = primary_wallet.available_balance.amount
     try:
         _ = await primary_wallet.mint(minted_amount, quote_id=mint_quote.quote)
     except Exception as e:
-        logger.error(
-            "swap_to_primary_mint: mint on primary failed after successful melt",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "minted_amount": minted_amount,
-                "mint_quote_id": mint_quote.quote,
-            },
-        )
-        raise
+        if "11003" in str(e) or "outputs already signed" in str(e).lower():
+            # Previous mint call signed outputs at the mint but failed before
+            # bump_secret_derivation ran locally. Recover orphaned proofs and
+            # advance the counter so the next request derives fresh secrets.
+            logger.warning(
+                "swap_to_primary_mint: outputs already signed — recovering orphaned proofs",
+                extra={"mint_quote_id": mint_quote.quote, "minted_amount": minted_amount},
+            )
+            try:
+                for keyset_id in primary_wallet.keysets:
+                    await primary_wallet.restore_tokens_for_keyset(keyset_id, to=1, batch=25)
+                await primary_wallet.load_proofs(reload=True)
+                post_recovery_balance = primary_wallet.available_balance.amount
+                balance_gained = post_recovery_balance - pre_mint_balance
+                logger.info(
+                    "swap_to_primary_mint: recovery scan completed",
+                    extra={
+                        "pre_mint_balance": pre_mint_balance,
+                        "post_recovery_balance": post_recovery_balance,
+                        "balance_gained": balance_gained,
+                        "expected": minted_amount,
+                    },
+                )
+                if balance_gained < minted_amount:
+                    # Recovery scan ran but did NOT restore the orphaned proofs
+                    # (mint reports them as spent — they're stuck). Refuse to
+                    # credit the API key balance for proofs we don't actually hold.
+                    raise ValueError(
+                        f"Swap recovery failed: mint signed outputs but proofs are "
+                        f"unrecoverable (mint reports them spent). "
+                        f"Expected {minted_amount}, recovered {balance_gained}. "
+                        f"Local wallet DB ('.wallet/') state is corrupted — "
+                        f"the counter for keyset is stuck at a bad index range."
+                    )
+            except ValueError:
+                raise
+            except Exception as recovery_err:
+                logger.error(
+                    "swap_to_primary_mint: recovery failed",
+                    extra={"error": str(recovery_err)},
+                )
+                raise ValueError(
+                    f"Mint on primary failed and recovery unsuccessful: {e}"
+                ) from e
+        else:
+            logger.error(
+                "swap_to_primary_mint: mint on primary failed after successful melt",
+                extra={
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                    "minted_amount": minted_amount,
+                    "mint_quote_id": mint_quote.quote,
+                },
+            )
+            raise
 
     logger.info(
         "swap_to_primary_mint: completed successfully",
@@ -443,7 +538,7 @@ async def fetch_all_balances(
                 "unit": unit,
                 "wallet_balance": proofs_balance,
                 "user_balance": user_balance,
-                "owner_balance": proofs_balance - user_balance,
+                "owner_balance": proofs_balance - user_balance if proofs_balance != 0 else 0,
             }
             return result
         except Exception as e:
@@ -491,7 +586,9 @@ async def fetch_all_balances(
             total_wallet_balance_sats += proofs_balance_sats
             total_user_balance_sats += user_balance_sats
 
-    owner_balance = total_wallet_balance_sats - total_user_balance_sats
+    owner_balance = 0
+    if total_wallet_balance_sats != 0:
+        owner_balance = total_wallet_balance_sats - total_user_balance_sats
 
     return (
         balance_details,
@@ -502,11 +599,11 @@ async def fetch_all_balances(
 
 
 async def periodic_payout() -> None:
-    if not settings.receive_ln_address:
-        logger.warning("RECEIVE_LN_ADDRESS is not set, periodic payout disabled")
-        return
     while True:
-        await asyncio.sleep(60 * 15)
+        await asyncio.sleep(settings.payout_interval_seconds)
+        print(settings.payout_interval_seconds)
+        if not settings.receive_ln_address:
+            continue
         try:
             async with db.create_session() as session:
                 for mint_url in settings.cashu_mints:
@@ -524,7 +621,12 @@ async def periodic_payout() -> None:
                             user_balance = user_balance // 1000
                         proofs_balance = sum(proof.amount for proof in proofs)
                         available_balance = proofs_balance - user_balance
-                        min_amount = 210 if unit == "sat" else 210000
+                        # Threshold is configured in sats; convert for msat wallets.
+                        min_amount = (
+                            settings.min_payout_sat
+                            if unit == "sat"
+                            else settings.min_payout_sat * 1000
+                        )
                         if available_balance > min_amount:
                             amount_received = await raw_send_to_lnurl(
                                 wallet,

tests/integration/test_wallet_refund.py

@@ -372,17 +372,17 @@ async def test_refund_rejects_concurrent_topup_on_same_key(
     topup_amount_sat = 500
     topup_token = await testmint_wallet.mint_tokens(topup_amount_sat)
 
-    validate_called = asyncio.Event()
+    key_looked_up = asyncio.Event()
     allow_refund_to_continue = asyncio.Event()
-    original_validate_bearer_key = balance_module.validate_bearer_key
+    original_lookup = balance_module._lookup_key_no_create
     delayed_once = False
 
-    async def delayed_validate_bearer_key(*args: Any, **kwargs: Any) -> ApiKey:
+    async def delayed_lookup_key_no_create(*args: Any, **kwargs: Any) -> ApiKey | None:
         nonlocal delayed_once
-        key = await original_validate_bearer_key(*args, **kwargs)
-        if not delayed_once:
+        key = await original_lookup(*args, **kwargs)
+        if not delayed_once and key is not None:
             delayed_once = True
-            validate_called.set()
+            key_looked_up.set()
             await allow_refund_to_continue.wait()
         return key
 
@@ -390,7 +390,7 @@ async def test_refund_rejects_concurrent_topup_on_same_key(
         return await authenticated_client.post("/v1/wallet/refund")
 
     async def issue_topup() -> Any:
-        await validate_called.wait()
+        await key_looked_up.wait()
         try:
             return await authenticated_client.post(
                 "/v1/wallet/topup", params={"cashu_token": topup_token}
@@ -399,7 +399,7 @@ async def test_refund_rejects_concurrent_topup_on_same_key(
             allow_refund_to_continue.set()
 
     with patch(
-        "routstr.balance.validate_bearer_key", new=delayed_validate_bearer_key
+        "routstr.balance._lookup_key_no_create", new=delayed_lookup_key_no_create
     ):
         refund_response, topup_response = await asyncio.gather(
             issue_refund(), issue_topup()

tests/unit/test_balance.py

@@ -168,12 +168,12 @@ async def test_apikey_refund_stores_cashu_transaction_with_apikey_source() -> No
     refund_token = "cashuArefund_apikey_token"
 
     session = MagicMock()
+    session.get = AsyncMock(return_value=key)
     session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
     with (
-        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
         patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()) as mock_store,
@@ -203,12 +203,12 @@ async def test_apikey_refund_logs_token() -> None:
     refund_token = "cashuAlogged_token"
 
     session = MagicMock()
+    session.get = AsyncMock(return_value=key)
     session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
     with (
-        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
         patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()),
@@ -232,12 +232,12 @@ async def test_apikey_refund_log_includes_path() -> None:
     refund_token = "cashuApath_token"
 
     session = MagicMock()
+    session.get = AsyncMock(return_value=key)
     session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
     with (
-        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
         patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()),
@@ -269,6 +269,7 @@ async def test_apikey_refund_rejects_on_concurrent_balance_change() -> None:
     key = _make_api_key(balance=5000, refund_currency="sat")
 
     session = MagicMock()
+    session.get = AsyncMock(return_value=key)
     # Debit returns rowcount=0 → balance changed concurrently
     session.exec = AsyncMock(return_value=_update_result(0))
     session.commit = AsyncMock()
@@ -276,7 +277,6 @@ async def test_apikey_refund_rejects_on_concurrent_balance_change() -> None:
     mock_send_token = AsyncMock(return_value="cashuAshould_not_be_minted")
 
     with (
-        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
         patch("routstr.balance.send_token", mock_send_token),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()),
@@ -333,11 +333,11 @@ async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
 
     # First exec call = debit (succeeds), second = restore
     session = MagicMock()
+    session.get = AsyncMock(return_value=key)
     session.exec = AsyncMock(side_effect=[_update_result(1), _update_result(1)])
     session.commit = AsyncMock()
 
     with (
-        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
         patch("routstr.balance.send_token", AsyncMock(side_effect=Exception("mint down"))),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()),
@@ -355,3 +355,49 @@ async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
     assert exc_info.value.status_code == 503
     # Verify two exec calls: debit + restore
     assert session.exec.await_count == 2
+
+
+# ---------------------------------------------------------------------------
+# no-create guarantee: fresh Cashu/unknown sk- tokens must not create API keys
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_refund_fresh_cashu_bearer_returns_401() -> None:
+    """Fresh Cashu token not in DB must get 401, never create a new ApiKey."""
+    from fastapi import HTTPException
+
+    session = MagicMock()
+    session.get = AsyncMock(return_value=None)
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer cashuAfresh_never_deposited_token",
+            x_cashu=None,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 401
+    session.get.assert_awaited_once()
+    # No add/commit → no key was persisted
+    session.add.assert_not_called()
+    session.commit.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_refund_unknown_sk_bearer_returns_401() -> None:
+    """Unknown sk- key not in DB must get 401."""
+    from fastapi import HTTPException
+
+    session = MagicMock()
+    session.get = AsyncMock(return_value=None)
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-unknownhash",
+            x_cashu=None,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 401
+    session.get.assert_awaited_once()

tests/unit/test_count_tokens_local.py

@@ -0,0 +1,177 @@
+"""Unit tests for the local count_tokens shim.
+
+The shim runs whenever an upstream that does not support Anthropic's
+``/v1/messages`` endpoint is asked for a token count. It must always
+return a 200 JSON ``{"input_tokens": N}`` response and must never raise.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import patch
+
+from routstr.payment.models import Architecture, Model, Pricing
+from routstr.upstream import count_tokens as count_tokens_module
+from routstr.upstream.count_tokens import count_tokens_locally
+
+
+def _make_model(model_id: str = "anthropic/claude-3-5-sonnet") -> Model:
+    pricing = Pricing(prompt=0.000003, completion=0.000015)
+    architecture = Architecture(
+        modality="text",
+        input_modalities=["text"],
+        output_modalities=["text"],
+        tokenizer="cl100k_base",
+        instruct_type=None,
+    )
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="",
+        context_length=200_000,
+        architecture=architecture,
+        pricing=pricing,
+    )
+
+
+def _body(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload).encode()
+
+
+def _read_payload(response: Any) -> dict[str, Any]:
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    return json.loads(body.decode())
+
+
+def test_returns_input_tokens_for_simple_messages() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "hello world"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, model)
+
+    assert response.status_code == 200
+    assert response.media_type == "application/json"
+    payload = _read_payload(response)
+    assert "input_tokens" in payload
+    assert isinstance(payload["input_tokens"], int)
+    assert payload["input_tokens"] >= 0
+
+
+def test_falls_back_to_estimator_when_litellm_raises() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "this is a longer message"}],
+        }
+    )
+
+    with patch.object(
+        count_tokens_module,
+        "_count_with_litellm",
+        side_effect=RuntimeError("boom"),
+    ):
+        response = count_tokens_locally(request_body, model)
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 1
+
+
+def test_handles_missing_model_object() -> None:
+    request_body = _body(
+        {
+            "model": "anthropic/claude-3-5-sonnet",
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, None)
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_handles_empty_request_body() -> None:
+    response = count_tokens_locally(b"", _make_model())
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_handles_malformed_json() -> None:
+    response = count_tokens_locally(b"not-json", _make_model())
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_includes_system_prompt_in_count() -> None:
+    model = _make_model()
+    short = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+    with_system = _body(
+        {
+            "model": model.id,
+            "system": "You are a helpful assistant with a long preamble " * 10,
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    short_count = _read_payload(count_tokens_locally(short, model))["input_tokens"]
+    long_count = _read_payload(count_tokens_locally(with_system, model))["input_tokens"]
+
+    assert long_count > short_count
+
+
+def test_supports_anthropic_system_block_list() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "system": [{"type": "text", "text": "be terse" * 50}],
+            "messages": [{"role": "user", "content": "ok"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, model)
+
+    payload = _read_payload(response)
+    assert payload["input_tokens"] > 0
+
+
+def test_uses_forwarded_model_id_when_present() -> None:
+    model = _make_model("anthropic/claude-3-5-sonnet")
+    model.forwarded_model_id = "claude-3-5-sonnet-20241022"
+    request_body = _body(
+        {
+            "model": "ignored",
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    captured: dict[str, Any] = {}
+
+    def _capture(model_name: str, body: dict[str, Any]) -> int:
+        captured["model"] = model_name
+        return 7
+
+    with patch.object(count_tokens_module, "_count_with_litellm", side_effect=_capture):
+        response = count_tokens_locally(request_body, model)
+
+    assert captured["model"] == "claude-3-5-sonnet-20241022"
+    assert _read_payload(response)["input_tokens"] == 7

tests/unit/test_messages_litellm_dispatch.py

@@ -908,7 +908,7 @@ async def test_forward_request_skips_litellm_when_provider_supports_messages() -
 
 
 @pytest.mark.asyncio
-async def test_forward_request_skips_litellm_for_count_tokens() -> None:
+async def test_forward_request_handles_count_tokens_locally() -> None:
     provider = _make_provider()
     key = _make_key()
     model = _make_model()
@@ -923,19 +923,25 @@ async def test_forward_request_skips_litellm_for_count_tokens() -> None:
         with patch.object(
             provider,
             "prepare_request_body",
-            side_effect=RuntimeError("stop here"),
+            side_effect=AssertionError("upstream should not be called"),
         ):
-            with pytest.raises(RuntimeError, match="stop here"):
-                await provider.forward_request(
-                    request=request,
-                    path="messages/count_tokens",
-                    headers={},
-                    request_body=_anthropic_request_body(),
-                    key=key,
-                    max_cost_for_model=10_000,
-                    session=session,
-                    model_obj=model,
-                )
+            response = await provider.forward_request(
+                request=request,
+                path="messages/count_tokens",
+                headers={},
+                request_body=_anthropic_request_body(),
+                key=key,
+                max_cost_for_model=10_000,
+                session=session,
+                model_obj=model,
+            )
+
+    assert response.status_code == 200
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    payload = json.loads(body.decode())
+    assert "input_tokens" in payload
+    assert isinstance(payload["input_tokens"], int)
+    assert payload["input_tokens"] >= 0
 
 
 # ---------------------------------------------------------------------------
@@ -1010,7 +1016,7 @@ async def test_forward_x_cashu_request_skips_litellm_when_native_messages() -> N
 
 
 @pytest.mark.asyncio
-async def test_forward_x_cashu_request_skips_litellm_for_count_tokens() -> None:
+async def test_forward_x_cashu_request_handles_count_tokens_locally() -> None:
     provider = _make_provider()
     model = _make_model()
     request = _make_request()
@@ -1024,18 +1030,24 @@ async def test_forward_x_cashu_request_skips_litellm_for_count_tokens() -> None:
         with patch.object(
             provider,
             "prepare_request_body",
-            side_effect=RuntimeError("stop here"),
+            side_effect=AssertionError("upstream should not be called"),
         ):
-            with pytest.raises(RuntimeError, match="stop here"):
-                await provider.forward_x_cashu_request(
-                    request=request,
-                    path="v1/messages/count_tokens",
-                    headers={},
-                    amount=5_000,
-                    unit="sat",
-                    max_cost_for_model=10_000,
-                    model_obj=model,
-                )
+            response = await provider.forward_x_cashu_request(
+                request=request,
+                path="v1/messages/count_tokens",
+                headers={},
+                amount=5_000,
+                unit="sat",
+                max_cost_for_model=10_000,
+                model_obj=model,
+                mint="https://mint",
+                payment_token_hash="h",
+            )
+
+    assert response.status_code == 200
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    payload = json.loads(body.decode())
+    assert "input_tokens" in payload
 
 
 # ---------------------------------------------------------------------------

tests/unit/test_proxy_not_found.py

@@ -0,0 +1,70 @@
+"""Tests for the app-level 404 handler in routstr.core.main."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from routstr.core import main as core_main
+
+
+def _make_app() -> FastAPI:
+    app = FastAPI()
+    app.add_api_route(
+        "/{path:path}",
+        core_main.not_found_catch_all,
+        methods=["GET", "POST"],
+        include_in_schema=False,
+    )
+    return app
+
+
+@pytest.mark.skipif(
+    core_main._NOT_FOUND_HTML is None,
+    reason="UI bundle (ui_out/404.html) not present in this environment",
+)
+def test_unknown_path_returns_html_404_for_browser() -> None:
+    client = TestClient(_make_app())
+    response = client.get("/some/random/page", headers={"accept": "text/html"})
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("text/html")
+    assert "404" in response.text
+
+
+def test_unknown_path_returns_json_404_for_api_client() -> None:
+    client = TestClient(_make_app())
+    response = client.get(
+        "/some/random/page", headers={"accept": "application/json"}
+    )
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("application/json")
+    payload = response.json()
+    assert payload["error"]["type"] == "not_found"
+    assert payload["error"]["code"] == 404
+    assert "/some/random/page" in payload["error"]["message"]
+
+
+def test_root_path_returns_404() -> None:
+    client = TestClient(_make_app())
+    response = client.get("/", headers={"accept": "application/json"})
+    assert response.status_code == 404
+
+
+def test_json_returned_when_ui_html_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    from routstr.core import not_found as nf
+
+    monkeypatch.setattr(nf, "_NOT_FOUND_HTML", None)
+    client = TestClient(_make_app())
+    response = client.get("/some/random/page", headers={"accept": "text/html"})
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("application/json")
+
+
+def test_post_unknown_path_returns_json_even_for_browser() -> None:
+    client = TestClient(_make_app())
+    response = client.post("/some/random/page", headers={"accept": "text/html"})
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("application/json")
+    payload = response.json()
+    assert payload["error"]["type"] == "not_found"

tests/unit/test_settings.py

@@ -1,11 +1,12 @@
 import os
 
 import pytest
+from pydantic.v1 import ValidationError
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlmodel import text
 from sqlmodel.ext.asyncio.session import AsyncSession
 
-from routstr.core.settings import SettingsService
+from routstr.core.settings import Settings, SettingsService
 
 
 @pytest.mark.asyncio
@@ -46,6 +47,54 @@ async def test_settings_db_precedence_over_env() -> None:
         assert again.enable_analytics_sharing is False
 
 
+def test_payout_settings_have_sensible_defaults() -> None:
+    s = Settings()
+    assert s.min_payout_sat == 210
+    assert s.payout_interval_seconds == 900
+
+
+@pytest.mark.parametrize(
+    "field,bad_value",
+    [
+        ("min_payout_sat", 0),
+        ("min_payout_sat", -1),
+        ("payout_interval_seconds", 0),
+        ("payout_interval_seconds", -10),
+    ],
+)
+def test_payout_settings_reject_invalid_values(field: str, bad_value: int) -> None:
+    kwargs: dict[str, object] = {field: bad_value}
+    with pytest.raises(ValidationError):
+        Settings(**kwargs)  # type: ignore[arg-type]
+
+
+def test_payout_settings_accept_custom_positive_values() -> None:
+    s = Settings(min_payout_sat=500, payout_interval_seconds=60)
+    assert s.min_payout_sat == 500
+    assert s.payout_interval_seconds == 60
+
+
+@pytest.mark.asyncio
+async def test_payout_settings_persist_via_settings_service() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        await SettingsService.initialize(session)
+        updated = await SettingsService.update(
+            {"min_payout_sat": 1000, "payout_interval_seconds": 300}, session
+        )
+        assert updated.min_payout_sat == 1000
+        assert updated.payout_interval_seconds == 300
+
+
+@pytest.mark.asyncio
+async def test_payout_settings_update_rejects_invalid() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        await SettingsService.initialize(session)
+        with pytest.raises(ValidationError):
+            await SettingsService.update({"min_payout_sat": 0}, session)
+
+
 @pytest.mark.asyncio
 async def test_settings_initialize_discards_unknown_keys() -> None:
     engine = create_async_engine("sqlite+aiosqlite:///:memory:")

tests/unit/test_upstream_error_response.py

@@ -0,0 +1,150 @@
+"""Tests for ``BaseUpstreamProvider.forward_upstream_error_response``.
+
+Upstream services (e.g. an Express server that doesn't expose ``/messages``)
+sometimes return a non-JSON error body. The proxy must surface those errors
+in a consistent JSON envelope so clients don't have to parse HTML.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import Mock
+
+import httpx
+import pytest
+
+from routstr.upstream.base import BaseUpstreamProvider, _is_json_content_type
+
+
+def _make_request(request_id: str = "req-123") -> Mock:
+    request = Mock(spec=["method", "state"])
+    request.method = "POST"
+    request.state = Mock()
+    request.state.request_id = request_id
+    return request
+
+
+def _make_upstream_response(
+    *,
+    body: bytes,
+    status_code: int = 404,
+    content_type: str | None = "text/html",
+    extra_headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    headers: dict[str, str] = {}
+    if content_type is not None:
+        headers["content-type"] = content_type
+    if extra_headers:
+        headers.update(extra_headers)
+    return httpx.Response(status_code=status_code, headers=headers, content=body)
+
+
+@pytest.fixture
+def provider() -> BaseUpstreamProvider:
+    return BaseUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="k", provider_fee=1.0
+    )
+
+
+@pytest.mark.parametrize(
+    "content_type,expected",
+    [
+        ("application/json", True),
+        ("application/json; charset=utf-8", True),
+        ("text/json", True),
+        ("application/problem+json", True),
+        ("application/vnd.api+json", True),
+        ("text/html", False),
+        ("text/html; charset=utf-8", False),
+        ("text/plain", False),
+        ("", False),
+        (None, False),
+    ],
+)
+def test_is_json_content_type(content_type: str | None, expected: bool) -> None:
+    assert _is_json_content_type(content_type) is expected
+
+
+@pytest.mark.asyncio
+async def test_html_error_is_normalized_to_json_envelope(
+    provider: BaseUpstreamProvider,
+) -> None:
+    html_body = (
+        b"<!DOCTYPE html><html><head><title>Error</title></head>"
+        b"<body><pre>Cannot POST /messages</pre></body></html>"
+    )
+    upstream = _make_upstream_response(body=html_body, status_code=404)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 404
+    assert response.media_type == "application/json"
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["upstream_status"] == 404
+    assert payload["error"]["upstream_content_type"] == "text/html"
+    assert "Cannot POST /messages" in payload["error"]["upstream_body_preview"]
+    assert payload["request_id"] == "req-123"
+    # The upstream's text/html content-type must not survive — Response()
+    # sets the JSON content-type for us via media_type.
+    assert response.headers["content-type"].startswith("application/json")
+
+
+@pytest.mark.asyncio
+async def test_plain_text_error_is_normalized(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=b"Service Unavailable", status_code=503, content_type="text/plain"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 503
+    assert response.media_type == "application/json"
+    payload = json.loads(bytes(response.body))
+    assert payload["error"]["message"] == "Service Unavailable"
+
+
+@pytest.mark.asyncio
+async def test_empty_body_with_non_json_content_type_normalizes(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=b"", status_code=502, content_type="text/html"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 502
+    assert response.media_type == "application/json"
+    payload = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["upstream_body_preview"] is None
+
+
+@pytest.mark.asyncio
+async def test_json_error_body_is_passed_through_unchanged(
+    provider: BaseUpstreamProvider,
+) -> None:
+    json_body = json.dumps(
+        {"error": {"message": "Invalid model", "type": "invalid_request_error"}}
+    ).encode()
+    upstream = _make_upstream_response(
+        body=json_body, status_code=400, content_type="application/json"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 400
+    assert bytes(response.body) == json_body
+    assert response.media_type == "application/json"

tests/unit/test_upstream_routstr.py

@@ -74,3 +74,39 @@ async def test_get_balance_returns_none_on_connect_timeout(
     balance = await provider.get_balance()
 
     assert balance is None
+
+
+def test_normalize_request_path_keeps_v1_prefix() -> None:
+    """Routstr upstream stores ``base_url`` without ``/v1``; the prefix
+    must stay on the path so ``build_request_url`` produces ``/v1/<endpoint>``
+    instead of ``/<endpoint>`` (which the upstream Routstr 404s with HTML)."""
+    provider = RoutstrUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="key"
+    )
+
+    assert provider.normalize_request_path("v1/messages") == "v1/messages"
+    assert provider.normalize_request_path("/v1/messages") == "v1/messages"
+    assert (
+        provider.normalize_request_path("v1/chat/completions")
+        == "v1/chat/completions"
+    )
+
+
+def test_build_request_url_for_v1_messages() -> None:
+    """Forwarding ``/v1/messages`` must hit the upstream's ``/v1/messages``."""
+    provider = RoutstrUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="key"
+    )
+
+    normalized = provider.normalize_request_path("v1/messages")
+
+    assert (
+        provider.build_request_url(normalized)
+        == "https://privateprovider.xyz/v1/messages"
+    )
+
+
+def test_supports_anthropic_messages_natively() -> None:
+    """Routstr nodes serve ``/v1/messages`` directly, so the proxy must
+    forward as-is instead of round-tripping through litellm."""
+    assert RoutstrUpstreamProvider.supports_anthropic_messages is True

tests/unit/test_wallet.py

@@ -123,6 +123,7 @@ async def test_swap_to_primary_mint_insufficient_for_fees() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()
@@ -166,6 +167,7 @@ async def test_swap_to_primary_mint_melt_error_wrapped() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()
@@ -261,6 +263,7 @@ async def test_swap_to_primary_mint_success() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()

ui/components/add-provider-model-dialog.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { z } from 'zod';
 import { zodResolver } from '@hookform/resolvers/zod';

ui/components/app-page-shell.tsx

@@ -21,6 +21,7 @@ import { adminLogout } from '@/lib/api/services/auth';
 import { Button } from '@/components/ui/button';
 import { CurrencyToggle } from '@/components/currency-toggle';
 import { ThemeToggle } from '@/components/theme-toggle';
+import { VersionStatus } from '@/components/version-status';
 import {
   Sheet,
   SheetClose,
@@ -110,6 +111,7 @@ export function AppPageShell({
                   <h1 className='truncate text-lg font-semibold tracking-tight whitespace-nowrap'>
                     Routstr Node
                   </h1>
+                  <VersionStatus className='mt-0.5' />
                 </div>
               </div>
               <Button
@@ -279,9 +281,12 @@ export function AppPageShell({
                     height={24}
                     className='rounded-sm'
                   />
-                  <p className='truncate text-base font-medium tracking-tight'>
-                    Routstr Node
-                  </p>
+                  <div className='min-w-0'>
+                    <p className='truncate text-base font-medium tracking-tight'>
+                      Routstr Node
+                    </p>
+                    <VersionStatus className='mt-0.5' />
+                  </div>
                 </div>
                 <SheetClose asChild>
                   <Button

ui/components/settings/admin-settings.tsx

@@ -32,9 +32,18 @@ interface SettingsData {
   onion_url?: string;
   cashu_mints?: string[];
   relays?: string[];
+  receive_ln_address?: string;
+  min_payout_sat?: number;
+  payout_interval_seconds?: number;
   [key: string]: unknown;
 }
 
+const PAYOUT_KEYS = [
+  'receive_ln_address',
+  'min_payout_sat',
+  'payout_interval_seconds',
+] as const;
+
 const HANDLED_KEYS = [
   'name',
   'description',
@@ -48,6 +57,7 @@ const HANDLED_KEYS = [
   'admin_password',
   'id',
   'updated_at',
+  ...PAYOUT_KEYS,
 ];
 
 const IGNORED_KEYS = [
@@ -369,6 +379,7 @@ export function AdminSettings() {
   const cashuMintsChanged = hasFieldChanged('cashu_mints');
   const relaysChanged = hasFieldChanged('relays');
   const analyticsSharingChanged = hasFieldChanged('enable_analytics_sharing');
+  const payoutChanged = PAYOUT_KEYS.some(hasFieldChanged);
   const advancedKeys = Object.keys(settings).filter(
     (key) => !HANDLED_KEYS.includes(key) && !IGNORED_KEYS.includes(key)
   );
@@ -401,8 +412,44 @@ export function AdminSettings() {
     setNewRelay('');
   };
   const resetAnalyticsSharing = () => resetFields(['enable_analytics_sharing']);
+  const resetPayout = () => resetFields([...PAYOUT_KEYS]);
   const resetAdvanced = () => resetFields(advancedKeys);
 
+  const payoutFields: ReadonlyArray<{
+    key: (typeof PAYOUT_KEYS)[number];
+    label: string;
+    placeholder: string;
+    type: 'text' | 'number';
+    helpText: string;
+    min?: number;
+  }> = [
+    {
+      key: 'receive_ln_address',
+      label: 'Lightning Receive Address',
+      placeholder: 'you@walletofsatoshi.com or LNURL',
+      type: 'text',
+      helpText:
+        'Lightning address (or LNURL) profits are paid out to. Leave empty to disable periodic payouts.',
+    },
+    {
+      key: 'min_payout_sat',
+      label: 'Minimum Payout (sat)',
+      placeholder: '210',
+      type: 'number',
+      min: 1,
+      helpText:
+        'Wallet payouts only fire when at least this many satoshis are available. Must be > 0.',
+    },
+    {
+      key: 'payout_interval_seconds',
+      label: 'Payout Interval (seconds)',
+      placeholder: '900',
+      type: 'number',
+      min: 1,
+      helpText: 'How often the payout loop wakes up to check balances.',
+    },
+  ];
+
   if (loading) {
     return (
       <div className='space-y-4'>
@@ -620,6 +667,89 @@ export function AdminSettings() {
           ) : null}
         </Card>
 
+        {/* Lightning Payout Settings */}
+        <Card>
+          <CardHeader>
+            <CardTitle>Lightning Payout Settings</CardTitle>
+            <CardDescription>
+              Tune how node profit is paid out over Lightning. Amounts must be
+              positive and above your wallet&apos;s minimum-invoice constraints.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className='space-y-4'>
+            {payoutFields.map((field) => {
+              const value = settings[field.key];
+              if (field.type === 'number') {
+                return (
+                  <div key={field.key} className='space-y-2'>
+                    <Label htmlFor={field.key}>{field.label}</Label>
+                    <Input
+                      id={field.key}
+                      type='number'
+                      min={field.min}
+                      value={
+                        typeof value === 'number'
+                          ? value
+                          : value === undefined || value === null
+                            ? ''
+                            : Number(value)
+                      }
+                      placeholder={field.placeholder}
+                      onChange={(e) => {
+                        const raw = e.target.value;
+                        if (raw === '') {
+                          handleInputChange(field.key, undefined);
+                        } else {
+                          const parsed = Number(raw);
+                          handleInputChange(
+                            field.key,
+                            Number.isFinite(parsed) ? parsed : undefined
+                          );
+                        }
+                      }}
+                    />
+                    <p className='text-muted-foreground text-xs'>
+                      {field.helpText}
+                    </p>
+                  </div>
+                );
+              }
+              return (
+                <div key={field.key} className='space-y-2'>
+                  <Label htmlFor={field.key}>{field.label}</Label>
+                  <Input
+                    id={field.key}
+                    value={(value as string) || ''}
+                    placeholder={field.placeholder}
+                    onChange={(e) =>
+                      handleInputChange(field.key, e.target.value)
+                    }
+                  />
+                  <p className='text-muted-foreground text-xs'>
+                    {field.helpText}
+                  </p>
+                </div>
+              );
+            })}
+          </CardContent>
+          {payoutChanged ? (
+            <CardFooter className='justify-start'>
+              <div className='flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center'>
+                <Button
+                  variant='outline'
+                  onClick={resetPayout}
+                  disabled={loading || saving}
+                >
+                  Cancel
+                </Button>
+                <Button onClick={handleSave} disabled={loading || saving}>
+                  {saving ? 'Saving...' : 'Save'}
+                </Button>
+              </div>
+            </CardFooter>
+          ) : null}
+        </Card>
+
         {/* Relays */}
         <Card>
           <CardHeader>

ui/components/version-status.tsx

@@ -0,0 +1,282 @@
+'use client';
+
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import {
+  AlertTriangleIcon,
+  CheckCircle2Icon,
+  ExternalLinkIcon,
+  InfoIcon,
+  Loader2Icon,
+  RefreshCwIcon,
+} from 'lucide-react';
+import { ConfigurationService } from '@/lib/api/services/configuration';
+import { Button } from '@/components/ui/button';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
+import { cn } from '@/lib/utils';
+import {
+  deriveStatus,
+  formatReleaseDate,
+  formatVersionLabel,
+  parseVersion,
+  type StatusKind,
+} from '@/lib/utils/version';
+
+interface NodeInfo {
+  version?: string;
+}
+
+interface GithubRelease {
+  tag_name: string;
+  name?: string;
+  html_url: string;
+  published_at?: string;
+  body?: string;
+}
+
+const NODE_QUERY_KEY = ['node-version'] as const;
+const RELEASE_QUERY_KEY = ['routstr-latest-release'] as const;
+const THIRTY_MINUTES = 30 * 60 * 1000;
+
+const GITHUB_RELEASES_URL = `https://api.github.com/repos/Routstr/routstr-core/releases/latest`;
+const RELEASES_PAGE_URL = `https://github.com/Routstr/routstr-core/releases`;
+
+async function fetchNodeInfo(): Promise<NodeInfo> {
+  const baseUrl = ConfigurationService.getLocalBaseUrl().replace(/\/+$/, '');
+  const response = await fetch(`${baseUrl}/v1/info`, {
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error('Unable to load node info');
+  }
+  return (await response.json()) as NodeInfo;
+}
+
+async function fetchLatestRelease(): Promise<GithubRelease | null> {
+  const response = await fetch(GITHUB_RELEASES_URL, {
+    headers: { Accept: 'application/vnd.github+json' },
+  });
+  if (response.status === 403 || response.status === 404) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`GitHub responded ${response.status}`);
+  }
+  return (await response.json()) as GithubRelease;
+}
+
+function pickColorClass(status: StatusKind): string {
+  if (status === 'outdated') return 'text-amber-600 dark:text-amber-400';
+  if (status === 'unknown') return 'text-muted-foreground';
+  if (status === 'ahead' || status === 'commit-drift') {
+    return 'text-sky-600 dark:text-sky-400';
+  }
+  return 'text-emerald-600 dark:text-emerald-400';
+}
+
+function renderStatusIcon(status: StatusKind, className: string) {
+  if (status === 'outdated') {
+    return <AlertTriangleIcon className={className} />;
+  }
+  if (status === 'commit-drift' || status === 'ahead' || status === 'unknown') {
+    return <InfoIcon className={className} />;
+  }
+  return <CheckCircle2Icon className={className} />;
+}
+
+function describeStatus(status: StatusKind): string {
+  if (status === 'outdated') return 'A newer release is available.';
+  if (status === 'commit-drift') {
+    return 'Running release version on a non-release commit.';
+  }
+  if (status === 'ahead') {
+    return 'Running ahead of the latest published release.';
+  }
+  if (status === 'current') return 'Up to date with the latest release.';
+  return 'Version status unavailable.';
+}
+
+interface VersionStatusProps {
+  variant?: 'expanded' | 'compact';
+  className?: string;
+}
+
+export function VersionStatus({
+  variant = 'expanded',
+  className,
+}: VersionStatusProps) {
+  const queryClient = useQueryClient();
+
+  const nodeQuery = useQuery({
+    queryKey: NODE_QUERY_KEY,
+    queryFn: fetchNodeInfo,
+    staleTime: THIRTY_MINUTES,
+    retry: 1,
+  });
+
+  const releaseQuery = useQuery({
+    queryKey: RELEASE_QUERY_KEY,
+    queryFn: fetchLatestRelease,
+    staleTime: THIRTY_MINUTES,
+    refetchInterval: THIRTY_MINUTES,
+    refetchOnWindowFocus: false,
+    retry: 1,
+  });
+
+  const currentVersion = parseVersion(nodeQuery.data?.version);
+  const latestVersion = parseVersion(releaseQuery.data?.tag_name);
+  const status = deriveStatus(currentVersion, latestVersion);
+
+  const isRefreshing = releaseQuery.isFetching || nodeQuery.isFetching;
+
+  const handleRefresh = async (): Promise<void> => {
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: NODE_QUERY_KEY }),
+      queryClient.invalidateQueries({ queryKey: RELEASE_QUERY_KEY }),
+    ]);
+  };
+
+  const colorClass = pickColorClass(status);
+  const versionLabel = currentVersion
+    ? formatVersionLabel(currentVersion)
+    : nodeQuery.isLoading
+      ? '…'
+      : 'unknown';
+
+  if (!nodeQuery.data && nodeQuery.isLoading && variant === 'expanded') {
+    return null;
+  }
+
+  const statusDescription = describeStatus(status);
+  const ariaLabel = `Node version ${versionLabel}. ${statusDescription} Click for details.`;
+
+  const releaseRateLimited = releaseQuery.data === null;
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type='button'
+          onClick={(e) => e.stopPropagation()}
+          className={cn(
+            'hover:bg-accent/40 inline-flex items-center gap-1 rounded-md px-1 py-0.5 font-mono text-[10px] leading-tight transition-colors',
+            colorClass,
+            className
+          )}
+          title='View version details'
+          aria-label={ariaLabel}
+        >
+          {renderStatusIcon(status, 'h-3 w-3 shrink-0')}
+          <span className='truncate'>{versionLabel}</span>
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        side='bottom'
+        align='start'
+        sideOffset={6}
+        className='w-72 p-3'
+      >
+        <div className='flex items-start justify-between gap-2'>
+          <div className='min-w-0 space-y-0.5'>
+            <div className='flex items-center gap-1.5 text-sm font-medium'>
+              {renderStatusIcon(status, cn('h-4 w-4 shrink-0', colorClass))}
+              Node Version
+            </div>
+            <p className='text-muted-foreground text-xs leading-snug'>
+              {statusDescription}
+            </p>
+          </div>
+          <Button
+            type='button'
+            variant='outline'
+            size='icon'
+            className='h-7 w-7 shrink-0'
+            onClick={handleRefresh}
+            disabled={isRefreshing}
+            title='Check for latest release'
+          >
+            {isRefreshing ? (
+              <Loader2Icon className='h-3.5 w-3.5 animate-spin' />
+            ) : (
+              <RefreshCwIcon className='h-3.5 w-3.5' />
+            )}
+            <span className='sr-only'>Check for latest release</span>
+          </Button>
+        </div>
+
+        <div className='mt-3 space-y-2'>
+          <div className='border-border/60 bg-card/30 grid gap-1.5 rounded-md border p-2'>
+            <div className='flex items-center justify-between gap-3'>
+              <span className='text-muted-foreground text-[10px] tracking-wide uppercase'>
+                Current
+              </span>
+              <span className='font-mono text-xs'>{versionLabel}</span>
+            </div>
+            {currentVersion?.commit ? (
+              <div className='flex items-center justify-between gap-3'>
+                <span className='text-muted-foreground text-[10px] tracking-wide uppercase'>
+                  Commit
+                </span>
+                <code className='font-mono text-[11px]'>
+                  {currentVersion.commit}
+                </code>
+              </div>
+            ) : null}
+          </div>
+
+          <div className='border-border/60 bg-card/30 grid gap-1.5 rounded-md border p-2'>
+            <div className='flex items-center justify-between gap-3'>
+              <span className='text-muted-foreground text-[10px] tracking-wide uppercase'>
+                Latest release
+              </span>
+              <span className='font-mono text-xs'>
+                {releaseQuery.isLoading
+                  ? 'loading…'
+                  : releaseQuery.isError
+                    ? 'unavailable'
+                    : releaseRateLimited
+                      ? 'rate-limited'
+                      : (releaseQuery.data?.tag_name ?? 'unknown')}
+              </span>
+            </div>
+            {releaseQuery.data?.published_at ? (
+              <div className='flex items-center justify-between gap-3'>
+                <span className='text-muted-foreground text-[10px] tracking-wide uppercase'>
+                  Published
+                </span>
+                <span className='text-[11px]'>
+                  {formatReleaseDate(releaseQuery.data.published_at)}
+                </span>
+              </div>
+            ) : null}
+          </div>
+
+          {releaseQuery.isError ? (
+            <p className='text-muted-foreground text-[11px]'>
+              Failed to fetch latest release from GitHub.
+            </p>
+          ) : releaseRateLimited ? (
+            <p className='text-muted-foreground text-[11px]'>
+              GitHub rate limit reached. Try again later.
+            </p>
+          ) : null}
+        </div>
+
+        <div className='border-border/60 mt-3 border-t pt-2'>
+          <a
+            href={releaseQuery.data?.html_url ?? RELEASES_PAGE_URL}
+            target='_blank'
+            rel='noopener noreferrer'
+            className='text-primary inline-flex items-center gap-1 text-xs hover:underline'
+          >
+            View release changelog
+            <ExternalLinkIcon className='h-3 w-3' />
+          </a>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

ui/lib/utils/version.ts

@@ -0,0 +1,72 @@
+export interface ParsedVersion {
+  raw: string;
+  base: string;
+  parts: readonly number[];
+  commit: string | null;
+}
+
+export type StatusKind =
+  | 'unknown'
+  | 'outdated'
+  | 'ahead'
+  | 'commit-drift'
+  | 'current';
+
+export function parseVersion(
+  raw: string | undefined | null
+): ParsedVersion | null {
+  if (!raw) return null;
+  const trimmed = raw.trim().replace(/^v/i, '');
+  if (!trimmed) return null;
+  const [base, commitPart] = trimmed.split('+', 2);
+  const parts = (base ?? '')
+    .split('.')
+    .map((segment) => Number.parseInt(segment, 10))
+    .filter((value) => Number.isFinite(value));
+  if (parts.length === 0) return null;
+  return {
+    raw,
+    base: base ?? '',
+    parts,
+    commit: commitPart ?? null,
+  };
+}
+
+export function compareVersionParts(
+  a: readonly number[],
+  b: readonly number[]
+): number {
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+export function deriveStatus(
+  current: ParsedVersion | null,
+  latest: ParsedVersion | null
+): StatusKind {
+  if (!current || !latest) return 'unknown';
+  const cmp = compareVersionParts(current.parts, latest.parts);
+  if (cmp < 0) return 'outdated';
+  if (cmp > 0) return 'ahead';
+  return current.commit ? 'commit-drift' : 'current';
+}
+
+export function formatReleaseDate(iso: string | undefined): string | null {
+  if (!iso) return null;
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+export function formatVersionLabel(version: ParsedVersion | null): string {
+  if (!version) return 'unknown';
+  return version.raw.startsWith('v') ? version.raw : `v${version.raw}`;
+}

ui/next.config.ts

@@ -6,6 +6,9 @@ const nextConfig: NextConfig = {
   images: {
     unoptimized: true,
   },
+  turbopack: {
+    root: __dirname,
+  },
 };
 
 export default nextConfig;

ui/package.json

@@ -1,5 +1,6 @@
 {
   "name": "routstr-service",
+  "packageManager": "pnpm@10.15.0",
   "version": "0.1.0",
   "private": true,
   "scripts": {
@@ -88,5 +89,11 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "tailwindcss": "^4.2.0",
     "typescript": "^5.9.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "sharp",
+      "unrs-resolver"
+    ]
   }
 }