fix(gateway): settlement_failed session status + safe retry/cancel for stuck commits

[LamaSu]

Problem

#242 (merged) made POST /api/negotiate/session/:id/commit fail loud with 502 { error: "settlement_failed" } when REAL-settlement wiring fails to mint an on-chain escrow — closing the false-200 hole. But it deliberately left the session status="committed" so the shared liveness gate would 409-block a /commit retry (its only guard against a second createJobFromSession deploying a duplicate on-chain escrow).

The side effect: a failed-commit session is stuck — a retry 409s, and there is no cancel/retry path. This PR closes that gap (a fast-follow, not a prod blocker; the baseline loop works without it).

What this does

Adds a first-class, recoverable settlement_failed SessionStatus and a guarded recovery path that never risks a duplicate on-chain escrow.

• packages/spec/src/types/negotiation.ts — add settlement_failed to SessionStatus. The DB status column is free TEXT (no CHECK/enum) → no migration. The A2A status switch has a default, so the union addition is backward-compatible.
• packages/gateway/src/routes/session-liveness.ts — assertSessionLive() now returns 409 on settlement_failed too. This preserves fix(gateway): /commit fails loud (502) when real settlement wiring fails instead of a false 200 (SWALLOW) #242's double-escrow block: /commit, /quote, /review, and the A2A commit path all still refuse a settlement_failed session, so a naive /commit retry can never blind-mint. Recovery is out-of-band only.
• packages/gateway/src/routes/negotiation.ts
  • On a real-settlement commit failure, transition committed → settlement_failed (instead of silently leaving it committed), stamping a machine-readable failure class into the transition:
    • settlement_failed:preflight_no_escrow — gateway key unset, so createJobFromSession threw at its first line before any on-chain call → provably no escrow → safe to re-mint.
    • settlement_failed:onchain_maybe_minted — any other failure → an escrow may have minted before the throw → fail closed.
    • The 502 body is unchanged (error/message/sessionId/jobId).
  • New POST /api/negotiate/session/:id/retry-settlement — money-path order of operations, fail-closed at every ambiguity:
    1. Escrow already recorded (session escrowAddress, or escrows.findByCwm(cwmId), real 0x… not mock-…) → RESUME from it, transition to committed, never re-mint.
    2. No recorded escrow + REAL mode + not provably pre-flight → 409 settlement_unrecoverable_ambiguous (a duplicate escrow outranks a stuck session).
    3. Safe (pre-flight real failure, or mock mode) → re-run the wiring; a repeat failure re-stamps settlement_failed and never double-mints.
  • DELETE already cancels any non-committed session, so it cleanly closes a settlement_failed one (clarifying comment added: cancel closes the negotiation record only; no claim to refund/rescind an escrow).

Safety rationale (money-path)

The on-chain escrow is minted inside withSignerLock before any DB write, so a throw in that window can leave an on-chain escrow with no DB trace. The retry therefore (a) resumes from any recorded escrow rather than minting, and (b) only blind-mints when the prior failure was provably pre-flight (gateway key unset ⇒ threw before the first chain call). Everything else fails closed.

Tests (green on Spark)

New packages/gateway/src/__tests__/settlement-failed-recovery.test.ts (9 tests) in a non-CI-excluded file (per #322, paid-job-flow.test.ts / settlement.test.ts are excluded):

• real commit failure → session settlement_failed, 502 body unchanged;
• naive /commit on settlement_failed → 409;
• retry resumes from an escrow recorded by cwmId / on the session row → no second escrow;
• retry fails closed on ambiguous failure with no recorded escrow;
• retry re-mints exactly once when provably pre-flight (config fixed);
• a still-broken real retry re-fails safely, never mints;
• DELETE cancels a settlement_failed session cleanly.

Escrow-count assertions measure the delta (the seed pre-populates escrows) so "no double-mint" is verified precisely.

Also updated negotiation-commit-fail-loud.test.ts (#242's suite): the real-failure session now asserts settlement_failed, and a naive /commit retry is still 409-blocked (double-escrow guard preserved).

Out of scope (untouched): SEAM-1/SEAM-2 files, the #233 gate, and the CI-suite exclusions. This branch changes exactly 5 files: the two test files + negotiation.ts + session-liveness.ts + spec/negotiation.ts.

🤖 Generated with Claude Code