Add explicit broker workspace join options

Author: kjgbot

.agentworkforce/trajectories/completed/2026-06/traj_1llfpjvd9m7k/summary.md

@@ -0,0 +1,39 @@
+# Trajectory: Review and fix PR 1055
+
+> **Status:** ✅ Completed
+> **Confidence:** 86%
+> **Started:** June 6, 2026 at 01:49 PM
+> **Completed:** June 6, 2026 at 02:05 PM
+
+---
+
+## Summary
+
+Reviewed PR 1055, removed accidental rust_out artifact, restored emptied trajectory data, and fixed CLI env-var test cleanup. Verified harness-driver typecheck/build and focused broker CLI/auth tests.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Removed accidental binary artifact and restored emptied trajectory
+
+- **Chose:** Removed accidental binary artifact and restored emptied trajectory
+- **Reasoning:** PR diff added rust_out and emptied an active tracked trajectory; AGENTS.md requires trajectories to remain tracked, and generated binaries do not belong in the PR.
+
+### Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop
+
+- **Chose:** Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop
+- **Reasoning:** The new tests cleared the shared env var before each test but leaked it after the final test, which can affect later tests in the same process.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Removed accidental binary artifact and restored emptied trajectory: Removed accidental binary artifact and restored emptied trajectory
+- Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop: Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop

.agentworkforce/trajectories/completed/2026-06/traj_1llfpjvd9m7k/trajectory.json

