feat(cli): add --broker-name override to agent-relay up

[khaliqgant]

Summary

• Adds a --broker-name <name> flag to agent-relay up that overrides the broker/agent name (otherwise derived from the project directory basename).
• Threads the option through UpOptions → CoreDependencies.createRelay → createDefaultRelay → createAgentRelayClient → AgentRelayClient.spawn (the SDK already accepted brokerName).
• Forwards --broker-name in childUpArgsForDetachedStart so programmatic background callers — not just CLI users whose argv is preserved verbatim — see the override on the detached re-exec.

Why

Re-running agent-relay up --workspace-key ... against a workspace that already has an agent with the project's basename fails the relaycast handshake with agent name '<name>' already exists. The previous workarounds were renaming the project directory or rotating the workspace key — both heavy-handed. This gives a per-invocation override.

Repro before:

$ agent-relay up --background --workspace-key rk_live_...
Broker background start did not become ready within 10s (pid: 23620).
# broker exited with: failed registering agent with env workspace key
#   agent name 'relayfile' already exists

After:

$ agent-relay up --foreground --workspace-key rk_live_... --broker-name relayfile-dev
Relay API: http://127.0.0.1:3889
Project: /Users/khaliqgant/Projects/AgentWorkforce/relayfile
Mode: broker (stdio)
Workspace Key: rk_live_...
Broker started.

Test plan

• npx vitest run src/cli/commands/core.test.ts -t "up" — 33 passed, includes a new positive test asserting --broker-name relayfile-dev is forwarded to createRelay.
• Local build + live run against a real workspace key registers as the chosen name and the dashboard comes up.
• CI green.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a --broker-name CLI option to the agent-relay up command. This option is threaded through broker lifecycle startup and relay client creation, with updated type signatures and test coverage to verify the end-to-end flow.

Changes

Broker name CLI option and propagation

Layer / File(s)	Summary
CLI command option and types src/cli/commands/core.ts	The up command adds a --broker-name <name> option; the action's options type is extended to include brokerName for propagation to runUpCommand.
Options and interface contracts src/cli/lib/broker-lifecycle.ts, src/cli/commands/core.ts, src/cli/lib/client-factory.ts	UpOptions, CoreDependencies.createRelay, and CreateAgentRelayClientOptions now include optional brokerName fields to carry the option through the stack.
Broker startup and option propagation src/cli/lib/broker-lifecycle.ts	startBrokerWithPortFallback accepts brokerName and forwards it into createRelay; detached broker startup constructs CLI arguments including --broker-name when provided; runUpCommand passes options.brokerName through.
Relay client creation and broker name forwarding src/cli/commands/core.ts, src/cli/lib/client-factory.ts	createDefaultRelay accepts brokerName and forwards it to createAgentRelayClient; createAgentRelayClient destructures brokerName and passes it to AgentRelayClient.spawn call options.
Test coverage for broker name option src/cli/commands/core.test.ts	New test verifies up --broker-name <name> passes the broker name to deps.createRelay as the third argument; existing tests updated to expect undefined as the third argument when --broker-name is not supplied.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• willwashburn
• barryollama

Poem

🐰 A flag hops through the CLI,
Broker name spreads far and wide,
From command down to relay's side,
Tests confirm the happy ride,
Relays smile with branded pride! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a --broker-name flag to the agent-relay up command, which is the primary feature introduced in this changeset.
Description check	✅ Passed	The description includes a comprehensive Summary section explaining what the PR does and why, detailed Test Plan with completed manual testing and passing unit tests, and follows the template structure with all required sections completed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/up-broker-name-flag

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/cli/commands/core.test.ts (1)

208-218: ⚡ Quick win

Add a detached-mode assertion for --broker-name forwarding.

This new test covers stdio startup forwarding, but not the background/detached re-exec path. Please add (or extend an existing detached test) to assert deps.spawnProcess includes --broker-name <name>.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/commands/core.test.ts` around lines 208 - 218, The
detached/background re-exec path test is missing an assertion that the
broker-name flag is forwarded; update the detached-mode test (the one that uses
createHarness and inspects deps.spawnProcess) to assert that deps.spawnProcess
was called with arguments containing '--broker-name' and the name
'relayfile-dev' (e.g., check the spawnProcess call args include '--broker-name',
'relayfile-dev') so the re-exec invocation forwards the flag just like the
direct createRelay path tested by runCommand/createRelayMock.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/cli/commands/core.test.ts`:
- Around line 208-218: The detached/background re-exec path test is missing an
assertion that the broker-name flag is forwarded; update the detached-mode test
(the one that uses createHarness and inspects deps.spawnProcess) to assert that
deps.spawnProcess was called with arguments containing '--broker-name' and the
name 'relayfile-dev' (e.g., check the spawnProcess call args include
'--broker-name', 'relayfile-dev') so the re-exec invocation forwards the flag
just like the direct createRelay path tested by runCommand/createRelayMock.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f72e929-1c68-4cb7-b436-45ecc9f79813

📥 Commits

Reviewing files that changed from the base of the PR and between 9812d38 and 2966bde.

📒 Files selected for processing (4)

• src/cli/commands/core.test.ts
• src/cli/commands/core.ts
• src/cli/lib/broker-lifecycle.ts
• src/cli/lib/client-factory.ts

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.