@team-agent/installer 0.3.17 → 0.3.19

package/Cargo.lock

@@ -566,7 +566,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.3.17"
+version = "0.3.19"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.3.17"
+version = "0.3.19"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/emit.rs

@@ -32,9 +32,10 @@ pub fn run(argv: &[String], cwd: &Path) -> ExitCode {
         return emit_missing_subcommand_usage();
     };
     if command == "codex" || command == "claude" || command == "copilot" {
-        return cmd_leader_passthrough(command, &argv[1..], cwd)
-            .map(emit_result)
-            .unwrap_or(ExitCode::Error);
+        return match cmd_leader_passthrough(command, &argv[1..], cwd) {
+            Ok(result) => emit_result(result),
+            Err(error) => emit_cli_error(command, &argv[1..], cwd, &error),
+        };
     }
     if matches!(command, "-h" | "--help" | "help") {
         println!("{}", command_help(None));

package/crates/team-agent/src/cli/leader.rs

@@ -23,7 +23,14 @@ pub fn leader_launcher_args(values: &[String]) -> Result<LeaderLauncherArgs, Cli
     while idx < values.len() {
         let token = &values[idx];
         if token == "--" {
-            out.provider_args.extend(values.iter().skip(idx).cloned());
+            for value in values.iter().skip(idx + 1) {
+                if is_leader_launcher_flag(value) {
+                    return Err(CliError::Runtime(format!(
+                        "Team Agent launcher flag {value} must appear before --"
+                    )));
+                }
+            }
+            out.provider_args.extend(values.iter().skip(idx + 1).cloned());
             break;
         } else if token == "--attach" || token == "--attach-existing" {
             out.attach_existing = true;
@@ -49,6 +56,13 @@ pub fn leader_launcher_args(values: &[String]) -> Result<LeaderLauncherArgs, Cli
     Ok(out)
 }
 
+fn is_leader_launcher_flag(value: &str) -> bool {
+    matches!(
+        value,
+        "--external-leader" | "--attach" | "--attach-existing" | "--confirm" | "--attach-session"
+    ) || value.starts_with("--attach-session=")
+}
+
 fn leader_launcher_json(values: &[String]) -> bool {
     values
         .iter()

package/crates/team-agent/src/cli/mod.rs

@@ -363,10 +363,7 @@ pub mod lifecycle_port {
     }
 
     fn state_uses_external_leader(state: &Value) -> bool {
-        state
-            .get("is_external_leader")
-            .and_then(Value::as_bool)
-            .unwrap_or(true)
+        crate::state::projection::state_is_external_leader(state)
     }
 
     fn managed_leader_socket_cleanup(
@@ -1722,9 +1719,31 @@ pub mod lifecycle_port {
             open_display,
             team,
         ) {
-            Ok(report) => {
-                Ok(json!({"ok": true, "agent_id": agent, "report": format!("{report:?}")}))
-            }
+            Ok(crate::lifecycle::ResetAgentOutcome::Reset {
+                env,
+                start_mode,
+                discarded_session_id,
+                session_id,
+                new_session_id,
+            }) => Ok(json!({
+                "ok": true,
+                "agent_id": env.agent_id.as_str(),
+                "status": "reset",
+                "state_file": env.state_file.to_string_lossy().to_string(),
+                "coordinator_started": env.coordinator_started,
+                "start_mode": start_mode,
+                "discarded_session_id": discarded_session_id.as_ref().map(|id| id.as_str()),
+                "session_id": session_id.as_ref().map(|id| id.as_str()),
+                "new_session_id": new_session_id.as_ref().map(|id| id.as_str()),
+            })),
+            Ok(crate::lifecycle::ResetAgentOutcome::Refused { reason }) => Ok(json!({
+                "ok": false,
+                "agent_id": agent,
+                "status": "refused",
+                "reason": match reason {
+                    crate::lifecycle::ResetRefusal::DiscardSessionRequired => "discard_session_required",
+                },
+            })),
             Err(e) => Ok(error_value(e)),
         }
     }

package/crates/team-agent/src/cli/status_port.rs

@@ -48,10 +48,7 @@ use rusqlite::params;
             .cloned()
             .unwrap_or_else(|| json!({}));
         let session_name = state.get("session_name").cloned().unwrap_or(Value::Null);
-        let is_external_leader = state
-            .get("is_external_leader")
-            .and_then(Value::as_bool)
-            .unwrap_or(true);
+        let is_external_leader = crate::state::projection::state_is_external_leader(state);
         let leader_topology = if is_external_leader { "external" } else { "managed" };
         let leader_attach_command = if is_external_leader {
             None
@@ -573,8 +570,8 @@ use rusqlite::params;
         json!({
             "team": full.get("team").cloned().unwrap_or(Value::Null),
             "session_name": full.get("session_name").cloned().unwrap_or(Value::Null),
-            "leader_topology": full.get("leader_topology").cloned().unwrap_or_else(|| json!("external")),
-            "is_external_leader": full.get("is_external_leader").cloned().unwrap_or(Value::Bool(true)),
+            "leader_topology": full.get("leader_topology").cloned().unwrap_or_else(|| json!("managed")),
+            "is_external_leader": full.get("is_external_leader").cloned().unwrap_or(Value::Bool(false)),
             "leader_attach_command": full.get("leader_attach_command").cloned().unwrap_or(Value::Null),
             "leader_client": full.get("leader_client").cloned().unwrap_or(Value::Null),
             "tmux_session_present": full.get("tmux_session_present").cloned().unwrap_or(Value::Bool(false)),

package/crates/team-agent/src/cli/tests/base.rs

@@ -86,17 +86,18 @@ use super::*;
         assert!(!got.attach_existing);
         assert_eq!(
             got.provider_args,
-            vec!["--".to_string(), "--model".to_string(), "opus".to_string()]
+            vec!["--model".to_string(), "opus".to_string()]
         );
     }
 
     #[test]
-    fn leader_launcher_args_external_leader_after_dashdash_is_provider_arg() {
-        let got = leader_launcher_args(&["--".into(), "--external-leader".into()]).unwrap();
-        assert!(!got.external_leader);
-        assert_eq!(
-            got.provider_args,
-            vec!["--".to_string(), "--external-leader".to_string()]
+    fn leader_launcher_args_external_leader_after_dashdash_errors() {
+        let err = leader_launcher_args(&["--".into(), "--external-leader".into()])
+            .expect_err("Team Agent flags after -- must not be silently passed to provider");
+        assert!(
+            err.to_string()
+                .contains("Team Agent launcher flag --external-leader must appear before --"),
+            "unexpected error: {err}"
         );
     }
 
@@ -116,22 +117,22 @@ use super::*;
     }
 
     #[test]
-    fn leader_launcher_args_dashdash_passthrough_includes_following_flags() {
-        // golden: ["--attach","--","-x","--confirm"] ->
-        //   provider_args=["--","-x","--confirm"], attach_existing=True, confirm_attach=False
-        // (everything from `--` onward, INCLUDING the `--` token itself, is provider passthrough)
+    fn leader_launcher_args_dashdash_passthrough_strips_separator() {
+        // ["--attach","--","-x","--provider-confirm"] ->
+        //   provider_args=["-x","--provider-confirm"], attach_existing=True, confirm_attach=False
+        // Known Team Agent launcher flags after `--` are rejected by a separate guard.
         let got = leader_launcher_args(&[
             "--attach".into(),
             "--".into(),
             "-x".into(),
-            "--confirm".into(),
+            "--provider-confirm".into(),
         ])
         .unwrap();
         assert!(got.attach_existing);
-        assert!(!got.confirm_attach, "--confirm AFTER -- must NOT set confirm_attach");
+        assert!(!got.confirm_attach);
         assert_eq!(
             got.provider_args,
-            vec!["--".to_string(), "-x".to_string(), "--confirm".to_string()]
+            vec!["-x".to_string(), "--provider-confirm".to_string()]
         );
     }
 

package/crates/team-agent/src/cli/tests/shutdown_kill_plan.rs

@@ -309,6 +309,7 @@ fn lsof_cwd_timeout_is_diagnostic_not_shutdown_partial() {
         &ws,
         &json!({
             "session_name": "team-lsof-cwd-timeout",
+            "is_external_leader": true,
             "agents": {
                 "fake_impl": {
                     "status": "running",
@@ -467,6 +468,7 @@ fn leader_env_tmux_socket_never_kills_server_even_when_sessions_look_exclusive()
     crate::state::persist::save_runtime_state(
         &ws,
         &json!({
+            "is_external_leader": true,
             "tmux_socket_source": "leader_env",
             "agents": {
                 "fake_impl": {
@@ -543,3 +545,42 @@ fn managed_leader_shutdown_never_kills_server_even_when_socket_looks_exclusive()
         "managed topology must clear the team session/window without kill-server"
     );
 }
+
+#[test]
+fn shutdown_missing_topology_marker_defaults_to_managed_cleanup() {
+    let ws = tmp_shutdown_workspace("missing-topology-marker-managed-cleanup");
+    crate::state::persist::save_runtime_state(
+        &ws,
+        &json!({
+            "session_name": "team-current",
+            "agents": {}
+        }),
+    )
+    .unwrap();
+    let transport = CleanShutdownTransport::new()
+        .with_targets(vec![PaneInfo {
+            pane_id: PaneId::new("%1"),
+            session: SessionName::new("team-current"),
+            window_index: Some(0),
+            window_name: Some(WindowName::new("leader")),
+            pane_index: Some(0),
+            tty: None,
+            current_command: Some("codex".to_string()),
+            current_path: None,
+            active: true,
+            pane_pid: None,
+            leader_env: BTreeMap::new(),
+        }])
+        .with_targets_persist_after_kill();
+
+    let out = crate::cli::lifecycle_port::shutdown_with_transport(&ws, true, None, &transport)
+        .expect("shutdown should complete");
+
+    assert_eq!(out["ok"], json!(true));
+    assert_eq!(out["killed_sessions"], json!(["team-current"]));
+    assert_eq!(out["spared_sessions"], json!([]));
+    assert!(
+        !transport.kill_server_called(),
+        "missing topology marker must default to managed cleanup, not external kill-server"
+    );
+}

package/crates/team-agent/src/cli/tests/status_send.rs

@@ -86,6 +86,27 @@ use super::*;
         let _ = std::fs::remove_dir_all(&ws);
     }
 
+    #[test]
+    fn status_port_missing_topology_marker_defaults_to_managed() {
+        let ws = seed_status_workspace();
+        let mut state = crate::state::persist::load_runtime_state(&ws).unwrap();
+        if let Some(obj) = state.as_object_mut() {
+            obj.remove("is_external_leader");
+            obj.insert("session_name".to_string(), json!("team-current"));
+        }
+        crate::state::persist::save_runtime_state(&ws, &state).unwrap();
+
+        let v = status_port::status(&ws, /*compact=*/ true, /*detail=*/ false).expect("status");
+
+        assert_eq!(v["leader_topology"], json!("managed"));
+        assert_eq!(v["is_external_leader"], json!(false));
+        let attach = v["leader_attach_command"]
+            .as_str()
+            .expect("missing marker defaults to managed attach command");
+        assert!(attach.contains("attach -t team-current:leader"), "{attach}");
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
     #[test]
     fn status_port_status_detail_full_keeps_uncompacted_events() {
         // cmd_status --json --detail -> status_port::status(compact=false): the FULL dict
@@ -394,6 +415,48 @@ fn run_send_unknown_task_renders_error_not_silent_swallow() {
     let _ = std::fs::remove_dir_all(&ws);
 }
 
+#[test]
+fn run_leader_passthrough_flag_after_dashdash_renders_error_not_silent_swallow() {
+    let ws = std::env::temp_dir().join(format!(
+        "ta-run-leaderflag-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    ));
+    std::fs::create_dir_all(&ws).unwrap();
+    let argv: Vec<String> = ["codex", "--", "--external-leader"]
+        .iter()
+        .map(ToString::to_string)
+        .collect();
+
+    let code = run(&argv, &ws);
+
+    assert_eq!(
+        code,
+        ExitCode::Error,
+        "misplaced leader flag must fail before provider exec"
+    );
+    let logs_dir = ws.join(".team").join("logs");
+    let mut found = String::new();
+    if let Ok(entries) = std::fs::read_dir(&logs_dir) {
+        for entry in entries.flatten() {
+            let name = entry.file_name().to_string_lossy().to_string();
+            if name.starts_with("cli-error-") {
+                found = std::fs::read_to_string(entry.path()).unwrap_or_default();
+                break;
+            }
+        }
+    }
+    assert!(
+        found.contains("Team Agent launcher flag --external-leader must appear before --"),
+        "leader passthrough run() must render the misplaced flag error; a silent swallow leaves no \
+         cli-error log. got log body: {found:?}"
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
 // R8 D6 (c-lite offline byte-lock): the CLI requeued_exhausted_watchers return projection, extracted
 // into a pure helper, must project the golden event's watcher_ids STRING list (leader/__init__.py:56) —
 // NOT the Rust `requeued` Vec<WatcherNotice> objects.

package/crates/team-agent/src/cli/types.rs

@@ -101,6 +101,12 @@ impl CliError {
                         .to_string(),
                 ]);
             }
+        } else if error.contains("Team Agent launcher flag")
+            && error.contains("must appear before --")
+        {
+            payload.action = String::from(
+                "move the Team Agent launcher flag before `--`; only provider flags belong after `--`",
+            );
         }
         payload
     }

package/crates/team-agent/src/leader/lease.rs

@@ -144,6 +144,7 @@ fn attach_leader_targets(workspace: &Path, state: &Value) -> Vec<AttachLeaderTar
     let mut targets = Vec::new();
     for endpoint in state_recorded_tmux_endpoints(state) {
         let backend = tmux_backend_for_endpoint(&endpoint);
+        let resolved_endpoint = backend.tmux_endpoint();
         targets.extend(
             backend
                 .list_targets()
@@ -151,7 +152,7 @@ fn attach_leader_targets(workspace: &Path, state: &Value) -> Vec<AttachLeaderTar
                 .into_iter()
                 .map(|info| AttachLeaderTarget {
                     info,
-                    endpoint: Some(endpoint.clone()),
+                    endpoint: resolved_endpoint.clone(),
                 }),
         );
     }
@@ -168,10 +169,8 @@ fn attach_leader_targets(workspace: &Path, state: &Value) -> Vec<AttachLeaderTar
 fn tmux_backend_for_endpoint(endpoint: &str) -> crate::tmux_backend::TmuxBackend {
     if endpoint.is_empty() || endpoint == "default" {
         crate::tmux_backend::TmuxBackend::new()
-    } else if Path::new(endpoint).is_absolute() {
-        crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
     } else {
-        crate::tmux_backend::TmuxBackend::for_socket_name(endpoint)
+        crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
     }
 }
 

package/crates/team-agent/src/leader/start.rs

@@ -196,6 +196,9 @@ pub fn execute_leader_plan(
     let detached = plan.mode == LeaderStartMode::NewTmuxSession
         && !std::io::stdin().is_terminal()
         && insert_detach_flag(&mut argv);
+    if plan.is_external_leader {
+        persist_external_leader_topology_marker(plan, workspace)?;
+    }
     let status = run_leader_argv(&argv, &plan.leader_env, plan, workspace)?;
     let code = status.code();
     if !status.success() {
@@ -205,9 +208,6 @@ pub fn execute_leader_plan(
                 .unwrap_or_else(|| "signal".to_string())
         )));
     }
-    if plan.is_external_leader {
-        persist_external_leader_topology_marker(plan, workspace)?;
-    }
     if detached {
         Ok(LeaderLaunchOutcome {
             status: LeaderLaunchStatus::Detached,
@@ -258,7 +258,7 @@ fn start_argv(
     match mode {
         LeaderStartMode::ExecProvider => {
             let mut argv = vec![provider_cmd];
-            argv.extend(provider_args.iter().cloned());
+            argv.extend(normalized_provider_args(provider_args));
             Ok(argv)
         }
         LeaderStartMode::ManagedTmuxClient => {
@@ -289,7 +289,7 @@ fn start_argv(
                 exports.push(shlex_quote(&format!("PATH={path}")));
             }
             let mut provider_argv = vec![provider_cmd];
-            provider_argv.extend(provider_args.iter().cloned());
+            provider_argv.extend(normalized_provider_args(provider_args));
             let shell = format!(
                 "cd {} && export {} && exec {}",
                 shlex_quote(&resolved_workspace.to_string_lossy()),
@@ -316,10 +316,17 @@ fn start_argv(
 
 fn provider_command_argv(provider: Provider, provider_args: &[String]) -> Vec<String> {
     let mut argv = vec![provider_command_name(provider).to_string()];
-    argv.extend(provider_args.iter().cloned());
+    argv.extend(normalized_provider_args(provider_args));
     argv
 }
 
+fn normalized_provider_args(provider_args: &[String]) -> impl Iterator<Item = String> + '_ {
+    provider_args
+        .iter()
+        .skip(usize::from(provider_args.first().is_some_and(|arg| arg == "--")))
+        .cloned()
+}
+
 fn managed_team_session_name(identity: &LeaderIdentity) -> SessionName {
     let team = identity.team_id.as_str();
     if team.starts_with("team-") {
@@ -777,7 +784,12 @@ mod tests {
     use std::path::Path;
     use std::sync::Mutex;
 
+    use crate::leader::{
+        LeaderIdentity, LeaderLaunchSocket, LeaderSessionUuidSource, LeaderStartMode,
+        LeaderStartPlan,
+    };
     use crate::model::enums::PaneLiveness;
+    use crate::model::ids::{LeaderSessionUuid, TeamKey};
     use crate::provider::{Provider, COPILOT_READY_MARKER, COPILOT_TRUST_PROMPT_MARKER};
     use crate::transport::{
         AttachOutcome, BackendKind, CaptureRange, CapturedText, InjectPayload, InjectReport,
@@ -786,7 +798,7 @@ mod tests {
         TurnVerification, WindowName,
     };
 
-    use super::handle_exec_provider_startup_prompts;
+    use super::{execute_leader_plan, handle_exec_provider_startup_prompts, shlex_quote};
 
     struct ScriptedTransport {
         screens: Mutex<Vec<String>>,
@@ -937,6 +949,57 @@ mod tests {
         }
     }
 
+    #[test]
+    fn external_exec_provider_persists_topology_before_provider_exec() {
+        let workspace = std::env::temp_dir().join(format!(
+            "ta-external-pre-exec-{}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&workspace).unwrap();
+        let state_path = crate::state::persist::runtime_state_path(&workspace);
+        let command = format!(
+            "test -f {path} && grep -q is_external_leader {path}",
+            path = shlex_quote(&state_path.to_string_lossy())
+        );
+        let identity = LeaderIdentity {
+            leader_session_uuid: LeaderSessionUuid::derive(
+                "fp",
+                &workspace.to_string_lossy(),
+                "tester",
+                "current",
+            )
+            .unwrap(),
+            leader_session_uuid_source: LeaderSessionUuidSource::Derived,
+            machine_fingerprint: "fp".to_string(),
+            workspace_abspath: workspace.clone(),
+            os_user: "tester".to_string(),
+            team_id: TeamKey::new("current"),
+        };
+        let plan = LeaderStartPlan {
+            mode: LeaderStartMode::ExecProvider,
+            provider: Provider::Codex,
+            workspace: workspace.clone(),
+            socket: LeaderLaunchSocket::Workspace,
+            session_name: None,
+            argv: vec!["sh".to_string(), "-c".to_string(), command],
+            provider_argv: vec!["codex".to_string()],
+            leader_window: None,
+            is_external_leader: true,
+            leader_env: BTreeMap::new(),
+            identity: Some(identity),
+            detached: false,
+        };
+
+        let outcome = execute_leader_plan(&plan, &workspace)
+            .expect("external marker must be present before provider argv runs");
+
+        assert_eq!(outcome.status, crate::leader::LeaderLaunchStatus::Exited);
+        let state = crate::state::persist::load_runtime_state(&workspace).unwrap();
+        assert_eq!(state["is_external_leader"], serde_json::json!(true));
+        assert_eq!(state["teams"]["current"]["is_external_leader"], serde_json::json!(true));
+        let _ = std::fs::remove_dir_all(&workspace);
+    }
+
     #[test]
     fn exec_provider_leader_startup_prompt_handler_reuses_copilot_adapter() {
         let transport = ScriptedTransport::new(vec![

package/crates/team-agent/src/leader/tests/identity.rs

@@ -108,12 +108,20 @@ use super::*;
         let ws = std::env::temp_dir().join(format!("ta_rs_lsp_external_{}", std::process::id()));
         std::fs::create_dir_all(&ws).unwrap();
 
-        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, true).unwrap();
+        let provider_args = vec!["--".to_string(), "--model".to_string(), "opus".to_string()];
+        let plan = leader_start_plan(Provider::Fake, &provider_args, &ws, false, false, None, true).unwrap();
 
         assert_eq!(plan.mode, LeaderStartMode::ExecProvider);
         assert!(plan.is_external_leader);
         assert_eq!(plan.leader_window, None);
-        assert_eq!(plan.argv, vec!["fake".to_string()]);
+        assert_eq!(
+            plan.argv,
+            vec!["fake".to_string(), "--model".to_string(), "opus".to_string()]
+        );
+        assert_eq!(
+            plan.provider_argv,
+            vec!["fake".to_string(), "--model".to_string(), "opus".to_string()]
+        );
     }
 
     #[test]

package/crates/team-agent/src/lifecycle/launch.rs

@@ -856,6 +856,8 @@ fn save_launched_team_state_for_key(
             "active_team_key".to_string(),
             serde_json::Value::String(launched_key.clone()),
         );
+        obj.entry("is_external_leader".to_string())
+            .or_insert(serde_json::Value::Bool(false));
     }
     promote_launched_binding_from_team_entry(&mut launched, &launched_key);
     preserve_existing_leader_topology(&existing, &launched_key, &mut launched);
@@ -3021,10 +3023,7 @@ fn attach_window_names_with_managed_leader(
 }
 
 fn state_uses_managed_leader(state: &serde_json::Value) -> bool {
-    state
-        .get("is_external_leader")
-        .and_then(serde_json::Value::as_bool)
-        .is_some_and(|external| !external)
+    crate::state::projection::state_is_managed_leader(state)
 }
 
 /// BUG-7 helper: derive a [`QuickStartReadiness`] verdict from the just-written
@@ -3087,7 +3086,7 @@ fn quick_start_session_capture_incomplete_agents(workspace: &Path, team_key: &st
     crate::session_capture::incomplete_interacted_resumable_agent_ids(team_state)
 }
 
-fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool {
+pub(crate) fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool {
     let Ok(state) = load_runtime_state(workspace) else {
         return true;
     };
@@ -3097,7 +3096,7 @@ fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool
         .and_then(|teams| teams.get(team_key))
         .unwrap_or(&state);
     if team_state.get("leader_receiver").is_none() {
-        return true;
+        return crate::state::projection::state_is_external_leader(team_state);
     }
     if team_uses_fake_model_harness(team_state) {
         return true;
@@ -4366,6 +4365,7 @@ fn initial_runtime_state(
         "display_backend".to_string(),
         serde_json::json!(display_backend),
     );
+    state.insert("is_external_leader".to_string(), serde_json::json!(false));
     let mut state = serde_json::Value::Object(state);
     if !seed_launched_owner_from_env(&mut state) {
         let team_id = crate::state::projection::team_state_key(&state);

package/crates/team-agent/src/lifecycle/restart/agent.rs

@@ -206,6 +206,7 @@ pub(crate) fn start_agent_at_paths(
         start_mode,
         target: spawn.spawn.pane_id.as_str().to_string(),
         session_id,
+        new_session_id: spawn.plan.expected_session_id.clone(),
         rollout_path,
     })
 }
@@ -528,8 +529,8 @@ fn reset_agent_at_paths(
         .and_then(|v| v.get(agent_id.as_str()))
         .and_then(|v| v.get("session_id"))
         .and_then(|v| v.as_str())
-        .unwrap_or("")
-        .to_string();
+        .filter(|session| !session.is_empty())
+        .map(SessionId::new);
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state_before_stop, Some(agent_id))?;
     let stop = stop_agent_at_paths(workspace, spec_workspace, agent_id, team, transport)?;
     let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
@@ -537,11 +538,22 @@ fn reset_agent_at_paths(
     discard_agent_session_fields(&mut state, agent_id)?;
     // golden operations.py (reset): save_team_scoped_state on the team projection — same multi-team
     // preservation as stop, not a raw save_runtime_state.
-    crate::state::projection::save_team_scoped_state(workspace, &state)
+    crate::state::projection::save_team_scoped_state_with_tombstoned_agents(
+        workspace,
+        &state,
+        &[agent_id.as_str()],
+    )
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     // golden operations.py:125: write_team_state after the discard-save (the intermediate stopped snapshot).
     write_team_state(spec_workspace, &spec, &state)?;
-    write_reset_tombstone_event(workspace, agent_id, &discarded_session_id)?;
+    write_reset_tombstone_event(
+        workspace,
+        agent_id,
+        discarded_session_id
+            .as_ref()
+            .map(SessionId::as_str)
+            .unwrap_or(""),
+    )?;
     let start = start_agent_at_paths(
         workspace,
         spec_workspace,
@@ -556,11 +568,34 @@ fn reset_agent_at_paths(
     write_reset_complete_event(workspace, agent_id, stop.stopped, started)?;
     match start {
         StartAgentOutcome::Running {
-            env, start_mode, ..
-        } => Ok(ResetAgentOutcome::Reset { env, start_mode }),
+            env,
+            start_mode,
+            session_id,
+            new_session_id,
+            ..
+        } => {
+            let output_session_id = if matches!(
+                start_mode,
+                StartMode::Fresh | StartMode::FreshAfterMissingRollout
+            ) {
+                new_session_id.clone().or(session_id)
+            } else {
+                session_id
+            };
+            Ok(ResetAgentOutcome::Reset {
+                env,
+                start_mode,
+                discarded_session_id,
+                session_id: output_session_id,
+                new_session_id,
+            })
+        }
         StartAgentOutcome::Noop { env, .. } => Ok(ResetAgentOutcome::Reset {
             env,
             start_mode: StartMode::Noop,
+            discarded_session_id,
+            session_id: None,
+            new_session_id: None,
         }),
         StartAgentOutcome::Paused { .. } => Ok(ResetAgentOutcome::Reset {
             env: AgentActionEnvelope {
@@ -569,6 +604,9 @@ fn reset_agent_at_paths(
                 coordinator_started: false,
             },
             start_mode: StartMode::Noop,
+            discarded_session_id,
+            session_id: None,
+            new_session_id: None,
         }),
     }
 }

package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs

@@ -1200,9 +1200,15 @@ fn quick_start_persists_selected_tmux_endpoint_and_attach_commands() {
             .any(|cmd| cmd.contains(&format!("tmux -S {endpoint} attach -t "))),
         "attach commands must use the selected socket endpoint: {attach_commands:?}"
     );
+    assert!(
+        attach_commands.iter().any(|cmd| cmd.contains(":leader")),
+        "fresh managed quick-start must include the leader window attach command: {attach_commands:?}"
+    );
     let (_raw, state) = raw_runtime_state(workspace);
     assert_eq!(state["tmux_endpoint"], json!(endpoint));
     assert_eq!(state["tmux_socket"], json!(endpoint));
+    assert_eq!(state["is_external_leader"], json!(false));
+    assert_eq!(state["teams"]["teamdir"]["is_external_leader"], json!(false));
 }
 
 #[test]
@@ -1249,6 +1255,33 @@ fn quick_start_preserves_managed_leader_topology_and_emits_leader_attach_command
     assert_eq!(state["leader_client"]["diagnostic_only"], json!(true));
 }
 
+#[test]
+fn fresh_managed_state_without_receiver_is_not_attached() {
+    let workspace = temp_ws();
+    crate::state::persist::save_runtime_state(
+        &workspace,
+        &json!({
+            "active_team_key": "teamdir",
+            "session_name": "team-teamdir",
+            "is_external_leader": false,
+            "agents": {"implementer": {"status": "running"}},
+            "teams": {
+                "teamdir": {
+                    "session_name": "team-teamdir",
+                    "is_external_leader": false,
+                    "agents": {"implementer": {"status": "running"}}
+                }
+            }
+        }),
+    )
+    .unwrap();
+
+    assert!(
+        !crate::lifecycle::launch::launched_team_receiver_is_attached(&workspace, "teamdir"),
+        "managed topology with missing leader_receiver must not be reported attached"
+    );
+}
+
 #[test]
 fn attach_window_names_for_state_agents_include_managed_leader_and_layout_windows() {
     let state = json!({
@@ -2225,9 +2258,11 @@ fn quick_start_seeds_tasks_key_from_compiled_spec() {
 //   cross-team reads cannot accidentally pick up another team's binding from the root.
 //   The post-launch hook drops the top-level owner triple when the launched pane is
 //   unbound (empty pane_id), and only the per-team entry retains the binding.
-//   Order remains the golden prefix (spec_path … display_backend) + new suffix
-//   (active_team_key, teams). display_backend stays the resolved backend from
-//   display/backend.py:12-29 (default adaptive), not the raw optional spec field.
+//   R1: topology is explicit; fresh managed teams carry `is_external_leader=false`
+//   before the team-in-team suffix. Order remains the golden prefix
+//   (spec_path … display_backend) + topology marker + new suffix (active_team_key,
+//   teams). display_backend stays the resolved backend from display/backend.py:12-29
+//   (default adaptive), not the raw optional spec field.
 #[test]
 #[serial(env)]
 fn quick_start_state_seeds_spec_path_workspace_leader_display_backend() {
@@ -2264,11 +2299,13 @@ fn quick_start_state_seeds_spec_path_workspace_leader_display_backend() {
             "agents",
             "tasks",
             "display_backend",
+            "is_external_leader",
             "active_team_key",
             "teams",
         ],
         "state.json top-level key order must match golden launch/core.py:62-71 \
-         plus Bug 1/2 team-in-team suffix (active_team_key, teams). \
+         plus R1 topology marker and Bug 1/2 team-in-team suffix \
+         (is_external_leader, active_team_key, teams). \
          Bug 2 owner team-scope (N1/N12/N18/N29) deliberately keeps owner / \
          leader_receiver / owner_epoch OFF the top level — they live ONLY under \
          teams[<active_team_key>] so per-team isolation has a single source of \
@@ -2308,6 +2345,7 @@ fn quick_start_state_seeds_spec_path_workspace_leader_display_backend() {
         json!("adaptive"),
         "adaptive layout directive: resolve_display_backend(None, source='launch') defaults to adaptive"
     );
+    assert_eq!(state["is_external_leader"], json!(false));
 }
 
 // Stage B1 — golden launch/core.py:238-255 writes the running agent state only after

package/crates/team-agent/src/lifecycle/types.rs

@@ -535,6 +535,7 @@ pub enum StartAgentOutcome {
         start_mode: StartMode,
         target: String,
         session_id: Option<SessionId>,
+        new_session_id: Option<SessionId>,
         rollout_path: Option<RolloutPath>,
     },
     /// 窗口已存在且非 force → noop(`start.py:134`)。
@@ -565,6 +566,9 @@ pub enum ResetAgentOutcome {
     Reset {
         env: AgentActionEnvelope,
         start_mode: StartMode,
+        discarded_session_id: Option<SessionId>,
+        session_id: Option<SessionId>,
+        new_session_id: Option<SessionId>,
     },
     /// 未传 discard_session → 拒绝(不丢上下文的误用保护)。
     Refused { reason: ResetRefusal },

package/crates/team-agent/src/mcp_server/lifecycle_tools/agent_ops.rs

@@ -60,7 +60,13 @@ pub(crate) fn reset_agent(
     )
     .map_err(tool_runtime_error)?
     {
-        ResetAgentOutcome::Reset { env, start_mode } => Ok(ToolOk {
+        ResetAgentOutcome::Reset {
+            env,
+            start_mode,
+            discarded_session_id,
+            session_id,
+            new_session_id,
+        } => Ok(ToolOk {
             fields: object_fields(serde_json::json!({
                 "ok": true,
                 "agent_id": env.agent_id.as_str(),
@@ -68,6 +74,9 @@ pub(crate) fn reset_agent(
                 "state_file": env.state_file.to_string_lossy().to_string(),
                 "coordinator_started": env.coordinator_started,
                 "start_mode": enum_value(start_mode),
+                "discarded_session_id": discarded_session_id.as_ref().map(|id| id.as_str()),
+                "session_id": session_id.as_ref().map(|id| id.as_str()),
+                "new_session_id": new_session_id.as_ref().map(|id| id.as_str()),
             })),
         }),
         ResetAgentOutcome::Refused { reason } => Ok(ToolOk {

package/crates/team-agent/src/state/persist.rs

@@ -170,13 +170,38 @@ impl Drop for RuntimeLock {
 /// `save_runtime_state`(bug-084)。`state` 是 state.json 的内存 Value(插入序保留)。
 /// 注:Python 在此还调 `_migrate_state_identity`(identity slice 落地后接入;本 slice 不改 state 内容)。
 pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateError> {
-    save_runtime_state_with_deleted_agents(workspace, state, &[])
+    save_runtime_state_with_merge_exceptions(workspace, state, &[], None, &[])
 }
 
 pub(crate) fn save_runtime_state_with_deleted_agents(
     workspace: &Path,
     state: &Value,
     deleted_agent_ids: &[&str],
+) -> Result<(), StateError> {
+    save_runtime_state_with_merge_exceptions(workspace, state, deleted_agent_ids, None, &[])
+}
+
+pub(crate) fn save_runtime_state_with_team_tombstoned_agents(
+    workspace: &Path,
+    state: &Value,
+    tombstoned_team_key: &str,
+    tombstoned_agent_ids: &[&str],
+) -> Result<(), StateError> {
+    save_runtime_state_with_merge_exceptions(
+        workspace,
+        state,
+        &[],
+        Some(tombstoned_team_key),
+        tombstoned_agent_ids,
+    )
+}
+
+fn save_runtime_state_with_merge_exceptions(
+    workspace: &Path,
+    state: &Value,
+    deleted_agent_ids: &[&str],
+    skip_capture_backfill_team_key: Option<&str>,
+    skip_capture_backfill_agent_ids: &[&str],
 ) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
     if cache_equals(&path, state) {
@@ -218,7 +243,19 @@ pub(crate) fn save_runtime_state_with_deleted_agents(
             .filter(|id| !id.is_empty())
             .map(str::to_string)
             .collect::<BTreeSet<_>>();
-        preserve_latest_roster_entries(&mut migrated, &latest, &deleted);
+        let skip_capture_backfill = skip_capture_backfill_agent_ids
+            .iter()
+            .copied()
+            .filter(|id| !id.is_empty())
+            .map(str::to_string)
+            .collect::<BTreeSet<_>>();
+        preserve_latest_roster_entries(
+            &mut migrated,
+            &latest,
+            &deleted,
+            skip_capture_backfill_team_key,
+            &skip_capture_backfill,
+        );
     }
     // 字节对拍 Python json.dumps(indent=2, ensure_ascii=False)(无尾换行)。
     let payload = serde_json::to_string_pretty(&migrated)?;
@@ -269,19 +306,34 @@ fn read_latest_state_under_lock(workspace: &Path, path: &Path) -> Option<Value>
     Some(latest)
 }
 
-fn preserve_latest_roster_entries(incoming: &mut Value, latest: &Value, deleted_agent_ids: &BTreeSet<String>) {
+fn preserve_latest_roster_entries(
+    incoming: &mut Value,
+    latest: &Value,
+    deleted_agent_ids: &BTreeSet<String>,
+    skip_capture_backfill_team_key: Option<&str>,
+    skip_capture_backfill_agent_ids: &BTreeSet<String>,
+) {
     // A0/R1: the projection gate only guards the TOP-LEVEL passes (top-level agents and
     // the top-level<->active-team cross projections depend on which team is active); the
     // per-team `teams.<k>.agents` merge below is team-key self-identifying and must run
     // even when another process flipped session_name/active_team_key between this
     // writer's load and save.
     let projection_matches = same_runtime_projection(incoming, latest);
+    let active_team = active_team_key(incoming).or_else(|| active_team_key(latest));
+    let top_level_team = Some(team_state_key(incoming)).or_else(|| Some(team_state_key(latest)));
+    let skip_top_level_capture_backfill =
+        should_skip_capture_backfill(top_level_team.as_deref(), skip_capture_backfill_team_key);
     if projection_matches {
-        preserve_missing_agents(incoming.get_mut("agents"), latest.get("agents"), deleted_agent_ids);
+        preserve_missing_agents(
+            incoming.get_mut("agents"),
+            latest.get("agents"),
+            deleted_agent_ids,
+            skip_top_level_capture_backfill,
+            skip_capture_backfill_agent_ids,
+        );
         preserve_latest_ownership_fields(incoming, latest);
     }
 
-    let active_team = active_team_key(incoming).or_else(|| active_team_key(latest));
     if projection_matches {
         if let Some(active_team) = active_team.as_deref() {
             let latest_active_agents = latest
@@ -289,7 +341,13 @@ fn preserve_latest_roster_entries(incoming: &mut Value, latest: &Value, deleted_
                 .and_then(Value::as_object)
                 .and_then(|teams| teams.get(active_team))
                 .and_then(|entry| entry.get("agents"));
-            preserve_missing_agents(incoming.get_mut("agents"), latest_active_agents, deleted_agent_ids);
+            preserve_missing_agents(
+                incoming.get_mut("agents"),
+                latest_active_agents,
+                deleted_agent_ids,
+                skip_top_level_capture_backfill,
+                skip_capture_backfill_agent_ids,
+            );
         }
     }
 
@@ -306,6 +364,8 @@ fn preserve_latest_roster_entries(incoming: &mut Value, latest: &Value, deleted_
                 incoming_entry.get_mut("agents"),
                 latest_entry.get("agents"),
                 deleted_agent_ids,
+                should_skip_capture_backfill(Some(team), skip_capture_backfill_team_key),
+                skip_capture_backfill_agent_ids,
             );
             preserve_latest_ownership_fields(incoming_entry, latest_entry);
         }
@@ -314,13 +374,26 @@ fn preserve_latest_roster_entries(incoming: &mut Value, latest: &Value, deleted_
         if let Some(active_team) = active_team.as_deref() {
             let latest_top_agents = latest.get("agents");
             if let Some(incoming_entry) = incoming_teams.get_mut(active_team) {
-                preserve_missing_agents(incoming_entry.get_mut("agents"), latest_top_agents, deleted_agent_ids);
+                preserve_missing_agents(
+                    incoming_entry.get_mut("agents"),
+                    latest_top_agents,
+                    deleted_agent_ids,
+                    should_skip_capture_backfill(Some(active_team), skip_capture_backfill_team_key),
+                    skip_capture_backfill_agent_ids,
+                );
                 preserve_latest_ownership_fields(incoming_entry, latest);
             }
         }
     }
 }
 
+fn should_skip_capture_backfill(current_team_key: Option<&str>, skip_team_key: Option<&str>) -> bool {
+    match skip_team_key {
+        Some(skip_team_key) => current_team_key == Some(skip_team_key),
+        None => true,
+    }
+}
+
 fn preserve_latest_ownership_fields(incoming: &mut Value, latest: &Value) {
     if !latest_has_preferable_ownership(incoming, latest) {
         return;
@@ -379,6 +452,8 @@ fn preserve_missing_agents(
     incoming_agents: Option<&mut Value>,
     latest_agents: Option<&Value>,
     deleted_agent_ids: &BTreeSet<String>,
+    skip_capture_backfill: bool,
+    skip_capture_backfill_agent_ids: &BTreeSet<String>,
 ) {
     let Some(incoming_agents) = incoming_agents else {
         return;
@@ -398,7 +473,9 @@ fn preserve_missing_agents(
                 slot.insert(latest_agent.clone());
             }
             serde_json::map::Entry::Occupied(mut existing) => {
-                backfill_capture_fields(existing.get_mut(), latest_agent);
+                if !skip_capture_backfill || !skip_capture_backfill_agent_ids.contains(agent_id) {
+                    backfill_capture_fields(existing.get_mut(), latest_agent);
+                }
             }
         }
     }

package/crates/team-agent/src/state/projection.rs

@@ -14,7 +14,7 @@ use std::path::Path;
 use serde_json::{json, Map, Value};
 
 use super::StateError;
-use crate::state::persist::{load_runtime_state, save_runtime_state_with_deleted_agents};
+use crate::state::persist::{load_runtime_state, save_runtime_state_with_deleted_agents, save_runtime_state_with_team_tombstoned_agents};
 
 /// `team_state_key`(`state.py:93`):从 team_dir(.name)/spec_path(.parent.name)派生 team key,
 /// 跳过 `.team`/`runtime`;兜底 `session_name` 或 `"current"`。
@@ -162,6 +162,17 @@ pub fn compact_team_state(state: &Value) -> Value {
     }
 }
 
+pub fn state_is_external_leader(state: &Value) -> bool {
+    state
+        .get("is_external_leader")
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+}
+
+pub fn state_is_managed_leader(state: &Value) -> bool {
+    !state_is_external_leader(state)
+}
+
 /// `merge_workspace_team_state`(`state.py:111`):把新启动的 team 并入既有 workspace state。
 pub fn merge_workspace_team_state(existing: &Value, launched: &Value) -> Value {
     let launched_key = team_state_key(launched);
@@ -471,6 +482,23 @@ pub(crate) fn save_team_scoped_state_with_deleted_agents(
     workspace: &Path,
     team_state: &Value,
     deleted_agent_ids: &[&str],
+) -> Result<(), StateError> {
+    save_team_scoped_state_with_merge_exceptions(workspace, team_state, deleted_agent_ids, &[])
+}
+
+pub(crate) fn save_team_scoped_state_with_tombstoned_agents(
+    workspace: &Path,
+    team_state: &Value,
+    tombstoned_agent_ids: &[&str],
+) -> Result<(), StateError> {
+    save_team_scoped_state_with_merge_exceptions(workspace, team_state, &[], tombstoned_agent_ids)
+}
+
+fn save_team_scoped_state_with_merge_exceptions(
+    workspace: &Path,
+    team_state: &Value,
+    deleted_agent_ids: &[&str],
+    tombstoned_agent_ids: &[&str],
 ) -> Result<(), StateError> {
     let target_key = team_state_key(team_state);
     let existing = load_runtime_state(workspace)?;
@@ -500,7 +528,15 @@ pub(crate) fn save_team_scoped_state_with_deleted_agents(
     // not existing_teams and existing_primary_key == target_key → 纯 save(剔 teams)。
     if existing_teams.is_empty() && existing_primary_key.as_deref() == Some(target_key.as_str()) {
         let merged = compact_team_state(team_state);
-        return save_runtime_state_with_deleted_agents(workspace, &merged, deleted_agent_ids);
+        if tombstoned_agent_ids.is_empty() {
+            return save_runtime_state_with_deleted_agents(workspace, &merged, deleted_agent_ids);
+        }
+        return save_runtime_state_with_team_tombstoned_agents(
+            workspace,
+            &merged,
+            &target_key,
+            tombstoned_agent_ids,
+        );
     }
     // teams = deepcopy(incoming_teams or existing_teams)
     let mut teams = match incoming_teams {
@@ -520,7 +556,16 @@ pub(crate) fn save_team_scoped_state_with_deleted_agents(
     if merged.get("teams").and_then(Value::as_object).is_some_and(Map::is_empty) {
         merged.remove("teams");
     }
-    save_runtime_state_with_deleted_agents(workspace, &Value::Object(merged), deleted_agent_ids)
+    if tombstoned_agent_ids.is_empty() {
+        save_runtime_state_with_deleted_agents(workspace, &Value::Object(merged), deleted_agent_ids)
+    } else {
+        save_runtime_state_with_team_tombstoned_agents(
+            workspace,
+            &Value::Object(merged),
+            &target_key,
+            tombstoned_agent_ids,
+        )
+    }
 }
 
 // ---- helpers ----

package/crates/team-agent/src/tmux_backend/tests.rs

@@ -8,6 +8,7 @@
     #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
 
     use std::collections::{BTreeMap, VecDeque};
+    use std::os::unix::net::UnixListener;
     use std::path::Path;
     use std::sync::{Arc, Mutex};
 
@@ -251,8 +252,20 @@
     }
 
     #[test]
+    #[serial_test::serial(env)]
     fn leader_receiver_short_endpoint_must_not_reconstruct_tmux_l_socket() {
         let endpoint = "dl9aa40c88";
+        let uid = unsafe { libc::geteuid() };
+        let tmp = std::env::temp_dir().join(format!(
+            "ta-tmux-short-endpoint-{}",
+            std::process::id()
+        ));
+        let root = tmp.join(format!("tmux-{uid}"));
+        std::fs::create_dir_all(&root).unwrap();
+        let socket_path = root.join(endpoint);
+        let _listener = UnixListener::bind(&socket_path).unwrap();
+        let socket_path = socket_path.canonicalize().unwrap();
+        let _env = EnvGuard::apply(&[("TMPDIR", Some(tmp.to_str().unwrap()))]);
         let (be, rec) = {
             let recorded = Arc::new(Mutex::new(Vec::new()));
             let runner = MockCommandRunner {
@@ -275,6 +288,14 @@
             "non-canonical leader endpoints must be rejected or left unbound, never reconstructed as \
              tmux -L <short> under the coordinator socket root; calls={calls:?}"
         );
+        assert!(
+            calls.iter().all(|call| call.starts_with(&[
+                "tmux".to_string(),
+                "-S".to_string(),
+                socket_path.to_string_lossy().to_string()
+            ])),
+            "short leader endpoints must resolve to the existing physical socket path with -S; calls={calls:?}"
+        );
     }
 
     // ── 1. has_session: exit 0 -> true, exit 1 -> false; argv = `tmux has-session -t <s>` ──────────

package/crates/team-agent/src/tmux_backend.rs

@@ -233,6 +233,12 @@ impl TmuxBackend {
                 socket: Some(TmuxSocketEndpoint::Path(endpoint.to_string())),
                 event_workspace: None,
             }
+        } else if let Some(path) = socket_path_for_name(endpoint) {
+            Self {
+                runner: Box::new(RealCommandRunner),
+                socket: Some(TmuxSocketEndpoint::Path(path.to_string_lossy().into_owned())),
+                event_workspace: None,
+            }
         } else {
             Self::new()
         }
@@ -275,6 +281,12 @@ impl TmuxBackend {
                 socket: None,
                 event_workspace: None,
             }
+        } else if let Some(path) = socket_path_for_name(endpoint) {
+            Self {
+                runner,
+                socket: Some(TmuxSocketEndpoint::Path(path.to_string_lossy().into_owned())),
+                event_workspace: None,
+            }
         } else {
             Self {
                 runner,
@@ -340,13 +352,7 @@ pub(crate) fn socket_name_for_workspace(workspace: &Path) -> String {
 }
 
 pub(crate) fn socket_path_for_workspace(workspace: &Path) -> Option<PathBuf> {
-    if let Some(existing) = existing_socket_path_for_workspace(workspace) {
-        return Some(existing);
-    }
-    let uid = unsafe { libc::geteuid() };
-    let default_root = PathBuf::from(format!("/tmp/tmux-{uid}"));
-    let default_root = default_root.canonicalize().unwrap_or(default_root);
-    Some(default_root.join(socket_name_for_workspace(workspace)))
+    socket_path_for_name(&socket_name_for_workspace(workspace))
 }
 
 pub(crate) fn socket_probe_missing_for_workspace(workspace: &Path) -> bool {
@@ -354,11 +360,27 @@ pub(crate) fn socket_probe_missing_for_workspace(workspace: &Path) -> bool {
 }
 
 fn existing_socket_path_for_workspace(workspace: &Path) -> Option<PathBuf> {
-    let socket_name = socket_name_for_workspace(workspace);
+    existing_socket_path_for_name(&socket_name_for_workspace(workspace))
+}
+
+pub(crate) fn socket_path_for_name(socket_name: &str) -> Option<PathBuf> {
+    if socket_name.is_empty() || socket_name == "default" || Path::new(socket_name).is_absolute() {
+        return None;
+    }
+    if let Some(existing) = existing_socket_path_for_name(socket_name) {
+        return Some(existing);
+    }
+    let uid = unsafe { libc::geteuid() };
+    let default_root = PathBuf::from(format!("/tmp/tmux-{uid}"));
+    let default_root = default_root.canonicalize().unwrap_or(default_root);
+    Some(default_root.join(socket_name))
+}
+
+fn existing_socket_path_for_name(socket_name: &str) -> Option<PathBuf> {
     let roots = tmux_socket_roots();
     for root in &roots {
         let root = root.canonicalize().unwrap_or_else(|_| root.clone());
-        let candidate = root.join(&socket_name);
+        let candidate = root.join(socket_name);
         if candidate.exists() {
             return Some(candidate.canonicalize().unwrap_or(candidate));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.3.17",
-    "@team-agent/cli-darwin-x64": "0.3.17",
-    "@team-agent/cli-linux-x64": "0.3.17"
+    "@team-agent/cli-darwin-arm64": "0.3.19",
+    "@team-agent/cli-darwin-x64": "0.3.19",
+    "@team-agent/cli-linux-x64": "0.3.19"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",