fix(broker): cover overloaded mcp-args registration

[khaliqgant]

Summary

Stacked on #1730 to complete issue #1715 across both registration call sites:

• route mcp-args --register through the broker-owned bounded Relaycast registration retry helper;
• preserve takeover-safe registration and truthful terminal attempts: 3 diagnostics;
• correct the RelayFlow base proof for the pre-fix SDK’s omitted attempts marker.

Exact proof

• Base SHA: 4306bb29be696ec84a4e3844f86fdc4a91584407
  • outcome: bug
  • signature: spawn_503_not_retried_and_safe_fallback_missing
  • observed: 2 registration POSTs, unsafe PTY and safe task-exit spawn both fail closed.
• Head SHA: bde1d4257d7a95484f4e3bcb86f0e3eb95124022
  • outcome: fixed
  • signature: spawn_503_retried_and_safe_fallback_is_live
  • observed: 6 registration POSTs, 200/400 ms bounded retry schedule, unsafe PTY remains closed, safe headless task-exit fallback is live and cleaned up.

Validation

• cargo test -p agent-relay-broker --no-default-features: 1067 passed, 4 ignored.
• Veto diff review: PASS; code 95/100, security 95/100, secrets clean.

Closes #1715.

---

Note

Medium Risk
Changes Relaycast agent registration behavior for mcp-args --register (extra POST retries on typed overloads), reusing the same bounded helper as spawn rather than new ad-hoc logic.

Overview
Completes overload handling for #1715 by routing mcp-args --register through the same broker-owned retry_agent_registration helper used for worker spawns, instead of a single register_agent_token call.

Terminal failures now surface attempts: 3 when transient 503 overloads exhaust the bounded backoff. Unit coverage was flipped from “no replay on ambiguous 503” to three mock hits and matching diagnostics. The Unreleased changelog entry now calls out mcp-args --register alongside spawn retries.

The 1715-spawn-overload RelayFlow base arm no longer requires an attempts: marker, matching the pre-fix SDK omitting that field while still checking status, error code, and request id.

^{Reviewed by Cursor Bugbot for commit 94efb14. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 90742bbb-5aed-4c89-a4f6-9dea080971b1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[khaliqgant]

@codex review

Please independently review exact stacked head bde1d42 for issue #1715. Focus on both broker /api/spawn and Cloud RelayFlow mcp-args --register call sites, bounded retry semantics, takeover fallback, diagnostics, and exact base/head proof.

[khaliqgant]

@cursor review

Please independently review exact stacked head bde1d42 for issue #1715. Focus on mcp-args registration retry wiring, timeout/fallback safety, proof validity, and regressions.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T18:13:55.946536Z	94efb14	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

relay/crates/broker/src/relaycast/ws.rs

Lines 1563 to 1564 in 94efb14

	let retryable = registration_is_retryable(&error)
	|| is_transient_registration_api_error(&error);

Treat terminal takeover failures as fatal

When registration collides, register_agent_token enters the takeover path, whose 401/403, agent_not_found, and other terminal API failures are converted to RelaycastRegistrationError::Transport at lines 455-459. The SDK classifier used here considers transport errors retryable, so a rejected takeover now replays the entire create/conflict/lookup/takeover sequence three times; because with_registration_attempts only restamps Api errors, the resulting spawn and mcp-args diagnostic also omits the promised total attempt count. Preserve/classify takeover API failures as fatal while retaining retries for genuine registration transport failures.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Update the exact-head diagnostic proof for registration retries

Routing mcp-args --register through this helper changes a persistent 503 from one POST with attempts: 1 to three POSTs with attempts: 3, but tests/relayflows/cases/1673-relaycast-registration-diagnostics/run.mjs lines 147-153 still accepts the head only when requestCount === 1 and stderr contains attempts: 1. Consequently that compiled exact-head RelayFlow proof throws an unexpected-observation error at this head, and the new 1715 proof exercises only /api/spawn, not the Cloud mcp-args --register call site; update or replace the exact base/head proof alongside this behavior change.

Useful? React with 👍 / 👎.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 94efb14. Configure here.}