@team-agent/installer 0.5.73 → 0.5.75

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

@@ -26,6 +26,41 @@ use super::{
 
 // ── leader::lease — attach / claim / takeover / autobind / readopt 统一 CAS 路径 ──
 
+#[derive(Debug, Clone)]
+pub(crate) struct AppliedLeaderGrant {
+    pub(crate) owner: Value,
+    pub(crate) receiver: Value,
+}
+
+#[derive(Debug)]
+pub(crate) struct AttachLeaderError {
+    source: LeaderError,
+    applied_grant: Option<AppliedLeaderGrant>,
+}
+
+impl AttachLeaderError {
+    fn with_applied(source: LeaderError, applied_grant: Option<AppliedLeaderGrant>) -> Self {
+        Self {
+            source,
+            applied_grant,
+        }
+    }
+
+    pub(crate) fn into_parts(self) -> (LeaderError, Option<AppliedLeaderGrant>) {
+        (self.source, self.applied_grant)
+    }
+
+    fn into_error(self) -> LeaderError {
+        self.source
+    }
+}
+
+impl From<LeaderError> for AttachLeaderError {
+    fn from(source: LeaderError) -> Self {
+        Self::with_applied(source, None)
+    }
+}
+
 /// `attach_leader`(card §42;`__init__.py:19`)。手动 CLI attach;持 `LEADER_OWNERSHIP_LOCK`
 /// 整段临界区做 state 变更 + 事件 + 双写 + requeue exhausted watchers。
 pub fn attach_leader(
@@ -288,6 +323,23 @@ struct AttachLeaderTarget {
 
 fn attach_leader_targets(workspace: &Path, state: &Value) -> Vec<AttachLeaderTarget> {
     let mut targets = Vec::new();
+    // The caller's verified tmux server is authoritative for discovering its
+    // leader pane. Keep state-recorded worker endpoints as additional targets,
+    // but do not let a cross-socket pane-id collision hide the caller pane.
+    if let Some(endpoint) = crate::tmux_backend::socket_name_from_tmux_env() {
+        let backend = tmux_backend_for_endpoint(&endpoint);
+        let resolved_endpoint = backend.tmux_endpoint();
+        targets.extend(
+            backend
+                .list_targets()
+                .unwrap_or_default()
+                .into_iter()
+                .map(|info| AttachLeaderTarget {
+                    info,
+                    endpoint: resolved_endpoint.clone(),
+                }),
+        );
+    }
     for endpoint in state_recorded_tmux_endpoints(state) {
         let backend = tmux_backend_for_endpoint(&endpoint);
         let resolved_endpoint = backend.tmux_endpoint();
@@ -437,63 +489,140 @@ pub(crate) fn attach_leader_to_state(
     source: LeaseSource,
     require_current: bool,
 ) -> Result<(LeaderReceiver, Value), LeaderError> {
-    let _ = (source, require_current);
+    attach_leader_to_state_with_target_and_controls(
+        workspace,
+        state,
+        pane,
+        provider,
+        event_log,
+        source,
+        require_current,
+        None,
+        None,
+        None,
+        None,
+    )
+    .map_err(AttachLeaderError::into_error)
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn attach_leader_to_state_with_target(
+    workspace: &Path,
+    state: &mut Value,
+    pane: Option<&PaneId>,
+    provider: Provider,
+    event_log: &crate::event_log::EventLog,
+    source: LeaseSource,
+    require_current: bool,
+    caller_target: Option<&PaneInfo>,
+) -> Result<(LeaderReceiver, Value), LeaderError> {
+    attach_leader_to_state_with_target_and_controls(
+        workspace,
+        state,
+        pane,
+        provider,
+        event_log,
+        source,
+        require_current,
+        caller_target,
+        None,
+        None,
+        None,
+    )
+    .map_err(AttachLeaderError::into_error)
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn attach_leader_to_state_with_target_and_controls(
+    workspace: &Path,
+    state: &mut Value,
+    pane: Option<&PaneId>,
+    provider: Provider,
+    event_log: &crate::event_log::EventLog,
+    source: LeaseSource,
+    require_current: bool,
+    caller_target: Option<&PaneInfo>,
+    expected_owner: Option<&Value>,
+    expected_receiver: Option<&Value>,
+    nonce_writer: Option<&dyn Fn(&str, &PaneId, &str) -> Result<String, LeaderError>>,
+) -> Result<(LeaderReceiver, Value), AttachLeaderError> {
+    if expected_owner.is_some() != expected_receiver.is_some() {
+        return Err(AttachLeaderError::from(LeaderError::Validation(
+            "fresh caller CAS requires both expected owner and receiver".to_string(),
+        )));
+    }
     let pane_id = pane
         .cloned()
         .ok_or_else(|| LeaderError::Validation("tmux pane not found".to_string()))?;
     let non_empty_pane_id = NonEmptyPaneId::try_from_pane(&pane_id)?;
     let identity = leader_identity_context(workspace, None, Some(state))?;
     let epoch = current_owner_epoch(state);
-    let receiver = make_receiver(
+    let has_owner = state.get("team_owner").is_some();
+    let binding_epoch = if has_owner {
+        epoch
+    } else {
+        OwnerEpoch(epoch.0.saturating_add(1))
+    };
+    let mut receiver = make_receiver(
         provider,
         &non_empty_pane_id,
         &identity.leader_session_uuid,
-        epoch,
+        binding_epoch,
         Discovery::EnvPane,
         None,
     );
-    if state.get("team_owner").is_some() {
+    authorize_fresh_caller_receiver(
+        workspace,
+        &mut receiver,
+        &non_empty_pane_id,
+        source,
+        require_current,
+        caller_target,
+        nonce_writer,
+    )?;
+    let receiver_value = serde_json::to_value(&receiver).map_err(LeaderError::from)?;
+    if has_owner {
         write_receiver_to_state(state, &receiver)?;
     } else {
-        let next_epoch = OwnerEpoch(epoch.0.saturating_add(1));
-        let receiver = make_receiver(
-            provider,
-            &non_empty_pane_id,
-            &identity.leader_session_uuid,
-            next_epoch,
-            Discovery::EnvPane,
-            None,
-        );
-        let owner = make_owner(provider, &non_empty_pane_id, &identity, next_epoch);
+        let owner = make_owner(provider, &non_empty_pane_id, &identity, binding_epoch);
         write_binding_to_state(state, &receiver, &owner)?;
-        write_lease_dual_state(workspace, state)?;
-        event_log.write(
-            super::LeaderEvent::ReceiverAttached.name(),
-            json!({"pane_id": pane_id.as_str(), "owner_epoch": next_epoch.0}),
-        )?;
-        let team_id = TeamKey::new(crate::state::projection::team_state_key(state));
-        crate::messaging::watchers::recover_watchers_for_incident(
+    }
+    if let (Some(expected_owner), Some(expected_receiver)) = (expected_owner, expected_receiver) {
+        write_lease_dual_state_with_expected(
             workspace,
-            event_log,
-            &team_id,
-            &pane_id,
-            LeaderIncident::LeaderAttached,
+            state,
+            expected_owner,
+            expected_receiver,
         )?;
-        return Ok((receiver, json!({"ok": true})));
+    } else {
+        write_lease_dual_state(workspace, state)?;
     }
-    write_lease_dual_state(workspace, state)?;
-    event_log.write(
+    let applied_grant = state
+        .get("team_owner")
+        .cloned()
+        .map(|owner| AppliedLeaderGrant {
+            owner,
+            receiver: receiver_value,
+        });
+    if let Err(error) = event_log.write(
         super::LeaderEvent::ReceiverAttached.name(),
-        json!({"pane_id": pane_id.as_str(), "owner_epoch": epoch.0}),
-    )?;
+        json!({"pane_id": pane_id.as_str(), "owner_epoch": binding_epoch.0}),
+    ) {
+        return Err(AttachLeaderError::with_applied(
+            error.into(),
+            applied_grant.clone(),
+        ));
+    }
     let team_id = TeamKey::new(crate::state::projection::team_state_key(state));
-    crate::messaging::watchers::recover_watchers_for_incident(
+    if let Err(error) = crate::messaging::watchers::recover_watchers_for_incident(
         workspace,
         event_log,
         &team_id,
         &pane_id,
         LeaderIncident::LeaderAttached,
-    )?;
+    ) {
+        return Err(AttachLeaderError::with_applied(error.into(), applied_grant));
+    }
     Ok((receiver, json!({"ok": true})))
 }
 
@@ -554,7 +683,18 @@ pub fn claim_leader(
                     "explicit cross-workspace claim requires an absolute tmux endpoint".to_string(),
                 ));
             }
-            let nonce = next_pane_binding_nonce(workspace, endpoint, &candidate.info.pane_id);
+            // A live pane nonce identifies the pane instance, not this team's
+            // claim. Preserve it so another child team remains authorized.
+            let nonce = pane_binding_nonce_for_claim(
+                workspace,
+                endpoint,
+                &candidate.info.pane_id,
+                candidate
+                    .info
+                    .leader_env
+                    .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+                    .map(String::as_str),
+            );
             target.scope_authority = Some("explicit_claim".to_string());
             target.authorized_team_workspace = Some(canonical_workspace(workspace));
             target.binding_nonce = Some(nonce);
@@ -600,7 +740,7 @@ pub fn claim_leader(
         confirm,
         &event_log,
         &liveness,
-        caller_target.as_ref(),
+        caller_target.as_mut(),
         caller_pane_info,
         scoped_team.map(|_| team_id.as_str()),
     )?;
@@ -692,7 +832,7 @@ fn claim_lease_no_incident_with_target(
     confirm: bool,
     event_log: &crate::event_log::EventLog,
     liveness: &dyn crate::state::owner_gate::PaneLivenessProbe,
-    caller_target: Option<&LeaderClaimTarget>,
+    mut caller_target: Option<&mut LeaderClaimTarget>,
     caller_pane_info: Option<&PaneInfo>,
     scoped_team: Option<&str>,
 ) -> Result<LeaseResult, LeaderError> {
@@ -734,9 +874,13 @@ 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)?;
+        if let Some(target) = caller_target.as_deref_mut() {
+            write_claim_target_pane_nonce(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 observed_endpoint = caller_target
+            .as_deref()
+            .and_then(|target| target.endpoint.as_deref());
         let convergence_candidate = observed_endpoint.or(current_endpoint.as_deref());
         let candidate_source = if observed_endpoint.is_some() {
             Some("observed_target_endpoint")
@@ -758,7 +902,7 @@ fn claim_lease_no_incident_with_target(
                 pane_info,
                 observed_endpoint.or(current_endpoint.as_deref()),
                 scoped_team.or(team),
-                caller_target,
+                caller_target.as_deref(),
             )
         });
         if converged || observation_refreshed {
@@ -924,23 +1068,33 @@ fn claim_lease_no_incident_with_target(
     } else {
         LeaseReason::VacantAcquired
     };
-    write_claim_target_pane_nonce(caller_target)?;
+    if let Some(target) = caller_target.as_deref_mut() {
+        write_claim_target_pane_nonce(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()) {
+    if let Some(uuid) = caller_target
+        .as_deref()
+        .and_then(|target| target.leader_session_uuid.as_ref()) {
         identity.leader_session_uuid = uuid.clone();
     }
     let next_epoch = OwnerEpoch(pre_epoch.0.saturating_add(1));
-    let provider = caller_target.map_or_else(|| prior_provider(state), |target| target.provider);
-    let observed_endpoint = caller_target.and_then(|target| target.endpoint.clone());
+    let provider = caller_target
+        .as_deref()
+        .map_or_else(|| prior_provider(state), |target| target.provider);
+    let observed_endpoint = caller_target
+        .as_deref()
+        .and_then(|target| target.endpoint.clone());
     let mut receiver = make_receiver(
         provider,
         &non_empty_caller_pane,
         &identity.leader_session_uuid,
         next_epoch,
         Discovery::ClaimLeader,
-        caller_target.and_then(|target| target.pane_info.clone()),
+        caller_target
+            .as_deref()
+            .and_then(|target| target.pane_info.clone()),
     );
-    if let Some(target) = caller_target {
+    if let Some(target) = caller_target.as_deref() {
         receiver.scope_authority.clone_from(&target.scope_authority);
         receiver
             .authorized_team_workspace
@@ -1540,10 +1694,10 @@ fn workspace_claim_target_from_pane_info(
     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 {
+fn write_claim_target_pane_nonce(target: &mut LeaderClaimTarget) -> Result<(), LeaderError> {
+    if target.scope_authority.is_none() {
         return Ok(());
-    };
+    }
     let endpoint = target.endpoint.as_deref().ok_or_else(|| {
         LeaderError::Validation("explicit claim is missing its tmux endpoint".to_string())
     })?;
@@ -1557,13 +1711,30 @@ fn write_claim_target_pane_nonce(target: Option<&LeaderClaimTarget>) -> Result<(
     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}"
-            ))
+    let live_nonce = target
+        .pane_info
+        .as_ref()
+        .and_then(|info| {
+            info.leader_env
+                .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+                .map(String::as_str)
         })
+        .filter(|nonce| !nonce.is_empty());
+    // The pane option is the pane-instance identity shared by all authorized
+    // teams. Rewriting an observed value would revoke another team's grant.
+    let effective_nonce = if let Some(live_nonce) = live_nonce {
+        live_nonce.to_string()
+    } else {
+        tmux_backend_for_endpoint(endpoint)
+            .set_pane_binding_nonce_if_unset(pane, nonce)
+            .map_err(|error| {
+                LeaderError::Validation(format!(
+                    "failed to bind the explicit leader pane instance: {error}"
+                ))
+            })?
+    };
+    target.binding_nonce = Some(effective_nonce);
+    Ok(())
 }
 
 fn canonical_workspace(workspace: &Path) -> PathBuf {
@@ -1591,6 +1762,18 @@ fn next_pane_binding_nonce(workspace: &Path, endpoint: &str, pane: &PaneId) -> S
         .collect()
 }
 
+fn pane_binding_nonce_for_claim(
+    workspace: &Path,
+    endpoint: &str,
+    pane: &PaneId,
+    live_nonce: Option<&str>,
+) -> String {
+    live_nonce
+        .filter(|nonce| !nonce.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| next_pane_binding_nonce(workspace, endpoint, pane))
+}
+
 fn target_leader_session_uuid(target: &PaneInfo) -> Option<crate::model::ids::LeaderSessionUuid> {
     target
         .leader_env
@@ -1799,6 +1982,72 @@ fn emit_lease_refusal(
     Ok(())
 }
 
+fn authorize_fresh_caller_receiver(
+    workspace: &Path,
+    receiver: &mut LeaderReceiver,
+    pane: &NonEmptyPaneId,
+    source: LeaseSource,
+    require_current: bool,
+    caller_target: Option<&PaneInfo>,
+    nonce_writer: Option<&dyn Fn(&str, &PaneId, &str) -> Result<String, LeaderError>>,
+) -> Result<(), LeaderError> {
+    if !matches!(source, LeaseSource::QuickStart) || !require_current {
+        return Ok(());
+    }
+    let Some(target) = caller_target else {
+        return Ok(());
+    };
+    if target.pane_id.as_str() != pane.as_pane_id().as_str() || !target.active {
+        return Err(LeaderError::Validation(
+            "fresh caller pane observation does not match the bound pane".to_string(),
+        ));
+    }
+    let Some(current_path) = target.current_path.as_deref() else {
+        return Ok(());
+    };
+    if crate::messaging::leader_channel::path_is_in_workspace(current_path, workspace) {
+        return Ok(());
+    }
+    let Some(endpoint) = receiver
+        .tmux_socket
+        .as_deref()
+        .filter(|endpoint| !endpoint.is_empty())
+    else {
+        return Err(LeaderError::Validation(
+            "fresh cross-workspace caller requires a tmux endpoint".to_string(),
+        ));
+    };
+    if !Path::new(endpoint).is_absolute() {
+        return Err(LeaderError::Validation(
+            "fresh cross-workspace caller requires an absolute tmux endpoint".to_string(),
+        ));
+    }
+    let pane_id = pane.as_pane_id();
+    let live_nonce = if let Some(live_nonce) = target
+        .leader_env
+        .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+        .filter(|nonce| !nonce.is_empty())
+        .cloned()
+    {
+        live_nonce
+    } else {
+        let nonce = pane_binding_nonce_for_claim(workspace, endpoint, pane_id, None);
+        if let Some(writer) = nonce_writer {
+            writer(endpoint, pane_id, &nonce)?
+        } else {
+            tmux_backend_for_endpoint(endpoint)
+                .set_pane_binding_nonce_if_unset(pane_id, &nonce)
+                .map_err(|error| LeaderError::Tmux(error.to_string()))?
+        }
+    };
+    receiver.scope_authority = Some(
+        crate::messaging::leader_channel::FRESH_CALLER_SCOPE_AUTHORITY.to_string(),
+    );
+    receiver.authorized_team_workspace = Some(canonical_workspace(workspace));
+    receiver.binding_nonce = Some(live_nonce);
+    Ok(())
+}
+
 fn make_receiver(
     provider: Provider,
     pane: &NonEmptyPaneId,
@@ -2166,6 +2415,24 @@ fn state_owner(state: &Value) -> Option<TeamOwner> {
 /// now persists ONLY the canonical root state; retaining the public
 /// name for 0.5.x call-site stability. The B0 legacy snapshot is
 /// diagnostic-only via `lifecycle::save_team_runtime_snapshot`.
+pub(crate) fn write_lease_dual_state_with_expected(
+    workspace: &Path,
+    state: &Value,
+    expected_owner: &Value,
+    expected_receiver: &Value,
+) -> Result<(), LeaderError> {
+    let team_key = canonical_owner_write_key(state);
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::ClaimLeaderFreshCaller {
+            team_key: team_key.as_str(),
+            expected_owner,
+            expected_receiver,
+        },
+        state,
+    )?;
+    Ok(())
+}
+
 pub fn write_lease_dual_state(workspace: &Path, state: &Value) -> Result<(), LeaderError> {
     // 0.5.42 S1b (s1b-writer-cluster-locate.md §4.4): terminal root
     // save routes through `StateRepository` with the `ClaimLeader`
@@ -2568,6 +2835,20 @@ mod tests {
         assert_ne!(first, second);
     }
 
+    #[test]
+    fn explicit_claim_generates_nonce_only_when_live_nonce_is_missing() {
+        let workspace = Path::new("/tmp/workspace-a");
+        let endpoint = "/tmp/team-agent-live.sock";
+        let pane = PaneId::new("%7");
+        let generated = pane_binding_nonce_for_claim(workspace, endpoint, &pane, None);
+        assert_eq!(generated.len(), 32);
+        assert!(generated.chars().all(|ch| ch.is_ascii_hexdigit()));
+        assert_eq!(
+            pane_binding_nonce_for_claim(workspace, endpoint, &pane, Some("live-nonce")),
+            "live-nonce"
+        );
+    }
+
     #[test]
     fn claim_authority_preserves_recorded_absolute_observation() {
         let workspace = Path::new("/tmp/workspace-a");