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

The broker name is otherwise derived from the project directory basename,
which means re-running `up` against a workspace that already has an agent
with that name fails the relaycast handshake with
`agent name '<name>' already exists`. The only existing workarounds were
to rename the project directory or rotate the workspace key.

Threads a `brokerName` option through `UpOptions`,
`CoreDependencies.createRelay`, `createDefaultRelay`, and
`createAgentRelayClient` into the SDK's `AgentRelayClient.spawn`, which
already supported it. Also forwards `--broker-name` from background
re-execs in `childUpArgsForDetachedStart` so programmatic callers (not
just CLI users whose argv is preserved verbatim) get the override.

Co-authored-by: Proactive Runtime Bot <agent@agent-relay.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

src/cli/commands/core.test.ts

@@ -205,6 +205,18 @@ describe('registerCoreCommands', () => {
     );
   });
 
+  it('up forwards --broker-name to createRelay', async () => {
+    const relay = createRelayMock({
+      getStatus: vi.fn(async () => ({ agent_count: 1, pending_delivery_count: 0 })),
+    });
+    const { program, deps } = createHarness({ relay });
+
+    const exitCode = await runCommand(program, ['up', '--port', '4999', '--broker-name', 'relayfile-dev']);
+
+    expect(exitCode).toBeUndefined();
+    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 5000, 'relayfile-dev');
+  });
+
   it('up starts broker and dashboard process', async () => {
     const relay = createRelayMock({
       getStatus: vi.fn(async () => ({ agent_count: 1, pending_delivery_count: 0 })),
@@ -214,7 +226,7 @@ describe('registerCoreCommands', () => {
     const exitCode = await runCommand(program, ['up', '--port', '4999']);
 
     expect(exitCode).toBeUndefined();
-    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 5000);
+    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 5000, undefined);
     expect(deps.spawnProcess).toHaveBeenCalledWith(
       '/usr/local/bin/relay-dashboard-server',
       expect.arrayContaining(['--port', '4999', '--relay-url', 'http://127.0.0.1:5000']),
@@ -236,7 +248,7 @@ describe('registerCoreCommands', () => {
     const exitCode = await runCommand(program, ['start', 'dashboard.js', 'claude', '--port', '4999']);
 
     expect(exitCode).toBeUndefined();
-    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 5000);
+    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 5000, undefined);
     expect(deps.spawnProcess).toHaveBeenCalledWith(
       '/usr/local/bin/relay-dashboard-server',
       expect.arrayContaining(['--port', '4999', '--relay-url', 'http://127.0.0.1:5000']),
@@ -445,7 +457,7 @@ describe('registerCoreCommands', () => {
     // Port probing happens before createRelay — only one broker is spawned
     expect(deps.createRelay).toHaveBeenCalledTimes(1);
     // API port = dashboard port (3888) + 1 = 3889
-    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 3889);
+    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 3889, undefined);
     expect(relay.getStatus).toHaveBeenCalledTimes(1);
   });
 
@@ -457,7 +469,7 @@ describe('registerCoreCommands', () => {
 
     expect(exitCode).toBeUndefined();
     expect(deps.createRelay).toHaveBeenCalledTimes(1);
-    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 3889);
+    expect(deps.createRelay).toHaveBeenCalledWith('/tmp/project', 3889, undefined);
     expect(relay.getStatus).toHaveBeenCalledTimes(1);
   });
 

src/cli/commands/core.ts

@@ -105,7 +105,7 @@ export interface CoreDependencies {
     missing: BridgeProject[];
   };
   getAgentOutboxTemplate: () => string;
-  createRelay: (cwd: string, apiPort?: number) => CoreRelay | Promise<CoreRelay>;
+  createRelay: (cwd: string, apiPort?: number, brokerName?: string) => CoreRelay | Promise<CoreRelay>;
   findDashboardBinary: () => string | null;
   spawnProcess: (command: string, args: string[], options?: Record<string, unknown>) => SpawnedProcess;
   execCommand: (command: string) => Promise<{ stdout: string; stderr: string }>;
@@ -245,7 +245,7 @@ function findDashboardBinaryDefault(fileSystem: CoreFileSystem): string | null {
   return null;
 }
 
-async function createDefaultRelay(cwd: string, apiPort = 0): Promise<CoreRelay> {
+async function createDefaultRelay(cwd: string, apiPort = 0, brokerName?: string): Promise<CoreRelay> {
   const binaryArgs: AgentRelayBrokerInitArgs = {};
   if (apiPort > 0) {
     binaryArgs.persist = true;
@@ -258,6 +258,7 @@ async function createDefaultRelay(cwd: string, apiPort = 0): Promise<CoreRelay>
   const client = await createAgentRelayClient({
     cwd,
     binaryArgs,
+    brokerName,
     preferConnect: apiPort > 0,
   });
 
@@ -415,6 +416,7 @@ export function registerCoreCommands(program: Command, overrides: Partial<CoreDe
     .option('--verbose', 'Enable verbose logging')
     .option('--workspace-key <key>', 'Use a pre-established Relaycast workspace key')
     .option('--state-dir <path>', 'Directory for broker state and connection files (default: .agent-relay/)')
+    .option('--broker-name <name>', 'Override the broker name (defaults to project directory basename)')
     .action(
       async (options: {
         dashboard?: boolean;
@@ -425,6 +427,7 @@ export function registerCoreCommands(program: Command, overrides: Partial<CoreDe
         verbose?: boolean;
         workspaceKey?: string;
         stateDir?: string;
+        brokerName?: string;
       }) => {
         await runUpCommand(options, deps);
       }

src/cli/lib/broker-lifecycle.ts

@@ -19,6 +19,7 @@ type UpOptions = {
   reuseExistingBroker?: boolean;
   workspaceKey?: string;
   stateDir?: string;
+  brokerName?: string;
 };
 
 type DownOptions = {
@@ -209,15 +210,16 @@ async function resolveApiPortWithFallback(
 async function startBrokerWithPortFallback(
   paths: CoreProjectPaths,
   dashboardPort: number,
-  deps: CoreDependencies
+  deps: CoreDependencies,
+  brokerName?: string
 ): Promise<{ relay: CoreRelay; apiPort: number }> {
   // Resolve a free API port BEFORE spawning the broker.  This avoids
   // spawning (and flocking) multiple --persist brokers during retry,
   // which caused stale-flock "already running" errors.
   const startApiPort = dashboardPort + 1;
   const apiPort = await resolveApiPortWithFallback(startApiPort, MAX_API_PORT_ATTEMPTS, deps);
 
-  const candidate = await deps.createRelay(paths.projectRoot, apiPort);
+  const candidate = await deps.createRelay(paths.projectRoot, apiPort, brokerName);
 
   await candidate.getStatus();
   return { relay: candidate, apiPort };
@@ -559,6 +561,9 @@ function childUpArgsForDetachedStart(options: UpOptions, deps: CoreDependencies)
   if (options.workspaceKey && !hasCliOption(args, '--workspace-key')) {
     args.push('--workspace-key', options.workspaceKey);
   }
+  if (options.brokerName && !hasCliOption(args, '--broker-name')) {
+    args.push('--broker-name', options.brokerName);
+  }
   if (options.verbose === true && !args.includes('--verbose')) {
     args.push('--verbose');
   }
@@ -1463,7 +1468,7 @@ export async function runUpCommand(options: UpOptions, deps: CoreDependencies):
     // files (e.g. user deleted .agent-relay/ while broker was running).
     await killOrphanedBrokerProcesses(paths.projectRoot, deps);
 
-    const started = await startBrokerWithPortFallback(paths, dashboardPort, deps);
+    const started = await startBrokerWithPortFallback(paths, dashboardPort, deps, options.brokerName);
     relay = started.relay;
     apiPort = started.apiPort;
     const dashboardRelayUrl = resolveDashboardRelayUrl(apiPort, deps);

src/cli/lib/client-factory.ts

@@ -5,6 +5,7 @@ export interface CreateAgentRelayClientOptions {
   channels?: string[];
   binaryPath?: string;
   binaryArgs?: AgentRelayBrokerInitArgs;
+  brokerName?: string;
   env?: NodeJS.ProcessEnv;
   preferConnect?: boolean;
 }
@@ -30,6 +31,7 @@ export async function createAgentRelayClient(
     channels = ['general'],
     binaryPath = process.env.AGENT_RELAY_BIN,
     binaryArgs,
+    brokerName,
     env = process.env,
     preferConnect = false,
   } = options;
@@ -45,6 +47,7 @@ export async function createAgentRelayClient(
   return AgentRelayClient.spawn({
     binaryPath: binaryPath || undefined,
     binaryArgs,
+    brokerName,
     channels,
     cwd,
     env: env as Record<string, string>,