fix(broker): cover overloaded mcp-args registration

.agentworkforce/trajectories/completed/2026-09/traj_shd42liwvlpd.trace.json

@@ -0,0 +1,74 @@
+{
+  "version": "1.0.0",
+  "id": "2f7178f0-a2ba-4c9a-ad4a-7102fb547dbe",
+  "timestamp": "2026-09-10T18:07:12.764Z",
+  "trajectory": "traj_shd42liwvlpd",
+  "files": [
+    {
+      "path": "CHANGELOG.md",
+      "conversations": [
+        {
+          "contributor": {
+            "type": "ai"
+          },
+          "ranges": [
+            {
+              "start_line": 9,
+              "end_line": 15,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "path": "crates/broker/src/cli_mcp_args.rs",
+      "conversations": [
+        {
+          "contributor": {
+            "type": "ai"
+          },
+          "ranges": [
+            {
+              "start_line": 4,
+              "end_line": 11,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            },
+            {
+              "start_line": 172,
+              "end_line": 186,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            },
+            {
+              "start_line": 632,
+              "end_line": 638,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            },
+            {
+              "start_line": 670,
+              "end_line": 682,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "path": "tests/relayflows/cases/1715-spawn-overload/run.mjs",
+      "conversations": [
+        {
+          "contributor": {
+            "type": "ai"
+          },
+          "ranges": [
+            {
+              "start_line": 140,
+              "end_line": 159,
+              "revision": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

.agentworkforce/trajectories/completed/2026-09/traj_shd42liwvlpd/summary.md

@@ -0,0 +1,40 @@
+# Trajectory: Finish Relay PR #1730 overload retries and mcp-args proof
+
+> **Status:** ✅ Completed
+> **Task:** relay-1730-1715
+> **Confidence:** 90%
+> **Started:** September 10, 2026 at 08:01 PM
+> **Completed:** September 10, 2026 at 08:07 PM
+
+---
+
+## Summary
+
+Extended the broker-owned bounded Relaycast registration retry path to cli mcp-args --register, corrected the base proof marker contract, updated the changelog, and validated full broker tests plus exact base-red/head-green proof at bde1d4257d7a95484f4e3bcb86f0e3eb95124022.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Extended the broker-owned bounded registration retry helper into mcp-args --register
+- **Chose:** Extended the broker-owned bounded registration retry helper into mcp-args --register
+- **Reasoning:** The fresh Cloud proof showed the outer RelayFlow executor retried three times while each inner mcp-args registration reported attempts:1; the existing helper already owns typed 503 classification, bounded backoff, diagnostics, and takeover-safe registration.
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Extended the broker-owned bounded registration retry helper into mcp-args --register: Extended the broker-owned bounded registration retry helper into mcp-args --register
+- Broker spawn is green at head and red at base; Cloud mcp-args was a separate uncovered call site and now shares the same bounded retry path. Full broker tests pass.
+
+---
+
+## Artifacts
+
+**Commits:** bde1d4257
+**Files changed:** 3

.agentworkforce/trajectories/completed/2026-09/traj_shd42liwvlpd/trajectory.json

@@ -0,0 +1,76 @@
+{
+  "id": "traj_shd42liwvlpd",
+  "version": 1,
+  "task": {
+    "title": "Finish Relay PR #1730 overload retries and mcp-args proof",
+    "source": {
+      "system": "plain",
+      "id": "relay-1730-1715"
+    }
+  },
+  "status": "completed",
+  "startedAt": "2026-09-10T18:01:46.070Z",
+  "completedAt": "2026-09-10T18:07:12.675Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-09-10T18:05:54.505Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_j655wk1uhsl5",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-09-10T18:05:54.505Z",
+      "endedAt": "2026-09-10T18:07:12.675Z",
+      "events": [
+        {
+          "ts": 1789063554506,
+          "type": "decision",
+          "content": "Extended the broker-owned bounded registration retry helper into mcp-args --register: Extended the broker-owned bounded registration retry helper into mcp-args --register",
+          "raw": {
+            "question": "Extended the broker-owned bounded registration retry helper into mcp-args --register",
+            "chosen": "Extended the broker-owned bounded registration retry helper into mcp-args --register",
+            "alternatives": [],
+            "reasoning": "The fresh Cloud proof showed the outer RelayFlow executor retried three times while each inner mcp-args registration reported attempts:1; the existing helper already owns typed 503 classification, bounded backoff, diagnostics, and takeover-safe registration."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1789063556526,
+          "type": "reflection",
+          "content": "Broker spawn is green at head and red at base; Cloud mcp-args was a separate uncovered call site and now shares the same bounded retry path. Full broker tests pass.",
+          "raw": {
+            "confidence": 0.88
+          },
+          "significance": "high",
+          "tags": [
+            "confidence:0.88"
+          ]
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Extended the broker-owned bounded Relaycast registration retry path to cli mcp-args --register, corrected the base proof marker contract, updated the changelog, and validated full broker tests plus exact base-red/head-green proof at bde1d4257d7a95484f4e3bcb86f0e3eb95124022.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  },
+  "commits": [
+    "bde1d4257"
+  ],
+  "filesChanged": [
+    "CHANGELOG.md",
+    "crates/broker/src/cli_mcp_args.rs",
+    "tests/relayflows/cases/1715-spawn-overload/run.mjs"
+  ],
+  "projectId": "AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "be109f9f94e641d35a842024418440b8b0a7ae3d",
+    "endRef": "bde1d4257d7a95484f4e3bcb86f0e3eb95124022",
+    "traceId": "2f7178f0-a2ba-4c9a-ad4a-7102fb547dbe"
+  }
+}

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Broker worker spawns now retry transient Relaycast registration overloads and only fall back to local headless task-exit workers when Relaycast messaging is explicitly disabled.
+- Broker worker spawns and `mcp-args --register` now retry transient Relaycast registration overloads; spawns only fall back to local headless task-exit workers when Relaycast messaging is explicitly disabled.
 
 ## [11.10.4] - 2026-09-08
 

crates/broker/src/cli_mcp_args.rs

@@ -4,7 +4,8 @@ use std::{
 };
 
 use crate::relaycast::{
-    configure_agent_relay_mcp_with_token, RelaycastHttpClient, RelaycastRegistrationError,
+    configure_agent_relay_mcp_with_token, retry_agent_registration, RegRetryOutcome,
+    RelaycastHttpClient, RelaycastRegistrationError,
 };
 use anyhow::{anyhow, bail, Context, Result};
 use serde::{Deserialize, Serialize};
@@ -171,12 +172,15 @@ async fn register_agent_token_for_mcp_args_with_timeout(
 
     let agent_token = match tokio::time::timeout(
         timeout,
-        client.register_agent_token(agent_name, Some(&cli_lower)),
+        retry_agent_registration(&client, agent_name, Some(&cli_lower)),
     )
     .await
     {
         Ok(Ok(token)) => token,
-        Ok(Err(error)) => return Err(map_register_agent_token_error(error)),
+        Ok(Err(RegRetryOutcome::RetryableExhausted(error)))
+        | Ok(Err(RegRetryOutcome::Fatal(error))) => {
+            return Err(map_register_agent_token_error(error));
+        }
         Err(error) => bail!("register timed out after {timeout:?}: {error}"),
     };
 
@@ -628,7 +632,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn register_surfaces_terminal_sdk_diagnostics_without_replaying_an_unsafe_post() {
+    async fn register_retries_transient_overload_before_surface_terminal_diagnostics() {
         let _env = EnvGuard::all();
         std::env::remove_var("RELAY_API_KEY");
         std::env::remove_var("RELAY_BASE_URL");
@@ -666,14 +670,13 @@ mod tests {
             "registration_backend_overloaded",
             "deterministic registration failure",
             "request_id: mcp-args-374",
-            "attempts: 1",
+            "attempts: 3",
         ] {
             assert!(message.contains(marker), "missing {marker}: {message}");
         }
-        // Registration is an unkeyed POST. Retrying an ambiguous 503 could
-        // duplicate a committed agent registration, so the SDK must not replay
-        // it even when the server advertised Retry-After.
-        register_mock.assert_hits(1);
+        // The broker-owned retry budget handles the typed transient overload;
+        // the terminal diagnostic must report the total broker attempts.
+        register_mock.assert_hits(3);
     }
 
     #[tokio::test]

tests/relayflows/cases/1715-spawn-overload/run.mjs

@@ -140,18 +140,20 @@ try {
   }, 'safe task-exit cleanup');
   const registrationTimestamps = [...relay.workerRegistrationTimestamps];
   const retryScheduleBounded = retryScheduleIsBounded(registrationTimestamps);
-  const markers = (text, attempts) =>
+  // The pre-fix SDK reports one POST by omission (no attempts marker), while
+  // the broker-owned retry path restamps the terminal detail with the total.
+  const markers = (text, attempts, requireAttempts = true) =>
     text.includes(`(${ERROR_STATUS})`) &&
     text.includes(ERROR_CODE) &&
     text.includes(REQUEST_ID) &&
-    text.includes(`attempts: ${attempts}`);
+    (!requireAttempts || text.includes(`attempts: ${attempts}`));
 
   const baseObserved =
     arm === 'base' &&
     unsafe.status === 500 &&
     safe.status === 500 &&
-    markers(unsafeError, 1) &&
-    markers(typeof safe.body?.error === 'string' ? safe.body.error : '', 1) &&
+    markers(unsafeError, 1, false) &&
+    markers(typeof safe.body?.error === 'string' ? safe.body.error : '', 1, false) &&
     unsafeNoWorker === true &&
     safeNoWorker === true &&
     safeTaskExitCleaned === true &&