Add deadline-aware x402 settlement for upto sessions

[adambalogh]

Summary

Implements deadline-aware settlement for x402 upto sessions to fix three silent failure modes in og-x402's stock middleware that cause revenue loss:

1. Sessions outliving their Permit2 deadline (permit expires before settlement completes)
2. Async facilitator jobs treated as settled at enqueue time (202 Accepted) rather than confirmed on-chain
3. Sessions refusing cost after response streams, becoming permanently un-exhaustible

Key Changes

• New module x402_settlement.py: Provides deadline-aware session management and settlement lifecycle

  • DeadlineAwareSessionStore: Extends og-x402's SessionStore to:
    • Track Permit2 deadlines per session
    • Hide sessions from serving paths before deadline becomes unsettleable (clients get 402 and sign fresh permit)
    • Saturate spend cap instead of refusing cost, so exhausted sessions settle promptly
    • Track in-flight facilitator settlement job IDs
  • install_deadline_aware_settlement(): Monkey-patches PaymentMiddleware to:
    • Settle sessions before their permit deadline (not just when idle/exhausted)
    • Poll facilitator async jobs to terminal state before closing sessions
    • Re-drive settlement when jobs fail (if time permits) or abandon with critical logging if deadline passed
    • Clean up idle sessions with zero cost (no settlement needed)

• Updated __main__.py:

  • Replaces default SessionStore with DeadlineAwareSessionStore
  • Calls install_deadline_aware_settlement() during middleware initialization
  • Passes X402_SESSION_MAX_TIMEOUT_SECONDS to session creation

• Updated definitions.py:

  • Adds X402_SESSION_MAX_TIMEOUT_SECONDS constant (permit lifetime in seconds)
  • Documents relationship to SERVE_MARGIN_SECONDS and SETTLE_MARGIN_SECONDS

• New test module test_x402_settlement.py:

  • 20+ tests covering store behavior (deadline tracking, cost saturation, session hiding)
  • Settlement lifecycle tests (async job success/failure, deadline hopelessness, sync transactions)

Implementation Details

• Uses configurable margins (SERVE_MARGIN_SECONDS=420s, SETTLE_MARGIN_SECONDS=120s) to provide buffer for reaper cadence, facilitator queue latency, and on-chain confirmation
• Polls facilitator jobs with per-cycle budget (JOB_POLL_BUDGET_SECONDS=30s) to avoid blocking the reaper; resumes next cycle if budget exhausted
• Abandons sessions with critical logging when deadline becomes hopeless (DEADLINE_HOPELESS_SECONDS=30s) to surface revenue loss
• Follows existing monkey-patch pattern in __main__.py to avoid forking og-x402 (pinned dependency)
• Thread-safe session bookkeeping (deadlines, job IDs) using existing SessionStore._lock

https://claude.ai/code/session_01CbDr9d3YxeSjdwJQUzjuEC