fix(#4098): extend backoff gate to A2A agent-card HTTP errors

[aheritier]

🤖 Automated implementer agent — this comment was posted by the implementer bot from Docker Agentic Platform, not by a human developer

Extends the StartableToolSet backoff gate (#4062, #4074) to A2A agent-card resolution failures — the piece #4074 explicitly deferred because the agent-card resolver "didn't cleanly expose HTTP status." That deferral rationale turned out to be wrong: agentcard.Resolver.Resolve already returns *agentcard.ErrStatusNotOK{StatusCode, Status} on any non-200 response. enrichCardError (new pkg/tools/a2a/carderror.go) translates that into *modelerrors.StatusError, mirroring enrichConnectError's handling of remote MCP HTTP errors.

The one thing the resolver genuinely doesn't expose is the Retry-After header (it discards the *http.Response). retryAfterRecorder, a minimal http.RoundTripper installed only in front of the card-resolution GET, recovers it — it never reaches the JSON-RPC transport chain built afterwards.

Arming set (unchanged fixed enumeration from #4062/#4074): 429, 408, 500, 502, 503, 504, 529 — not a full 5xx range (501, 505, Cloudflare 520–527 excluded). Fails promptly, no pacing: DNS failures, connection refused, SSRF-blocked private-IP targets, malformed/unparsable agent cards, and other 4xx (bad auth/config). Only the startup agent-card fetch is paced — per-call SendStreamingMessage failures on an already-started toolset are not.

Changed files

File	Change
pkg/tools/a2a/carderror.go	New: retryAfterRecorder + enrichCardError
pkg/tools/a2a/a2a.go	Wire recorder + enrichCardError into Toolset.Start
pkg/tools/a2a/carderror_test.go	New: retryable/non-retryable status tables, no-status cases, Retry-After tests
pkg/tools/a2a/backoff_test.go	New: end-to-end StartableToolSet.TryStart gate tests (arm/block/reopen/recover)
docs/tools/a2a/index.md	New "Startup failure behaviour" section
docs/tools/rag/index.md	Cross-reference note now names A2A alongside remote MCP

Testing

task build && task test && task lint all pass (this sandbox lacked task/golangci-lint/gcc; installed task v3.53.1, golangci-lint v2.13.1 via go install, and gcc/build-essential via apt so pkg/rag/treesitter's CGO-gated tests run — CGO_ENABLED=1 was set for task test). Independent review (self-review pattern per #4062/#4074, aheritier identity) posted below.

Refs #4060, #4074, #4098

[aheritier]

Independent review — no blocking issues (CI verified green)

Reviewed head 8c64d794 against base fix/startable-toolset-backoff-mcp-lsp (three-dot diff, 6 files, +434/−6).

CI: all 20 live check-runs for this SHA succeeded (ci: build-and-test, lint, windows-tests, build-image ×2, license-check; CodeQL: Analyze go/actions/js; docs-lint/a11y/upstream). Note for anyone reading the PR body's "CI is green" with the stacked base: ci.yml/codeql.yml use an unfiltered pull_request: trigger, so Go checks run for feature-branch bases too — verified.

Local validation (throwaway checkout): go build ./..., go vet, go test -count=1 -race ./pkg/tools/a2a/ ./pkg/tools/ ./pkg/modelerrors/, golangci-lint run — all clean; -race -count=5 stable. Mutation check via go test -overlay: 4/4 mutants killed (no StatusError wrap; Retry-After dropped; recorder threshold >=500; wrong status forwarded) — the new tests are load-bearing.

#4098 acceptance criteria:

• Card-error origin identified: agentcard.Resolver.Resolve returns *ErrStatusNotOK{StatusCode} unwrapped; consumed structurally via errors.As (carderror.go:39-41) — no reliance on err.Error() text or the modelerrors regex fallback.
• Retryable statuses (429/408/500/502/503/504/529) → *modelerrors.StatusError (carderror.go:44-53, wired at a2a.go:198); fixed enumeration, 501 proven excluded.
• Non-HTTP failures (ctx cancel, DNS, conn-refused, SSRF-blocked, malformed 200 body) fall through unwrapped → fail fast; 4xx wrapped but non-retryable → fail fast (carderror_test.go:48-134, backoff_test.go:74-95).
• End-to-end gate tests through real tools.NewStartable(...).TryStart: arm → block → reopen (backoff_test.go:29-70) and recover to a working a2asrv handshake (:104-177).
• Retry-After honoured with a status-matched recorder (carderror.go:23-29, 48-51; tests carderror_test.go:141-184).

Parity with #4074: recorder is a local around a fresh *http.Client; JSON-RPC transport is rebuilt from the saved base (a2a.go:212), so the per-call SendStreamingMessage path is unchanged. docs/tools/rag/index.md overlap with #4074 is additive on top of #4074's own lines — rebase onto main after #4074 merges will be clean.

[optional] carderror.go:49 — the status == statusErr.StatusCode guard is defensive only (the resolver issues a single GET; redirect hops are <400 and never recorded), so that branch is unreachable/untested. Fine to keep.

Verdict: approve-equivalent. GitHub blocks self-approval for the PR author, so this is posted as a comment. Merge gating: retarget to main once #4074 lands rather than merging into the feature branch.