fix(v2): tell a caller when to come back on every failure meant to be retried - #6625

Three related gaps in retry signalling on the v2 surface, found auditing it against RFC 9110 / RFC 6585 and against how Stripe, GitHub and Google's AIPs handle the same problems. Builds on #6620.

What was wrong

1. No 503 carried Retry-After. Not one of them: the three route builders' unhandledErrorResponse, the execute and resume routes, and serviceFailureResponse. A client's only defensible policy on a bare 503 is an immediate retry — which is exactly the traffic a degraded dependency cannot absorb, and Sim raises 503 precisely when the API-key store, the rollout gate, the rate-limit backend, or execution-identity allocation is briefly unavailable.

2. A 429 that already knew its wait threw it away. This is the more interesting one. ADMISSION_ERROR_DESCRIPTOR declares retryAfterSeconds: 5 for RESERVATION_CONCURRENCY, but mapping a descriptor onto a PreprocessExecutionError copied only statusCode, code and retryable. A concurrency denial therefore reached the client as a bare 429 with no Retry-After — despite the policy layer having named the wait five seconds earlier, and despite the OpenAPI already documenting RateLimited.headers: ['Retry-After']. The 503 infrastructure denial had the same leak; the new default happened to mask it with the same number.

3. One 503 must not advise a retry at all. ASYNC_ENQUEUE_AMBIGUOUS means the enqueue may have succeeded — it deliberately retains its execution-ID claim because a job may already exist. Telling that caller to come back in 5s invites a client with no X-Run-Id to start, and bill, a second run of the same workflow.

What changed

• v2Error applies a Retry-After default keyed on the response status (not the v2 error code — Retry-After is defined against the status, and the status is the only half of the pair a client sees). A caller-supplied value still wins.
• retryAfterSeconds now travels descriptor → PreprocessExecutionError.retryAfterMs → ExecuteWorkflowServiceFailure.retryAfterMs → serviceFailureResponse. The transport reads a number the policy owns instead of re-guessing it; the v2Error default is now only the floor for paths with no policy signal.
• ASYNC_ENQUEUE_AMBIGUOUS opts out via omitRetryAfter and returns the run id so the caller reconciles rather than retries.
• Reuses ADMISSION_RETRY_AFTER_SECONDS rather than restating 5, so the execute route's capacity 429 and every other surface's 503 cannot drift apart.
• One central OpenAPI edit adds Retry-After to the shared ServiceUnavailable response — all 128 operations, 7 specs.

The audit

.agents/skills/v2-api-conventions/SKILL.md records the standards review so it is not re-litigated: the retry rule, the cursor-tamper-evidence invariants, and reasoned rejections of RFC 9457 problem+json, the IETF RateLimit-* draft fields, renaming X-RateLimit-* under RFC 6648, 422-for-semantic-validation, Location on 201, ETag / If-Match, and merge-patch+json — each with the spec text and the industry evidence.

Highlights of the "no" cases, since the evidence was not what I expected:

• RFC 6648 does not ask anyone to rename deployed X- headers. §1 item 4 "makes no recommendation as to whether existing 'X-' parameters ought to remain in use or be migrated", and Appendix B argues the migration is the interoperability harm. The rule is a SHOULD NOT binding creators of new parameters.
• The RateLimit-* draft is unpublished, was returned "Not ready" at HTTPDIR review, and is on its third mutually incompatible wire format. 0 of Stripe/GitHub/Google emit it.
• 0 of 3 use RFC 9457, and 9457 §4 itself steers APIs with an existing format toward keeping it.
• 0 of 3 do HTTP optimistic concurrency. Google does the semantics via a resource etag field (AIP-154), deliberately not If-Match.
• Retry-After is only a MAY on 429 and 503 — it is SHOULD on exactly one status, 413. So this PR is a deliberate improvement, not a conformance fix, and says so.

Deprecation/Sunset on v1 is left open: emitting either commits Sim to a retirement date, which is a product decision, not an engineering one.

Idempotency is assessed and deliberately not extended here. X-Run-Id already gives the money path at-most-once semantics via a durable claim, and the operation description already says it is not an idempotency key. A true Stripe-style Idempotency-Key needs a request fingerprint, a retention window, an in-flight-vs-completed split, and somewhere to store a large synchronous body — a designed piece of work, not an increment. Aliasing the header name without the replay semantics would be worse than leaving it, since clients written against Stripe would read our 409 as a hard failure.

Verification

• Every fix has a test proven to fail without it (reverted the source, watched it go red, restored).
• bun run type-check, check:api-validation, check:openapi (7 specs, 128 operations, 225 examples), biome on all changed files, and 1299 tests across the v2 / routes / execution / billing suites — all green.