@team-agent/installer 0.5.51 → 0.5.53

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

@@ -3,8 +3,11 @@
 
 use std::collections::BTreeSet;
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
 
 use crate::message_store::MessageStore;
 use crate::model::enums::PaneLiveness;
@@ -357,6 +360,29 @@ fn push_state_tmux_endpoints(state: &Value, out: &mut BTreeSet<String>) {
     }
 }
 
+fn state_records_pane_endpoint(state: &Value, pane_id: &str, endpoint: &str) -> bool {
+    let record_matches = |record: &Value| {
+        record.get("pane_id").and_then(Value::as_str) == Some(pane_id)
+            && record
+                .get("tmux_socket")
+                .and_then(Value::as_str)
+                .is_some_and(|recorded| tmux_endpoints_match(recorded, endpoint))
+    };
+    ["team_owner", "leader_receiver"]
+        .iter()
+        .any(|key| state.get(*key).is_some_and(&record_matches))
+        || state
+            .get("teams")
+            .and_then(Value::as_object)
+            .is_some_and(|teams| {
+                teams.values().any(|team| {
+                    ["team_owner", "leader_receiver"]
+                        .iter()
+                        .any(|key| team.get(*key).is_some_and(&record_matches))
+                })
+            })
+}
+
 fn requeue_exhausted_watchers_after_attach(
     workspace: &Path,
     state: &Value,
@@ -489,41 +515,50 @@ pub fn claim_leader(
         .unwrap_or_default();
     let raw_state = crate::state::persist::load_runtime_state_without_migrations(workspace)?;
     let event_log = crate::event_log::EventLog::new(workspace);
+    let active_team = crate::messaging::leader_receiver::active_team_key(workspace, &raw_state);
+    let requested_team = team
+        .filter(|team| !team.is_empty())
+        .or_else(|| {
+            raw_state
+                .get("active_team_key")
+                .and_then(Value::as_str)
+                .filter(|team| !team.is_empty())
+        })
+        .unwrap_or(active_team.as_str());
+    let team_id = TeamKey::new(requested_team.to_string());
     let targets = claim_leader_targets(workspace, &raw_state);
-    let caller_candidate = targets
-        .iter()
-        .filter(|target| target.info.pane_id.as_str() == caller)
-        .min_by_key(|target| target.source.priority());
+    let caller_candidate =
+        select_claim_authority(workspace, &raw_state, team_id.as_str(), &targets, &caller);
     let caller_pane_info = caller_candidate.map(|target| &target.info);
-    let caller_target = caller_candidate.and_then(|target| {
-        claim_target_from_pane_info(workspace, &target.info).map(|mut claim_target| {
-            claim_target.endpoint = target.endpoint.clone();
+    let observed_endpoint = caller_candidate.and_then(|candidate| {
+        authoritative_observed_endpoint(workspace, &raw_state, &targets, candidate)
+    });
+    let mut caller_target = caller_candidate.and_then(|target| {
+        claim_target_from_pane_info(&target.info).map(|mut claim_target| {
+            claim_target.endpoint.clone_from(&observed_endpoint);
             claim_target
         })
     });
-    let env_team = std::env::var("TEAM_AGENT_TEAM_ID")
-        .ok()
-        .filter(|team| !team.is_empty());
-    let explicit_team = team.filter(|team| !team.is_empty());
-    let active_team = crate::messaging::leader_receiver::active_team_key(workspace, &raw_state);
-    let active_team_from_state = raw_state
-        .get("active_team_key")
-        .and_then(Value::as_str)
-        .filter(|team| !team.is_empty());
-    let requested_team = explicit_team
-        .or(active_team_from_state)
-        .or_else(|| {
-            caller_target
-                .as_ref()
-                .and_then(|target| target.team_id.as_deref())
-        })
-        .or(env_team.as_deref())
-        .or(Some(active_team.as_str()));
-    let team_id = TeamKey::new(
-        requested_team
-            .map(str::to_string)
-            .unwrap_or_else(|| active_team.clone()),
-    );
+    if let (Some(candidate), Some(target)) = (caller_candidate, caller_target.as_mut()) {
+        if candidate.info.current_path.as_deref().is_some_and(|path| {
+            !crate::messaging::leader_channel::path_is_in_workspace(path, workspace)
+        }) {
+            let endpoint = target.endpoint.as_deref().ok_or_else(|| {
+                LeaderError::Validation(
+                    "explicit cross-workspace claim requires a canonical tmux endpoint".to_string(),
+                )
+            })?;
+            if !Path::new(endpoint).is_absolute() {
+                return Err(LeaderError::Validation(
+                    "explicit cross-workspace claim requires an absolute tmux endpoint".to_string(),
+                ));
+            }
+            let nonce = next_pane_binding_nonce(workspace, endpoint, &candidate.info.pane_id);
+            target.scope_authority = Some("explicit_claim".to_string());
+            target.authorized_team_workspace = Some(canonical_workspace(workspace));
+            target.binding_nonce = Some(nonce);
+        }
+    }
     let scoped_team = if team_id.as_str() == active_team
         || raw_state
             .get("teams")
@@ -695,6 +730,7 @@ fn claim_lease_no_incident_with_target(
     let non_empty_caller_pane = NonEmptyPaneId::try_from_pane(caller_pane)?;
     let bound_endpoint_matches_caller = bound_endpoint_matches_current_process(state);
     if bound_pane_id.as_deref() == Some(caller_pane.as_str()) && bound_endpoint_matches_caller {
+        write_claim_target_pane_nonce(caller_target)?;
         let current_endpoint = crate::tmux_backend::socket_name_from_tmux_env();
         let observed_endpoint = caller_target.and_then(|target| target.endpoint.as_deref());
         let convergence_candidate = observed_endpoint.or(current_endpoint.as_deref());
@@ -712,25 +748,47 @@ fn claim_lease_no_incident_with_target(
             candidate_source,
             pre_epoch,
         );
-        if converged {
+        let observation_refreshed = caller_pane_info.is_some_and(|pane_info| {
+            refresh_already_bound_receiver_observation(
+                state,
+                pane_info,
+                observed_endpoint.or(current_endpoint.as_deref()),
+                scoped_team.or(team),
+                caller_target,
+            )
+        });
+        if converged || observation_refreshed {
             write_claim_state(workspace, state, scoped_team, team)?;
-            topology_convergence = verify_persisted_topology_convergence(
-                workspace,
-                team_id.as_str(),
-                topology_convergence,
-                pre_epoch,
-            )?;
-            if topology_convergence
-                .as_ref()
-                .and_then(|metadata| metadata.get("status"))
-                .and_then(Value::as_str)
-                != Some("converged")
-            {
-                return Ok(convergence_persistence_refusal(
+            if observation_refreshed {
+                event_log.write(
+                    "leader_receiver.observation_refreshed",
+                    json!({
+                        "pane_id": caller_pane.as_str(),
+                        "owner_epoch": pre_epoch.0,
+                        "owner_changed": false,
+                        "source": "claim_leader_already_bound",
+                    }),
+                )?;
+            }
+            if converged {
+                topology_convergence = verify_persisted_topology_convergence(
+                    workspace,
+                    team_id.as_str(),
                     topology_convergence,
                     pre_epoch,
-                    Some(caller_pane.clone()),
-                ));
+                )?;
+                if topology_convergence
+                    .as_ref()
+                    .and_then(|metadata| metadata.get("status"))
+                    .and_then(Value::as_str)
+                    != Some("converged")
+                {
+                    return Ok(convergence_persistence_refusal(
+                        topology_convergence,
+                        pre_epoch,
+                        Some(caller_pane.clone()),
+                    ));
+                }
             }
         }
         return Ok(LeaseResult {
@@ -862,6 +920,7 @@ fn claim_lease_no_incident_with_target(
     } else {
         LeaseReason::VacantAcquired
     };
+    write_claim_target_pane_nonce(caller_target)?;
     let mut identity = leader_identity_context(workspace, Some(team_id.as_str()), Some(state))?;
     if let Some(uuid) = caller_target.and_then(|target| target.leader_session_uuid.as_ref()) {
         identity.leader_session_uuid = uuid.clone();
@@ -877,6 +936,13 @@ fn claim_lease_no_incident_with_target(
         Discovery::ClaimLeader,
         caller_target.and_then(|target| target.pane_info.clone()),
     );
+    if let Some(target) = caller_target {
+        receiver.scope_authority.clone_from(&target.scope_authority);
+        receiver
+            .authorized_team_workspace
+            .clone_from(&target.authorized_team_workspace);
+        receiver.binding_nonce.clone_from(&target.binding_nonce);
+    }
     if let Some(endpoint) = observed_endpoint.as_ref() {
         receiver.tmux_socket = Some(endpoint.clone());
     }
@@ -1002,6 +1068,8 @@ fn apply_endpoint_convergence(
                 "new_tmux_endpoint": candidate_endpoint,
                 "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
+                "persisted": false,
+                "checked_paths": convergence_checked_paths(team_id.as_str()),
             })),
             false,
         ),
@@ -1017,6 +1085,8 @@ fn apply_endpoint_convergence(
                 "reason": reason,
                 "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
+                "persisted": false,
+                "checked_paths": convergence_checked_paths(team_id.as_str()),
                 "action": format!(
                     "old tmux endpoint {old_endpoint} still has this team's session or pane tuple; run team-agent diagnose --json before retrying restart"
                 ),
@@ -1292,32 +1362,89 @@ struct LeaderClaimTarget {
     team_id: Option<String>,
     pane_info: Option<PaneInfo>,
     endpoint: Option<String>,
+    scope_authority: Option<String>,
+    authorized_team_workspace: Option<PathBuf>,
+    binding_nonce: Option<String>,
 }
 
 #[derive(Clone)]
 struct ClaimLeaderTargetCandidate {
     info: PaneInfo,
     endpoint: Option<String>,
-    source: ClaimLeaderTargetSource,
 }
 
-#[derive(Clone, Copy, PartialEq, Eq)]
-enum ClaimLeaderTargetSource {
-    StateRecorded,
-    Workspace,
-    CurrentTmux,
-    Default,
+fn select_claim_authority<'a>(
+    workspace: &Path,
+    state: &Value,
+    team_id: &str,
+    targets: &'a [ClaimLeaderTargetCandidate],
+    caller: &str,
+) -> Option<&'a ClaimLeaderTargetCandidate> {
+    targets
+        .iter()
+        .filter(|target| {
+            target.info.pane_id.as_str() == caller
+                && target.info.active
+                && super::attribute_pane_provider(&target.info).is_some()
+        })
+        .min_by_key(|target| {
+            let recorded = target
+                .endpoint
+                .as_deref()
+                .is_some_and(|endpoint| state_records_pane_endpoint(state, caller, endpoint));
+            let in_workspace = target.info.current_path.as_deref().is_some_and(|path| {
+                crate::messaging::leader_channel::path_is_in_workspace(path, workspace)
+            });
+            let team_affinity = match target
+                .info
+                .leader_env
+                .get("TEAM_AGENT_TEAM_ID")
+                .filter(|value| !value.is_empty())
+            {
+                Some(observed) if observed == team_id => 0,
+                None => 1,
+                Some(_) => 2,
+            };
+            (
+                !recorded,
+                !in_workspace,
+                team_affinity,
+                target.info.pane_pid.unwrap_or(u32::MAX),
+                target.info.session.as_str().to_string(),
+                target.info.window_index.unwrap_or(u32::MAX),
+                target.info.pane_index.unwrap_or(u32::MAX),
+                target.info.tty.clone().unwrap_or_default(),
+            )
+        })
 }
 
-impl ClaimLeaderTargetSource {
-    fn priority(self) -> u8 {
-        match self {
-            Self::StateRecorded => 0,
-            Self::Workspace => 1,
-            Self::CurrentTmux => 2,
-            Self::Default => 3,
-        }
-    }
+fn authoritative_observed_endpoint(
+    workspace: &Path,
+    state: &Value,
+    targets: &[ClaimLeaderTargetCandidate],
+    authority: &ClaimLeaderTargetCandidate,
+) -> Option<String> {
+    let recorded = state_recorded_tmux_endpoints(state);
+    let workspace_name = crate::tmux_backend::socket_name_for_workspace(workspace);
+    let workspace_path = crate::tmux_backend::socket_path_for_workspace(workspace);
+    targets
+        .iter()
+        .filter(|candidate| candidate.info == authority.info)
+        .filter_map(|candidate| candidate.endpoint.as_ref())
+        .min_by_key(|endpoint| {
+            let canonical_workspace_endpoint = endpoint.as_str() == workspace_name
+                || workspace_path
+                    .as_ref()
+                    .is_some_and(|path| path.to_string_lossy().as_ref() == endpoint.as_str());
+            (
+                !state_records_pane_endpoint(state, authority.info.pane_id.as_str(), endpoint),
+                !recorded.contains(endpoint.as_str()),
+                !canonical_workspace_endpoint,
+                !Path::new(endpoint.as_str()).is_absolute(),
+                endpoint.as_str(),
+            )
+        })
+        .cloned()
 }
 
 fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTargetCandidate> {
@@ -1333,7 +1460,6 @@ fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTarge
                 .map(|info| ClaimLeaderTargetCandidate {
                     info,
                     endpoint: resolved_endpoint.clone(),
-                    source: ClaimLeaderTargetSource::CurrentTmux,
                 }),
         );
     }
@@ -1348,7 +1474,6 @@ fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTarge
                 .map(|info| ClaimLeaderTargetCandidate {
                     info,
                     endpoint: resolved_endpoint.clone(),
-                    source: ClaimLeaderTargetSource::StateRecorded,
                 }),
         );
     }
@@ -1362,7 +1487,6 @@ fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTarge
             .map(|info| ClaimLeaderTargetCandidate {
                 info,
                 endpoint: workspace_endpoint.clone(),
-                source: ClaimLeaderTargetSource::Workspace,
             }),
     );
     let default_backend = crate::transport_factory::tmux_default_transport();
@@ -1375,21 +1499,16 @@ fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTarge
             .map(|info| ClaimLeaderTargetCandidate {
                 info,
                 endpoint: default_endpoint.clone(),
-                source: ClaimLeaderTargetSource::Default,
             }),
     );
     targets
 }
 
-fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<LeaderClaimTarget> {
+fn claim_target_from_pane_info(target: &PaneInfo) -> Option<LeaderClaimTarget> {
     if !target.active {
         return None;
     }
     let provider = super::attribute_pane_provider(target)?;
-    let current_path = target.current_path.as_deref()?;
-    if !crate::state::owner_gate::workspace_paths_match(current_path, workspace) {
-        return None;
-    }
     Some(LeaderClaimTarget {
         provider,
         leader_session_uuid: target_leader_session_uuid(target),
@@ -1400,9 +1519,74 @@ fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<Le
             .cloned(),
         pane_info: Some(target.clone()),
         endpoint: None,
+        scope_authority: None,
+        authorized_team_workspace: None,
+        binding_nonce: None,
     })
 }
 
+fn workspace_claim_target_from_pane_info(
+    workspace: &Path,
+    target: &PaneInfo,
+) -> Option<LeaderClaimTarget> {
+    let current_path = target.current_path.as_deref()?;
+    if !crate::state::owner_gate::workspace_paths_match(current_path, workspace) {
+        return None;
+    }
+    claim_target_from_pane_info(target)
+}
+
+fn write_claim_target_pane_nonce(target: Option<&LeaderClaimTarget>) -> Result<(), LeaderError> {
+    let Some(target) = target.filter(|target| target.scope_authority.is_some()) else {
+        return Ok(());
+    };
+    let endpoint = target.endpoint.as_deref().ok_or_else(|| {
+        LeaderError::Validation("explicit claim is missing its tmux endpoint".to_string())
+    })?;
+    let pane = target
+        .pane_info
+        .as_ref()
+        .map(|info| &info.pane_id)
+        .ok_or_else(|| {
+            LeaderError::Validation("explicit claim is missing its pane observation".to_string())
+        })?;
+    let nonce = target.binding_nonce.as_deref().ok_or_else(|| {
+        LeaderError::Validation("explicit claim is missing its pane binding nonce".to_string())
+    })?;
+    tmux_backend_for_endpoint(endpoint)
+        .set_pane_binding_nonce(pane, nonce)
+        .map_err(|error| {
+            LeaderError::Validation(format!(
+                "failed to bind the explicit leader pane instance: {error}"
+            ))
+        })
+}
+
+fn canonical_workspace(workspace: &Path) -> PathBuf {
+    workspace
+        .canonicalize()
+        .unwrap_or_else(|_| workspace.to_path_buf())
+}
+
+fn next_pane_binding_nonce(workspace: &Path, endpoint: &str, pane: &PaneId) -> String {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |duration| duration.as_nanos());
+    let counter = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let material = format!(
+        "{}\0{endpoint}\0{}\0{}\0{nanos}\0{counter}",
+        canonical_workspace(workspace).display(),
+        pane.as_str(),
+        std::process::id(),
+    );
+    let digest = Sha256::digest(material.as_bytes());
+    digest[..16]
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect()
+}
+
 fn target_leader_session_uuid(target: &PaneInfo) -> Option<crate::model::ids::LeaderSessionUuid> {
     target
         .leader_env
@@ -1426,7 +1610,7 @@ fn validate_attach_target(
     // a real Codex/Claude/Copilot binary. This is a targeted escape
     // hatch — `Provider::Fake` is not selectable from the user-facing
     // provider list, only wired in test/fixture flows.
-    let claim_target = match claim_target_from_pane_info(workspace, target) {
+    let claim_target = match workspace_claim_target_from_pane_info(workspace, target) {
         Some(target) => Some(target),
         None if matches!(requested_provider, Provider::Fake) => None,
         None => return Err("leader_pane_validation_failed"),
@@ -1532,7 +1716,7 @@ impl TargetScanLiveness {
         let live_panes = targets
             .iter()
             .filter_map(|target| {
-                let claim_target = claim_target_from_pane_info(workspace, target)?;
+                let claim_target = workspace_claim_target_from_pane_info(workspace, target)?;
                 if let Some(owner_uuid) = owner_uuid.as_deref() {
                     let target_uuid = claim_target.leader_session_uuid.as_ref()?.as_str();
                     if target_uuid != owner_uuid {
@@ -1635,6 +1819,9 @@ fn make_receiver(
         pane_tty: target.as_ref().and_then(|t| t.tty.clone()),
         pane_current_command: target.as_ref().and_then(|t| t.current_command.clone()),
         tmux_socket: crate::tmux_backend::socket_name_from_tmux_env(),
+        scope_authority: None,
+        authorized_team_workspace: None,
+        binding_nonce: None,
         fingerprint: target.as_ref().map(receiver_fingerprint),
         leader_session_uuid: Some(uuid.clone()),
         owner_epoch: Some(epoch),
@@ -1659,6 +1846,132 @@ fn receiver_fingerprint(target: &PaneInfo) -> String {
     )
 }
 
+fn refresh_already_bound_receiver_observation(
+    state: &mut Value,
+    observed: &PaneInfo,
+    observed_endpoint: Option<&str>,
+    team_key: Option<&str>,
+    claim_target: Option<&LeaderClaimTarget>,
+) -> bool {
+    let attached_at = now_ts();
+    let mut refreshed = state
+        .get_mut("leader_receiver")
+        .and_then(Value::as_object_mut)
+        .is_some_and(|receiver| {
+            refresh_receiver_observation(
+                receiver,
+                observed,
+                observed_endpoint,
+                attached_at.as_str(),
+                claim_target,
+            )
+        });
+    if let Some(team_key) = team_key {
+        refreshed |= state
+            .get_mut("teams")
+            .and_then(|teams| teams.get_mut(team_key))
+            .and_then(|entry| entry.get_mut("leader_receiver"))
+            .and_then(Value::as_object_mut)
+            .is_some_and(|receiver| {
+                refresh_receiver_observation(
+                    receiver,
+                    observed,
+                    observed_endpoint,
+                    attached_at.as_str(),
+                    claim_target,
+                )
+            });
+    }
+    refreshed
+}
+
+fn refresh_receiver_observation(
+    receiver: &mut serde_json::Map<String, Value>,
+    observed: &PaneInfo,
+    observed_endpoint: Option<&str>,
+    attached_at: &str,
+    claim_target: Option<&LeaderClaimTarget>,
+) -> bool {
+    let before = Value::Object(receiver.clone());
+    receiver.insert(
+        "session_name".to_string(),
+        Value::String(observed.session.as_str().to_string()),
+    );
+    receiver.insert(
+        "window_index".to_string(),
+        observed
+            .window_index
+            .map(|value| Value::String(value.to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "window_name".to_string(),
+        observed
+            .window_name
+            .as_ref()
+            .map(|value| Value::String(value.as_str().to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_index".to_string(),
+        observed
+            .pane_index
+            .map(|value| Value::String(value.to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_tty".to_string(),
+        observed
+            .tty
+            .as_ref()
+            .map(|value| Value::String(value.clone()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_current_command".to_string(),
+        observed
+            .current_command
+            .as_ref()
+            .map(|value| Value::String(value.clone()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "fingerprint".to_string(),
+        Value::String(receiver_fingerprint(observed)),
+    );
+    if let Some(endpoint) = observed_endpoint.filter(|value| !value.is_empty()) {
+        receiver.insert(
+            "tmux_socket".to_string(),
+            Value::String(endpoint.to_string()),
+        );
+    }
+    if let Some(target) = claim_target.filter(|target| target.scope_authority.is_some()) {
+        receiver.insert(
+            "scope_authority".to_string(),
+            Value::String(target.scope_authority.clone().unwrap_or_default()),
+        );
+        receiver.insert(
+            "authorized_team_workspace".to_string(),
+            Value::String(
+                target
+                    .authorized_team_workspace
+                    .as_deref()
+                    .map(|path| path.to_string_lossy().into_owned())
+                    .unwrap_or_default(),
+            ),
+        );
+        receiver.insert(
+            "binding_nonce".to_string(),
+            Value::String(target.binding_nonce.clone().unwrap_or_default()),
+        );
+    }
+    receiver.insert(
+        "attached_at".to_string(),
+        Value::String(attached_at.to_string()),
+    );
+    Value::Object(receiver.clone()) != before
+}
+
 fn make_owner(
     provider: Provider,
     pane: &NonEmptyPaneId,
@@ -2124,6 +2437,22 @@ fn readable_team_snapshot_path(w: &BP, n: &str) -> BF /* B0_DIAGNOSTIC_LEGACY_SN
 mod tests {
     use super::*;
 
+    fn observed_pane() -> PaneInfo {
+        PaneInfo {
+            pane_id: PaneId::new("%7"),
+            session: crate::transport::SessionName::new("new-session"),
+            window_index: Some(3),
+            window_name: Some(crate::transport::WindowName::new("new-window")),
+            pane_index: Some(1),
+            tty: Some("/dev/ttys007".to_string()),
+            current_command: Some("codex".to_string()),
+            current_path: None,
+            active: true,
+            pane_pid: Some(700),
+            leader_env: std::collections::BTreeMap::new(),
+        }
+    }
+
     #[test]
     fn attribute_command_provider_recognizes_copilot() {
         assert_eq!(
@@ -2135,4 +2464,128 @@ mod tests {
             Some(Provider::Copilot)
         );
     }
+
+    #[test]
+    fn already_bound_refresh_updates_observations_without_reclaiming() {
+        let mut state = json!({
+            "leader_receiver": {
+                "status": "attached",
+                "pane_id": "%7",
+                "owner_epoch": 10,
+                "owner_agent_id": "leader",
+                "session_name": "old-session",
+                "pane_tty": "/dev/old",
+                "attached_at": "2026-01-01T00:00:00Z"
+            },
+            "teams": {"team-a": {"leader_receiver": {
+                "status": "attached",
+                "pane_id": "%7",
+                "owner_epoch": 10,
+                "owner_agent_id": "leader",
+                "session_name": "old-session",
+                "pane_tty": "/dev/old",
+                "attached_at": "2026-01-01T00:00:00Z"
+            }}}
+        });
+
+        assert!(refresh_already_bound_receiver_observation(
+            &mut state,
+            &observed_pane(),
+            Some("/tmp/team-agent-live.sock"),
+            Some("team-a"),
+            None,
+        ));
+        let receiver = &state["leader_receiver"];
+        assert_eq!(receiver["owner_epoch"], json!(10));
+        assert_eq!(receiver["owner_agent_id"], json!("leader"));
+        assert_eq!(receiver["session_name"], json!("new-session"));
+        assert_eq!(receiver["window_name"], json!("new-window"));
+        assert_eq!(receiver["pane_tty"], json!("/dev/ttys007"));
+        assert_eq!(receiver["tmux_socket"], json!("/tmp/team-agent-live.sock"));
+        assert_ne!(receiver["attached_at"], json!("2026-01-01T00:00:00Z"));
+        assert_eq!(
+            state["teams"]["team-a"]["leader_receiver"]["session_name"],
+            json!("new-session")
+        );
+        assert_eq!(
+            state["teams"]["team-a"]["leader_receiver"]["owner_epoch"],
+            json!(10)
+        );
+    }
+
+    #[test]
+    fn already_bound_explicit_claim_persists_cross_workspace_authority() {
+        let mut state = json!({
+            "leader_receiver": {"status": "attached", "pane_id": "%7"},
+            "teams": {"team-a": {"leader_receiver": {
+                "status": "attached", "pane_id": "%7"
+            }}}
+        });
+        let target = LeaderClaimTarget {
+            provider: Provider::Codex,
+            leader_session_uuid: None,
+            team_id: Some("team-a".to_string()),
+            pane_info: Some(observed_pane()),
+            endpoint: Some("/tmp/team-agent-live.sock".to_string()),
+            scope_authority: Some("explicit_claim".to_string()),
+            authorized_team_workspace: Some(PathBuf::from("/tmp/workspace-a")),
+            binding_nonce: Some("nonce-7".to_string()),
+        };
+
+        assert!(refresh_already_bound_receiver_observation(
+            &mut state,
+            &observed_pane(),
+            Some("/tmp/team-agent-live.sock"),
+            Some("team-a"),
+            Some(&target),
+        ));
+        for receiver in [
+            &state["leader_receiver"],
+            &state["teams"]["team-a"]["leader_receiver"],
+        ] {
+            assert_eq!(receiver["scope_authority"], json!("explicit_claim"));
+            assert_eq!(
+                receiver["authorized_team_workspace"],
+                json!("/tmp/workspace-a")
+            );
+            assert_eq!(receiver["binding_nonce"], json!("nonce-7"));
+        }
+    }
+
+    #[test]
+    fn pane_binding_nonce_rotates_per_explicit_claim() {
+        let workspace = Path::new("/tmp/workspace-a");
+        let endpoint = "/tmp/team-agent-live.sock";
+        let pane = PaneId::new("%7");
+        let first = next_pane_binding_nonce(workspace, endpoint, &pane);
+        let second = next_pane_binding_nonce(workspace, endpoint, &pane);
+        assert_eq!(first.len(), 32);
+        assert!(first.chars().all(|ch| ch.is_ascii_hexdigit()));
+        assert_ne!(first, second);
+    }
+
+    #[test]
+    fn claim_authority_preserves_recorded_absolute_observation() {
+        let workspace = Path::new("/tmp/workspace-a");
+        let absolute = "/tmp/tmux-501/ta-live";
+        let state = json!({
+            "leader_receiver": {"pane_id": "%9", "tmux_socket": absolute}
+        });
+        let pane = observed_pane();
+        let targets = vec![
+            ClaimLeaderTargetCandidate {
+                info: pane.clone(),
+                endpoint: Some(crate::tmux_backend::socket_name_for_workspace(workspace)),
+            },
+            ClaimLeaderTargetCandidate {
+                info: pane,
+                endpoint: Some(absolute.to_string()),
+            },
+        ];
+
+        assert_eq!(
+            authoritative_observed_endpoint(workspace, &state, &targets, &targets[0]).as_deref(),
+            Some(absolute)
+        );
+    }
 }