@team-agent/installer 0.3.0 → 0.3.2

package/crates/team-agent/src/provider/adapter.rs

@@ -277,15 +277,19 @@ impl ProviderAdapter for BasicProviderAdapter {
         spawn_cwd: &Path,
         _timeout_s: u64,
     ) -> Result<Option<CapturedSession>, ProviderError> {
-        let candidates = candidate_session_files(spawn_cwd, agent_id)?;
-        for path in candidates {
+        let candidates = candidate_session_files(self.provider, spawn_cwd, agent_id)?;
+        for candidate in candidates {
+            let path = candidate.path;
             let Ok(text) = std::fs::read_to_string(&path) else {
                 continue;
             };
-            let records = parse_jsonl_records(&text);
+            let records = parse_session_records(&text);
             if records.is_empty() {
                 continue;
             }
+            if candidate.requires_cwd_match && !provider_home_records_match_spawn_cwd(&records, spawn_cwd) {
+                continue;
+            }
             let session_id = records.iter().find_map(find_session_id);
             if matches!(self.provider, Provider::Claude | Provider::ClaudeCode)
                 && session_id.is_some()
@@ -518,18 +522,56 @@ fn command_on_path(name: &str) -> bool {
     std::env::split_paths(&path).any(|dir| dir.join(name).is_file())
 }
 
-fn candidate_session_files(spawn_cwd: &Path, agent_id: &str) -> Result<Vec<PathBuf>, ProviderError> {
+struct SessionCandidate {
+    path: PathBuf,
+    requires_cwd_match: bool,
+}
+
+fn candidate_session_files(
+    provider: Provider,
+    spawn_cwd: &Path,
+    agent_id: &str,
+) -> Result<Vec<SessionCandidate>, ProviderError> {
     let mut out = Vec::new();
-    collect_candidate_files(spawn_cwd, agent_id, 0, &mut out)?;
-    out.sort_by(|a, b| a.to_string_lossy().cmp(&b.to_string_lossy()));
+    collect_candidate_files(spawn_cwd, agent_id, 0, false, &mut out)?;
+    if let Some(home) = std::env::var_os("HOME").map(PathBuf::from) {
+        match provider {
+            Provider::Codex => {
+                collect_optional_candidate_files(&home.join(".codex").join("sessions"), agent_id, &mut out)?;
+            }
+            Provider::Claude | Provider::ClaudeCode => {
+                collect_optional_candidate_files(&home.join(".claude").join("sessions"), agent_id, &mut out)?;
+                collect_optional_candidate_files(&home.join(".claude").join("projects"), agent_id, &mut out)?;
+            }
+            Provider::GeminiCli | Provider::Fake => {}
+        }
+    }
+    out.sort_by(|a, b| {
+        a.requires_cwd_match
+            .cmp(&b.requires_cwd_match)
+            .then_with(|| a.path.to_string_lossy().cmp(&b.path.to_string_lossy()))
+    });
+    out.dedup_by(|a, b| a.path == b.path && a.requires_cwd_match == b.requires_cwd_match);
     Ok(out)
 }
 
+fn collect_optional_candidate_files(
+    dir: &Path,
+    agent_id: &str,
+    out: &mut Vec<SessionCandidate>,
+) -> Result<(), ProviderError> {
+    if dir.exists() {
+        let _ = collect_candidate_files(dir, agent_id, 0, true, out);
+    }
+    Ok(())
+}
+
 fn collect_candidate_files(
     dir: &Path,
     agent_id: &str,
     depth: usize,
-    out: &mut Vec<PathBuf>,
+    requires_cwd_match: bool,
+    out: &mut Vec<SessionCandidate>,
 ) -> Result<(), ProviderError> {
     if depth > 4 {
         return Ok(());
@@ -545,9 +587,12 @@ fn collect_candidate_files(
         };
         let path = entry.path();
         if path.is_dir() {
-            collect_candidate_files(&path, agent_id, depth.saturating_add(1), out)?;
+            collect_candidate_files(&path, agent_id, depth.saturating_add(1), requires_cwd_match, out)?;
         } else if looks_like_session_file(&path, agent_id) {
-            out.push(path);
+            out.push(SessionCandidate {
+                path,
+                requires_cwd_match,
+            });
         }
     }
     Ok(())
@@ -572,6 +617,46 @@ fn looks_like_session_file(path: &Path, agent_id: &str) -> bool {
         || (!agent_id.is_empty() && name.contains(agent_id))
 }
 
+fn parse_session_records(text: &str) -> Vec<serde_json::Value> {
+    match serde_json::from_str::<serde_json::Value>(text) {
+        Ok(serde_json::Value::Array(items)) => items,
+        Ok(value) => vec![value],
+        Err(_) => parse_jsonl_records(text),
+    }
+}
+
+fn provider_home_records_match_spawn_cwd(records: &[serde_json::Value], spawn_cwd: &Path) -> bool {
+    let cwd_values: Vec<String> = records.iter().filter_map(record_cwd).collect();
+    !cwd_values.is_empty()
+        && cwd_values
+            .iter()
+            .any(|cwd| paths_equivalent(Path::new(cwd), spawn_cwd))
+}
+
+fn record_cwd(record: &serde_json::Value) -> Option<String> {
+    record
+        .get("cwd")
+        .and_then(serde_json::Value::as_str)
+        .or_else(|| {
+            record
+                .get("session_meta")
+                .and_then(|v| v.get("payload"))
+                .or_else(|| record.get("payload"))
+                .and_then(|v| v.get("cwd"))
+                .and_then(serde_json::Value::as_str)
+        })
+        .map(ToString::to_string)
+}
+
+fn paths_equivalent(left: &Path, right: &Path) -> bool {
+    if left == right {
+        return true;
+    }
+    let left = std::fs::canonicalize(left).unwrap_or_else(|_| left.to_path_buf());
+    let right = std::fs::canonicalize(right).unwrap_or_else(|_| right.to_path_buf());
+    left == right || left.starts_with(&right)
+}
+
 /// `true` iff any path component is `.team` (the Team Agent runtime/logs root) — used
 /// to gate session-file detection so `<workspace>/.team/logs/events.jsonl`,
 /// `.team/runtime/team.db`, etc. are NEVER mistaken for a provider transcript.
@@ -790,7 +875,7 @@ fn current_team_agent_command() -> String {
 }
 
 fn has_cwd_field(record: &serde_json::Value) -> bool {
-    record.get("cwd").and_then(serde_json::Value::as_str).is_some()
+    record_cwd(record).is_some()
 }
 
 fn next_session_token() -> String {

package/crates/team-agent/src/provider/helpers.rs

@@ -22,9 +22,18 @@ pub(crate) fn find_session_id(record: &serde_json::Value) -> Option<String> {
     if let Some(s) = record.get("sessionId").and_then(serde_json::Value::as_str) {
         return Some(s.to_string());
     }
-    record
+    if let Some(s) = record
         .get("session_id")
         .and_then(serde_json::Value::as_str)
+    {
+        return Some(s.to_string());
+    }
+    record
+        .get("session_meta")
+        .and_then(|v| v.get("payload"))
+        .or_else(|| record.get("payload"))
+        .and_then(|v| v.get("id"))
+        .and_then(serde_json::Value::as_str)
         .map(ToString::to_string)
 }
 

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

@@ -332,6 +332,9 @@ pub fn apply_first_time_leader_binding(
         r.insert("leader_session_uuid".to_string(), id_uuid.clone());
         r.insert("machine_fingerprint".to_string(), id_fp.clone());
         r.insert("owner_epoch".to_string(), json!(0));
+        if let Some(socket) = crate::tmux_backend::socket_name_from_tmux_env() {
+            r.insert("tmux_socket".to_string(), json!(socket));
+        }
     }
     let owner = json!({
         "pane_id": receiver.get("pane_id").cloned().unwrap_or(Value::Null),

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

@@ -20,7 +20,7 @@
 //! (`identity::migrate_state_identity`,补 leader_session_uuid)→ `_migrate_active_team_key`
 //! (seed active 指针);任一改动 → `save_runtime_state` 回写。不存在且命中缓存 → 返回缓存 deepcopy。
 
-use std::collections::HashMap;
+use std::collections::{BTreeSet, HashMap};
 use std::io;
 use std::path::{Path, PathBuf};
 use std::sync::{LazyLock, Mutex};
@@ -170,6 +170,14 @@ 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, &[])
+}
+
+pub(crate) fn save_runtime_state_with_deleted_agents(
+    workspace: &Path,
+    state: &Value,
+    deleted_agent_ids: &[&str],
+) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
     if cache_equals(&path, state) {
         return Ok(());
@@ -203,6 +211,15 @@ pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateEr
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
     }
+    if let Some(latest) = read_latest_state_under_lock(workspace, &path) {
+        let deleted = deleted_agent_ids
+            .iter()
+            .copied()
+            .filter(|id| !id.is_empty())
+            .map(str::to_string)
+            .collect::<BTreeSet<_>>();
+        preserve_latest_roster_entries(&mut migrated, &latest, &deleted);
+    }
     // 字节对拍 Python json.dumps(indent=2, ensure_ascii=False)(无尾换行)。
     let payload = serde_json::to_string_pretty(&migrated)?;
     let delays = [0.05_f64, 0.2, 0.5];
@@ -243,6 +260,101 @@ pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateEr
     Err(StateError::SaveFailed("retry loop exhausted without return".to_string()))
 }
 
+fn read_latest_state_under_lock(workspace: &Path, path: &Path) -> Option<Value> {
+    let text = std::fs::read_to_string(path).ok()?;
+    let mut latest = serde_json::from_str::<Value>(&text).ok()?;
+    normalize_agent_session_state(&mut latest);
+    let _ = migrate_state_identity(&mut latest, &SystemEnv, workspace);
+    let _ = migrate_active_team_key(&mut latest);
+    Some(latest)
+}
+
+fn preserve_latest_roster_entries(incoming: &mut Value, latest: &Value, deleted_agent_ids: &BTreeSet<String>) {
+    if !same_runtime_projection(incoming, latest) {
+        return;
+    }
+    preserve_missing_agents(incoming.get_mut("agents"), latest.get("agents"), deleted_agent_ids);
+
+    let active_team = active_team_key(incoming).or_else(|| active_team_key(latest));
+    if let Some(active_team) = active_team.as_deref() {
+        let latest_active_agents = latest
+            .get("teams")
+            .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);
+    }
+
+    let latest_teams = latest.get("teams").and_then(Value::as_object);
+    let Some(incoming_teams) = incoming.get_mut("teams").and_then(Value::as_object_mut) else {
+        return;
+    };
+    if let Some(latest_teams) = latest_teams {
+        for (team, latest_entry) in latest_teams {
+            let Some(incoming_entry) = incoming_teams.get_mut(team) else {
+                continue;
+            };
+            preserve_missing_agents(
+                incoming_entry.get_mut("agents"),
+                latest_entry.get("agents"),
+                deleted_agent_ids,
+            );
+        }
+    }
+    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);
+        }
+    }
+}
+
+fn preserve_missing_agents(
+    incoming_agents: Option<&mut Value>,
+    latest_agents: Option<&Value>,
+    deleted_agent_ids: &BTreeSet<String>,
+) {
+    let Some(incoming_agents) = incoming_agents else {
+        return;
+    };
+    let Some(incoming_map) = incoming_agents.as_object_mut() else {
+        return;
+    };
+    let Some(latest_map) = latest_agents.and_then(Value::as_object) else {
+        return;
+    };
+    for (agent_id, latest_agent) in latest_map {
+        if deleted_agent_ids.contains(agent_id) {
+            continue;
+        }
+        incoming_map
+            .entry(agent_id.clone())
+            .or_insert_with(|| latest_agent.clone());
+    }
+}
+
+fn same_runtime_projection(left: &Value, right: &Value) -> bool {
+    let left_session = left.get("session_name").and_then(Value::as_str);
+    let right_session = right.get("session_name").and_then(Value::as_str);
+    if left_session.is_some() && right_session.is_some() && left_session != right_session {
+        return false;
+    }
+    let left_team = active_team_key(left);
+    let right_team = active_team_key(right);
+    if left_team.is_some() && right_team.is_some() && left_team != right_team {
+        return false;
+    }
+    true
+}
+
+fn active_team_key(state: &Value) -> Option<String> {
+    state
+        .get("active_team_key")
+        .and_then(Value::as_str)
+        .filter(|team| !team.is_empty() && *team != "current")
+        .map(str::to_string)
+}
+
 /// `_self_heal_runtime_state`:重建 inode(heal-tmp + backup-rename),绝不 in-place truncate。
 fn self_heal(
     workspace: &Path,

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};
+use crate::state::persist::{load_runtime_state, save_runtime_state_with_deleted_agents};
 
 /// `team_state_key`(`state.py:93`):从 team_dir(.name)/spec_path(.parent.name)派生 team key,
 /// 跳过 `.team`/`runtime`;兜底 `session_name` 或 `"current"`。
@@ -43,6 +43,122 @@ pub fn team_state_key(state: &Value) -> String {
         .map_or_else(|| "current".to_string(), str::to_string)
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum OwnerTeamResolution {
+    Canonical(String),
+    LegacyAlias { requested: String, canonical: String },
+    Unresolved { requested: String },
+    Ambiguous { requested: String, matches: Vec<String> },
+}
+
+impl OwnerTeamResolution {
+    pub fn canonical_key(&self) -> Option<&str> {
+        match self {
+            OwnerTeamResolution::Canonical(key)
+            | OwnerTeamResolution::LegacyAlias { canonical: key, .. } => Some(key),
+            OwnerTeamResolution::Unresolved { .. } | OwnerTeamResolution::Ambiguous { .. } => None,
+        }
+    }
+}
+
+pub fn resolve_owner_team_id(state: &Value, owner_team_id: &str) -> OwnerTeamResolution {
+    let requested = owner_team_id.trim();
+    if requested.is_empty() {
+        return OwnerTeamResolution::Unresolved { requested: owner_team_id.to_string() };
+    }
+    let teams = state.get("teams").and_then(Value::as_object);
+    if teams.is_some_and(|teams| teams.contains_key(requested)) {
+        if has_top_level_runtime_content(state) {
+            return OwnerTeamResolution::Canonical(requested.to_string());
+        }
+    }
+    if teams.is_none_or(Map::is_empty) {
+        let active = state.get("active_team_key").and_then(Value::as_str).unwrap_or("");
+        let derived = team_state_key(state);
+        if active == requested || derived == requested {
+            return OwnerTeamResolution::Canonical(requested.to_string());
+        }
+        if !active.is_empty() {
+            return OwnerTeamResolution::LegacyAlias {
+                requested: requested.to_string(),
+                canonical: active.to_string(),
+            };
+        }
+        if derived != "current" {
+            return OwnerTeamResolution::LegacyAlias {
+                requested: requested.to_string(),
+                canonical: derived,
+            };
+        }
+        return OwnerTeamResolution::Canonical(requested.to_string());
+    }
+    let Some(teams) = teams else {
+        return OwnerTeamResolution::Unresolved { requested: requested.to_string() };
+    };
+    let mut matches = Vec::new();
+    for (key, entry) in teams {
+        if legacy_owner_team_aliases(entry).any(|alias| alias == requested) {
+            matches.push(key.clone());
+        }
+    }
+    matches.sort();
+    matches.dedup();
+    match matches.len() {
+        0 => OwnerTeamResolution::Unresolved { requested: requested.to_string() },
+        1 => OwnerTeamResolution::LegacyAlias {
+            requested: requested.to_string(),
+            canonical: matches.remove(0),
+        },
+        _ => OwnerTeamResolution::Ambiguous { requested: requested.to_string(), matches },
+    }
+}
+
+fn has_top_level_runtime_content(state: &Value) -> bool {
+    [
+        "session_name",
+        "team_dir",
+        "spec_path",
+        "workspace",
+        "agents",
+        "tasks",
+        "leader_receiver",
+        "team_owner",
+    ]
+    .into_iter()
+    .any(|key| state.get(key).is_some_and(super::json_truthy))
+}
+
+fn legacy_owner_team_aliases(entry: &Value) -> impl Iterator<Item = String> + '_ {
+    let scalar_paths = [
+        "/team/name",
+        "/team/id",
+        "/name",
+        "/team_name",
+        "/team_id",
+        "/spec_name",
+        "/legacy_owner_team_id",
+        "/legacy_team_id",
+        "/legacy_team_name",
+        "/legacy_alias",
+    ];
+    let list_paths = ["/legacy_aliases", "/legacy_team_aliases", "/legacy_owner_team_ids", "/aliases"];
+    let scalars = scalar_paths
+        .into_iter()
+        .filter_map(|path| entry.pointer(path).and_then(Value::as_str));
+    let lists = list_paths.into_iter().flat_map(|path| {
+        entry
+            .pointer(path)
+            .and_then(Value::as_array)
+            .into_iter()
+            .flatten()
+            .filter_map(Value::as_str)
+    });
+    scalars
+        .chain(lists)
+        .filter(|alias| !alias.is_empty())
+        .map(str::to_string)
+}
+
 /// `compact_team_state`(`state.py:105`):剔除 `teams`(team entry 不嵌套全量 teams),保序。
 pub fn compact_team_state(state: &Value) -> Value {
     match state.as_object() {
@@ -339,6 +455,14 @@ pub fn resolve_team_scoped_state(
 /// 纯 `save_runtime_state`(字节等价);多 team 时把本 team 落到 `teams[target_key]=compact(...)`,顶层
 /// 视图按 golden 的 `existing_primary_key` 逻辑择 incoming/existing。§10:无 unwrap/panic。
 pub fn save_team_scoped_state(workspace: &Path, team_state: &Value) -> Result<(), StateError> {
+    save_team_scoped_state_with_deleted_agents(workspace, team_state, &[])
+}
+
+pub(crate) fn save_team_scoped_state_with_deleted_agents(
+    workspace: &Path,
+    team_state: &Value,
+    deleted_agent_ids: &[&str],
+) -> Result<(), StateError> {
     let target_key = team_state_key(team_state);
     let existing = load_runtime_state(workspace)?;
     // existing_primary_key = team_state_key(existing) if existing.get("session_name") else None
@@ -367,7 +491,7 @@ pub fn save_team_scoped_state(workspace: &Path, team_state: &Value) -> Result<()
     // 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(workspace, &merged);
+        return save_runtime_state_with_deleted_agents(workspace, &merged, deleted_agent_ids);
     }
     // teams = deepcopy(incoming_teams or existing_teams)
     let mut teams = match incoming_teams {
@@ -387,7 +511,7 @@ pub fn save_team_scoped_state(workspace: &Path, team_state: &Value) -> Result<()
     if merged.get("teams").and_then(Value::as_object).is_some_and(Map::is_empty) {
         merged.remove("teams");
     }
-    save_runtime_state(workspace, &Value::Object(merged))
+    save_runtime_state_with_deleted_agents(workspace, &Value::Object(merged), deleted_agent_ids)
 }
 
 // ---- helpers ----

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

@@ -98,6 +98,185 @@
         items.iter().map(|s| (*s).to_string()).collect()
     }
 
+    struct EnvGuard {
+        saved: Vec<(String, Option<String>)>,
+    }
+
+    impl EnvGuard {
+        fn apply(vars: &[(&str, Option<&str>)]) -> Self {
+            let saved = vars.iter().map(|(k, _)| ((*k).to_string(), std::env::var(k).ok())).collect();
+            for (k, v) in vars {
+                match v {
+                    Some(val) => std::env::set_var(k, val),
+                    None => std::env::remove_var(k),
+                }
+            }
+            Self { saved }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for (k, v) in &self.saved {
+                match v {
+                    Some(val) => std::env::set_var(k, val),
+                    None => std::env::remove_var(k),
+                }
+            }
+        }
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn leader_receiver_endpoint_from_tmux_env_preserves_full_socket_path() {
+        let leader_socket = "/tmp/ta-leader-root/tmux-501/dl2f";
+        let _env = EnvGuard::apply(&[
+            ("TMUX", Some("/tmp/ta-leader-root/tmux-501/dl2f,12345,0")),
+            ("TMUX_TMPDIR", Some("/tmp/ta-coordinator-root")),
+        ]);
+
+        assert_eq!(
+            super::socket_name_from_tmux_env().as_deref(),
+            Some(leader_socket),
+            "leader receivers must persist the exact tmux endpoint from $TMUX; a short -L socket \
+             name is re-rooted under the coordinator's TMUX_TMPDIR and cannot reach an external \
+             leader pane"
+        );
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn leader_receiver_endpoint_from_tmux_env_rejects_short_socket_name() {
+        let _env = EnvGuard::apply(&[
+            ("TMUX", Some("dl9aa40c88,12345,0")),
+            ("TMUX_TMPDIR", Some("/tmp/ta-coordinator-root")),
+        ]);
+
+        assert_eq!(
+            super::socket_name_from_tmux_env(),
+            None,
+            "leader_receiver.tmux_socket is a durable physical endpoint: a short socket name from \
+             $TMUX must not be persisted because tmux -L <short> is re-rooted under the coordinator"
+        );
+    }
+
+    #[test]
+    fn leader_receiver_delivery_uses_full_socket_endpoint_not_short_l_reconstruction() {
+        let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
+        let delivery = std::fs::read_to_string(manifest.join("src/messaging/delivery.rs")).unwrap();
+        let leader_receiver =
+            std::fs::read_to_string(manifest.join("src/messaging/leader_receiver.rs")).unwrap();
+        let tmux_backend = std::fs::read_to_string(manifest.join("src/tmux_backend.rs")).unwrap();
+
+        assert!(
+            tmux_backend.contains("\"-S\""),
+            "tmux backend must support `tmux -S <full-socket-path>` for persisted external leader \
+             endpoints; `-L <short-name>` is not enough when leader and coordinator TMUX_TMPDIR differ"
+        );
+        assert!(
+            !delivery.contains("TmuxBackend::for_socket_name(socket)"),
+            "worker->leader delivery must not reconstruct an external leader endpoint with \
+             `tmux -L <short-name>`; it must use the persisted full socket path endpoint"
+        );
+        assert!(
+            !leader_receiver.contains("TmuxBackend::for_socket_name(socket)"),
+            "leader_receiver live checks must verify the same full socket endpoint used by delivery, \
+            not a short socket name resolved under the coordinator's socket root"
+        );
+    }
+
+    #[test]
+    fn leader_receiver_full_endpoint_liveness_list_and_inject_use_s_path_command_shape() {
+        let endpoint = "/private/tmp/tmux-501/default";
+        let stdout = "%7\tteam-x\t0\tleader\t0\t/dev/ttys003\tbash\t1\t/Users/me/work\t1\t0\n";
+        let (be, rec, _stdin) = {
+            let recorded = Arc::new(Mutex::new(Vec::new()));
+            let stdin_recorded = Arc::new(Mutex::new(Vec::new()));
+            let runner = MockCommandRunner {
+                recorded: Arc::clone(&recorded),
+                stdin_recorded: Arc::clone(&stdin_recorded),
+                queue: Mutex::new(
+                    vec![
+                        MockResp::Out(ok(stdout)),
+                        MockResp::Out(ok("%7\n")),
+                        MockResp::Out(ok("")),
+                        MockResp::Out(ok("")),
+                        MockResp::Out(ok("")),
+                    ]
+                    .into_iter()
+                    .collect(),
+                ),
+                default: MockResp::Out(ok("")),
+            };
+            (
+                TmuxBackend::with_runner_for_tmux_endpoint(Box::new(runner), endpoint),
+                recorded,
+                stdin_recorded,
+            )
+        };
+
+        let _ = be.list_targets().expect("list_targets via endpoint");
+        let _ = be.liveness(&PaneId::new("%7")).expect("liveness via endpoint");
+        let _ = be
+            .inject(
+                &Target::Pane(PaneId::new("%7")),
+                &InjectPayload::Text("hello leader".to_string()),
+                Key::Enter,
+                true,
+            )
+            .expect("inject via endpoint");
+
+        let calls = rec.lock().unwrap().clone();
+        assert!(
+            calls.len() >= 5,
+            "fixture must exercise list-panes, display-message, buffer/paste, and send-keys; got {calls:?}"
+        );
+        for call in &calls {
+            assert!(
+                call.starts_with(&["tmux".to_string(), "-S".to_string(), endpoint.to_string()]),
+                "leader receiver list/liveness/inject must use tmux -S <full socket path>; got {call:?}"
+            );
+            assert!(
+                !call.windows(2).any(|w| w == ["-L".to_string(), endpoint.to_string()]),
+                "leader receiver full endpoint must never be reconstructed with -L; got {call:?}"
+            );
+        }
+        assert!(
+            calls.iter().any(|call| call.iter().any(|arg| arg == "list-panes"))
+                && calls.iter().any(|call| call.iter().any(|arg| arg == "display-message"))
+                && calls.iter().any(|call| call.iter().any(|arg| arg == "paste-buffer"))
+                && calls.iter().any(|call| call.iter().any(|arg| arg == "send-keys")),
+            "contract must cover liveness/list/inject command shapes; got {calls:?}"
+        );
+    }
+
+    #[test]
+    fn leader_receiver_short_endpoint_must_not_reconstruct_tmux_l_socket() {
+        let endpoint = "dl9aa40c88";
+        let (be, rec) = {
+            let recorded = Arc::new(Mutex::new(Vec::new()));
+            let runner = MockCommandRunner {
+                recorded: Arc::clone(&recorded),
+                stdin_recorded: Arc::new(Mutex::new(Vec::new())),
+                queue: Mutex::new(vec![MockResp::Out(ok(""))].into_iter().collect()),
+                default: MockResp::Out(ok("")),
+            };
+            (
+                TmuxBackend::with_runner_for_tmux_endpoint(Box::new(runner), endpoint),
+                recorded,
+            )
+        };
+
+        let _ = be.list_targets().expect("short endpoint should not become -L");
+
+        let calls = rec.lock().unwrap().clone();
+        assert!(
+            calls.iter().all(|call| !call.windows(2).any(|w| w == ["-L".to_string(), endpoint.to_string()])),
+            "non-canonical leader endpoints must be rejected or left unbound, never reconstructed as \
+             tmux -L <short> under the coordinator socket root; calls={calls:?}"
+        );
+    }
+
     // ── 1. has_session: exit 0 -> true, exit 1 -> false; argv = `tmux has-session -t <s>` ──────────
     #[test]
     fn has_session_argv_and_exit_code_maps_to_bool() {