Never map a Solana confirmation timeout to regenerate/pay-again (#109)

## Summary

Python mirror of agentscore/node-commerce#105. Fixes a live
double-charge on the Solana MPP rail.

pympp verifies a transaction-payload credential by broadcasting it
(funds move, a signature is minted) then awaiting confirmation in the
same synchronous verify() call, with a fixed timeout not exposed to
callers. Under load that window can expire before the network surfaces
confirmation, even on a healthy production RPC (verified: Helius
getHealth ok in ~70ms during the failure), so verify() raises on a
transfer that may already have landed. `_handle_mppx` mapped every
unclassified pympp failure to `payment_proof_invalid` +
`regenerate_payment_credential`, so the merchant told the agent to pay
again for money that already left the wallet. Observed live 2026-08-12
on the hosted stores: an on-chain balance delta with no service
delivered and a regenerate 402 in hand.

`classify_mppx_failure` now recognizes the confirmation-timeout reason
and returns `payment_pending_confirmation` (HTTP 504, `action:
check_settlement_before_retry`) with a message telling the buyer to
verify settlement before retrying. 504 rather than 402 is deliberate:
x402/MPP clients version-route on status and a 402 auto-triggers a
re-pay retry, which is the double-charge this guards. A confirmation
timeout cannot be reliably distinguished from never-landed, so the
response surfaces the ambiguity rather than asserting success or
failure.

## Type of change

- [x] Bug fix (no breaking change)
- [ ] New feature (no breaking change)
- [ ] Breaking change (existing callers must update)
- [ ] Docs, tests, or internal maintenance only

## Public API

No signature changes. Behavior change on one error path: a Solana MPP
settle whose confirmation times out now returns HTTP 504
`payment_pending_confirmation` instead of 402 `payment_proof_invalid` /
`regenerate_payment_credential`. Callers that branched on that 402 to
auto-repay should treat 504 as submitted-but-unconfirmed and not blindly
resubmit.

## Test plan

ruff check + format, ty clean, full suite 1844 passing. New tests: the
classifier returns 504 `payment_pending_confirmation` (never 402, never
`regenerate_payment_credential`) with a do-not-double-pay message on
both the plain and status-recovery-failed variants.

## Checklist

- [x] Tests cover the new behavior, and the suite passes locally
- [x] Lint, format, and type checks pass
- [x] Docs and README examples updated if the public surface changed
- [x] No secrets, credentials, or personal data in the diff or the tests

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/payment/mppx_failures.py

@@ -41,10 +41,46 @@ class ClassifiedMppxFailure:
 )
 
 
+# The dangerous one. pympp verifies a transaction-payload credential by
+# broadcasting it (funds move, a signature is minted) and then awaiting
+# confirmation in the same verify() call, with a fixed timeout not exposed to
+# callers. When confirmation times out (routine under load, since Solana status
+# propagation can lag the window even on a production RPC), verify() raises on a
+# transaction that MAY HAVE ALREADY LANDED. Left unclassified, that maps to the
+# generic payment_proof_invalid + regenerate_payment_credential, i.e. the
+# merchant tells the agent to pay AGAIN for money that already left the wallet
+# (observed live 2026-08-12: an on-chain balance delta with no service
+# delivered and a regenerate 402 in hand). A confirmation timeout cannot be
+# reliably told apart from never-landed, so the honest response is 504 with an
+# explicit do-not-blindly-resubmit instruction; 504 (unlike 402) does not
+# trigger an automatic re-pay retry in x402/MPP clients.
+_SOLANA_CONFIRMATION_TIMEOUT = ClassifiedMppxFailure(
+    code="payment_pending_confirmation",
+    status=504,
+    message=(
+        "Payment was submitted on-chain but its confirmation timed out. It may "
+        "have settled. Do NOT resubmit without checking first, or you risk "
+        "paying twice."
+    ),
+    next_steps={
+        "action": "check_settlement_before_retry",
+        "user_message": (
+            "Your payment was broadcast to the network but confirmation timed "
+            "out, so it is unconfirmed rather than failed. Check your wallet "
+            "balance and the recipient before retrying: if the balance "
+            "decreased, the payment likely landed and you should NOT pay again, "
+            "wait for the merchant to reconcile or contact support. Only "
+            "resubmit if the funds are still in your wallet."
+        ),
+    },
+    extra={"chain": "solana", "broadcast": True},
+)
+
+
 def classify_mppx_failure(reason: str | None) -> ClassifiedMppxFailure | None:
     """Classify a failure-reason string against known patterns.
 
-    Returns ``None`` when unrecognized — callers fall back to the generic
+    Returns ``None`` when unrecognized: callers fall back to the generic
     ``payment_proof_invalid`` envelope. The reason argument may be the raw
     ``Exception`` message, ``shortMessage`` from a viem-shaped error, or any
     string carrying the upstream description. Substring match, case-insensitive.
@@ -54,4 +90,8 @@ def classify_mppx_failure(reason: str | None) -> ClassifiedMppxFailure | None:
     lower = reason.lower()
     if "keychain validation failed" in lower or "keynotfound" in lower:
         return _TEMPO_KEY_NOT_REGISTERED
+    # A broadcast Solana transfer whose confirmation timed out: money may have
+    # moved, so this must never fall through to regenerate_payment_credential.
+    if "confirmation timeout" in lower or "confirmation timed out" in lower:
+        return _SOLANA_CONFIRMATION_TIMEOUT
     return None

tests/test_mppx_failures.py

@@ -37,3 +37,32 @@ def test_user_message_names_both_recovery_paths() -> None:
     msg = out.next_steps["user_message"]
     assert "tempo wallet login" in msg
     assert "Base" in msg or "Solana" in msg
+
+
+def test_solana_confirmation_timeout_is_pending_not_regenerate() -> None:
+    out = classify_mppx_failure("Transaction confirmation timeout")
+    assert out is not None
+    assert out.code == "payment_pending_confirmation"
+    # 504, not 402: a 402 would trigger x402 clients to auto-repay, the exact
+    # double-charge this guards.
+    assert out.status == 504
+    assert out.status != 402
+    assert out.next_steps["action"] != "regenerate_payment_credential"
+    assert out.next_steps["action"] == "check_settlement_before_retry"
+    assert out.extra["chain"] == "solana"
+    assert out.extra["broadcast"] is True
+
+
+def test_solana_confirmation_timeout_status_recovery_variant() -> None:
+    out = classify_mppx_failure("Transaction confirmation timeout (status recovery failed: RPC error)")
+    assert out is not None
+    assert out.code == "payment_pending_confirmation"
+
+
+def test_solana_confirmation_timeout_warns_against_double_pay() -> None:
+    out = classify_mppx_failure("Transaction confirmation timeout")
+    assert out is not None
+    msg = out.next_steps["user_message"].lower()
+    assert "confirmation timed out" in msg
+    assert "check your wallet balance" in msg
+    assert "not pay again" in msg or "only resubmit" in msg