@@ -0,0 +1,65 @@
+{
+  "id": "traj_1llfpjvd9m7k",
+  "version": 1,
+  "task": {
+    "title": "Review and fix PR 1055"
+  },
+  "status": "completed",
+  "startedAt": "2026-06-06T13:49:15.971Z",
+  "completedAt": "2026-06-06T14:05:43.957Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-06-06T14:05:29.768Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_4iax8jv8u74r",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-06-06T14:05:29.768Z",
+      "endedAt": "2026-06-06T14:05:43.957Z",
+      "events": [
+        {
+          "ts": 1780754729769,
+          "type": "decision",
+          "content": "Removed accidental binary artifact and restored emptied trajectory: Removed accidental binary artifact and restored emptied trajectory",
+          "raw": {
+            "question": "Removed accidental binary artifact and restored emptied trajectory",
+            "chosen": "Removed accidental binary artifact and restored emptied trajectory",
+            "alternatives": [],
+            "reasoning": "PR diff added rust_out and emptied an active tracked trajectory; AGENTS.md requires trajectories to remain tracked, and generated binaries do not belong in the PR."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1780754730821,
+          "type": "decision",
+          "content": "Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop: Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop",
+          "raw": {
+            "question": "Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop",
+            "chosen": "Made CLI env-var test guard clear AGENT_RELAY_BROKER_NAME on drop",
+            "alternatives": [],
+            "reasoning": "The new tests cleared the shared env var before each test but leaked it after the final test, which can affect later tests in the same process."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Reviewed PR 1055, removed accidental rust_out artifact, restored emptied trajectory data, and fixed CLI env-var test cleanup. Verified harness-driver typecheck/build and focused broker CLI/auth tests.",
+    "approach": "Standard approach",
+    "confidence": 0.86
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "d5f7fee457c2d7a991bdb9167ad2c896aa0987e4",
+    "endRef": "d5f7fee457c2d7a991bdb9167ad2c896aa0987e4"
+  }
+}

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `agent-relay-broker` and `@agent-relay/harness-driver` accept explicit workspace keys and broker instance names, so local and cloud brokers can join the same Relay workspace with stable, addressable names.
 - `@agent-relay/harnesses` adds a `grok` PTY harness for the Grok CLI, including Relaycast MCP support for spawned agents.
 - `@agent-relay/harnesses` is now published to npm, so SDK consumers can install the prebuilt PTY harnesses and harness-authoring helpers.
 - `agent-relay drive` and `agent-relay passthrough` add adaptive predictive echo so typing stays responsive when driving a high-latency or remote agent, and stays invisible on fast local links.

crates/broker/src/cli/mod.rs

@@ -72,9 +72,9 @@ impl Commands {
         let pid = std::process::id();
         match self {
             Commands::Init(cmd) => {
-                let name = cmd.name.trim();
+                let name = cmd.resolved_instance_name(None);
                 if !name.is_empty() {
-                    return name.to_string();
+                    return name;
                 }
                 std::env::current_dir()
                     .ok()
@@ -215,9 +215,18 @@ pub(crate) struct McpArgsCommand {
 
 #[derive(Debug, clap::Args)]
 pub(crate) struct InitCommand {
-    #[arg(long, default_value = "")]
+    /// Legacy broker instance name flag. Prefer --instance-name.
+    #[arg(long, default_value = "", alias = "broker-name")]
     pub(crate) name: String,
 
+    /// Stable broker instance name within the Relay workspace.
+    #[arg(long = "instance-name")]
+    pub(crate) instance_name: Option<String>,
+
+    /// Join an existing Relay workspace instead of creating a fresh one.
+    #[arg(long = "workspace-key")]
+    pub(crate) workspace_key: Option<String>,
+
     #[arg(long, default_value = "general")]
     pub(crate) channels: String,
 
@@ -248,6 +257,135 @@ pub(crate) struct InitCommand {
     pub(crate) state_dir: Option<String>,
 }
 
+impl InitCommand {
+    pub(crate) fn resolved_instance_name(&self, fallback: Option<&str>) -> String {
+        fn non_empty_trimmed(value: &str) -> Option<String> {
+            let trimmed = value.trim();
+            if trimmed.is_empty() {
+                None
+            } else {
+                Some(trimmed.to_string())
+            }
+        }
+
+        self.instance_name
+            .as_deref()
+            .and_then(non_empty_trimmed)
+            .or_else(|| non_empty_trimmed(&self.name))
+            .or_else(|| {
+                std::env::var("AGENT_RELAY_BROKER_NAME")
+                    .ok()
+                    .and_then(|name| non_empty_trimmed(&name))
+            })
+            .or_else(|| fallback.and_then(non_empty_trimmed))
+            .unwrap_or_default()
+    }
+
+    pub(crate) fn resolved_workspace_key(&self) -> Option<String> {
+        self.workspace_key
+            .clone()
+            .or_else(|| std::env::var("AGENT_RELAY_WORKSPACE_KEY").ok())
+            .map(|key| key.trim().to_string())
+            .filter(|key| !key.is_empty())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+
+    static BROKER_NAME_ENV_MUTEX: Mutex<()> = Mutex::new(());
+
+    struct BrokerNameEnvGuard {
+        _guard: std::sync::MutexGuard<'static, ()>,
+    }
+
+    impl Drop for BrokerNameEnvGuard {
+        fn drop(&mut self) {
+            std::env::remove_var("AGENT_RELAY_BROKER_NAME");
+        }
+    }
+
+    fn broker_name_env_guard() -> BrokerNameEnvGuard {
+        let guard = BROKER_NAME_ENV_MUTEX.lock().unwrap();
+        std::env::remove_var("AGENT_RELAY_BROKER_NAME");
+        BrokerNameEnvGuard { _guard: guard }
+    }
+
+    fn init_command(name: &str, instance_name: Option<&str>) -> InitCommand {
+        InitCommand {
+            name: name.to_string(),
+            instance_name: instance_name.map(ToOwned::to_owned),
+            workspace_key: None,
+            channels: "general".to_string(),
+            api_port: 0,
+            api_bind: "127.0.0.1".to_string(),
+            persist: false,
+            state_dir: None,
+        }
+    }
+
+    #[test]
+    fn instance_name_flag_overrides_legacy_name_and_env() {
+        let _guard = broker_name_env_guard();
+        std::env::set_var("AGENT_RELAY_BROKER_NAME", "env-name");
+
+        let command = init_command("legacy-name", Some("instance-name"));
+
+        assert_eq!(
+            command.resolved_instance_name(Some("fallback")),
+            "instance-name"
+        );
+    }
+
+    #[test]
+    fn legacy_name_flag_overrides_env_default() {
+        let _guard = broker_name_env_guard();
+        std::env::set_var("AGENT_RELAY_BROKER_NAME", "env-name");
+
+        let command = init_command("legacy-name", None);
+
+        assert_eq!(
+            command.resolved_instance_name(Some("fallback")),
+            "legacy-name"
+        );
+    }
+
+    #[test]
+    fn env_broker_name_overrides_fallback_only() {
+        let _guard = broker_name_env_guard();
+        std::env::set_var("AGENT_RELAY_BROKER_NAME", "env-name");
+
+        let command = init_command("", None);
+
+        assert_eq!(command.resolved_instance_name(Some("fallback")), "env-name");
+    }
+
+    #[test]
+    fn blank_instance_name_falls_through_to_legacy_name() {
+        let _guard = broker_name_env_guard();
+        std::env::set_var("AGENT_RELAY_BROKER_NAME", "env-name");
+
+        let command = init_command("legacy-name", Some("   "));
+
+        assert_eq!(
+            command.resolved_instance_name(Some("fallback")),
+            "legacy-name"
+        );
+    }
+
+    #[test]
+    fn empty_instance_name_and_blank_env_fall_through_to_fallback() {
+        let _guard = broker_name_env_guard();
+        std::env::set_var("AGENT_RELAY_BROKER_NAME", "   ");
+
+        let command = init_command("", Some(""));
+
+        assert_eq!(command.resolved_instance_name(Some("fallback")), "fallback");
+    }
+}
+
 #[derive(Debug, clap::Args, Clone)]
 pub(crate) struct PtyCommand {
     pub(crate) cli: String,