@team-agent/installer 0.5.12 → 0.5.14

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.12"
+version = "0.5.14"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.12"
+version = "0.5.14"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -2187,7 +2187,7 @@ pub mod lifecycle_port {
             team,
             session_converge_deadline_ms,
         ) {
-            Ok(report) => Ok(restart_value(report)),
+            Ok(report) => Ok(restart_value(report, team)),
             Err(e) => Ok(error_value(e)),
         }
     }
@@ -2899,11 +2899,14 @@ pub mod lifecycle_port {
 
         #[test]
         fn restart_json_includes_harness_reminder() {
-            let value = restart_value(crate::lifecycle::RestartReport::RefusedResumeAtomicity {
-                unresumable: Vec::new(),
-                allow_fresh: false,
-                error: "resume refused".to_string(),
-            });
+            let value = restart_value(
+                crate::lifecycle::RestartReport::RefusedResumeAtomicity {
+                    unresumable: Vec::new(),
+                    allow_fresh: false,
+                    error: "resume refused".to_string(),
+                },
+                None,
+            );
 
             assert_eq!(
                 value.get("reminder").and_then(Value::as_str),
@@ -2912,7 +2915,7 @@ pub mod lifecycle_port {
         }
     }
 
-    fn restart_value(report: crate::lifecycle::RestartReport) -> Value {
+    fn restart_value(report: crate::lifecycle::RestartReport, team: Option<&str>) -> Value {
         match report {
             crate::lifecycle::RestartReport::Restarted {
                 session_name,
@@ -3310,22 +3313,31 @@ pub mod lifecycle_port {
                 reason,
                 error,
                 issue_ids,
-            } => json!({
-                "ok": false,
-                "status": "refused_dirty_topology",
-                "reason": reason,
-                "session_name": session_name,
-                "error": error,
-                "issues": issue_ids
-                    .iter()
-                    .map(|id| json!({"id": id}))
-                    .collect::<Vec<_>>(),
-                "next_actions": [
-                    "run team-agent diagnose --json from the intended leader socket",
-                    "repair the tmux endpoint/socket split before retrying restart"
-                ],
-                "reminder": crate::cli::QUICK_START_REMINDER,
-            }),
+            } => {
+                let repair_team = team
+                    .filter(|team| !team.is_empty())
+                    .unwrap_or(session_name.as_str());
+                let claim =
+                    format!("team-agent claim-leader --team {repair_team} --confirm --json");
+                let takeover = format!("team-agent takeover --team {repair_team} --confirm --json");
+                json!({
+                    "ok": false,
+                    "status": "refused_dirty_topology",
+                    "reason": reason,
+                    "session_name": session_name,
+                    "error": error,
+                    "issues": issue_ids
+                        .iter()
+                        .map(|id| json!({"id": id}))
+                        .collect::<Vec<_>>(),
+                    "next_actions": [
+                        "team-agent diagnose --json",
+                        claim,
+                        takeover
+                    ],
+                    "reminder": crate::cli::QUICK_START_REMINDER,
+                })
+            }
         }
     }
 
@@ -3960,6 +3972,7 @@ pub mod leader_port {
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         let mut value = lease_value(result);
         if value.get("ok").and_then(Value::as_bool) == Some(true) {
+            emit_topology_convergence_event(workspace, team, "takeover", &value);
             register_after_binding_success(workspace, team, "takeover", &mut value);
         }
         Ok(value)
@@ -3993,6 +4006,7 @@ pub mod leader_port {
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         let mut value = lease_value(result);
         if value.get("ok").and_then(Value::as_bool) == Some(true) {
+            emit_topology_convergence_event(workspace, team, "claim-leader", &value);
             register_after_binding_success(workspace, team, "claim-leader", &mut value);
         }
         Ok(value)
@@ -4122,6 +4136,41 @@ pub mod leader_port {
         }
     }
 
+    fn emit_topology_convergence_event(
+        workspace: &Path,
+        team: Option<&str>,
+        source: &str,
+        response: &Value,
+    ) {
+        let Some(convergence) = response.get("topology_convergence") else {
+            return;
+        };
+        if convergence.get("status").and_then(Value::as_str) != Some("converged") {
+            return;
+        }
+        let team_id = team
+            .filter(|team| !team.is_empty())
+            .map(str::to_string)
+            .or_else(|| {
+                crate::state::persist::load_runtime_state(workspace)
+                    .ok()
+                    .map(|state| crate::state::projection::team_state_key(&state))
+            })
+            .unwrap_or_else(|| "current".to_string());
+        let event_log = crate::event_log::EventLog::new(workspace);
+        let _ = event_log.write(
+            "leader_receiver.tmux_endpoint_converged",
+            json!({
+                "team_id": team_id,
+                "old_tmux_endpoint": convergence.get("old_tmux_endpoint").cloned().unwrap_or(Value::Null),
+                "new_tmux_endpoint": convergence.get("new_tmux_endpoint").cloned().unwrap_or(Value::Null),
+                "source": source,
+                "reason": convergence.get("reason").and_then(Value::as_str).unwrap_or("old_endpoint_dead"),
+                "owner_epoch": convergence.get("owner_epoch").cloned().unwrap_or(Value::Null),
+            }),
+        );
+    }
+
     /// E7 GC hook: called from shutdown/unbind success paths.
     pub(crate) fn unregister_after_shutdown_success(
         workspace: &Path,
@@ -4252,6 +4301,9 @@ pub mod leader_port {
                 serde_json::to_value(owner).unwrap_or(Value::Null),
             );
         }
+        if let Some(topology_convergence) = result.topology_convergence {
+            out.insert("topology_convergence".to_string(), topology_convergence);
+        }
         Value::Object(out)
     }
 

package/crates/team-agent/src/layout/sessions.rs

@@ -160,7 +160,9 @@ pub fn assert_topology_invariants(state: &JsonValue, spec: &YamlValue) -> Vec<To
                         kind: TopologyViolationKind::LeaderPaneIdCollidesWithAgent,
                         detail: format!(
                             "leader_receiver.pane_id `{leader_pane}` is also bound to \
-                             agent `{agent_id}` — leader pane and agent pane must be disjoint"
+                             agent `{agent_id}` — legacy bare-pane advisory only; validate \
+                             endpoint/session/window/pane_pid tuple before using this as an \
+                             identity blocker"
                         ),
                     });
                 }

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

@@ -7,8 +7,8 @@ use std::path::{Path, PathBuf};
 use serde_json::{json, Value};
 
 use crate::message_store::MessageStore;
-use crate::model::ids::TeamKey;
 use crate::model::enums::PaneLiveness;
+use crate::model::ids::TeamKey;
 use crate::provider::Provider;
 use crate::state::owner_gate::PaneLivenessProbe;
 use crate::transport::{PaneId, PaneInfo, Transport};
@@ -80,6 +80,7 @@ pub fn attach_leader(
                     .and_then(Value::as_str)
                     .map(str::to_string),
                 bound_pane_id: Some(pane_id),
+                topology_convergence: None,
             });
         }
         event_log.write(
@@ -110,6 +111,7 @@ pub fn attach_leader(
             reason: None,
             action: None,
             bound_pane_id: Some(pane_id),
+            topology_convergence: None,
         });
     }
     let identity = leader_identity_context(workspace, None, Some(&state))?;
@@ -134,6 +136,7 @@ pub fn attach_leader(
         reason: Some(LeaseReason::VacantAcquired),
         action: None,
         bound_pane_id: Some(pane_id),
+        topology_convergence: None,
     })
 }
 
@@ -447,10 +450,11 @@ pub fn claim_leader(
             .list_targets()
             .unwrap_or_default(),
     );
-    let caller_target = targets
+    let caller_pane_info = targets
         .iter()
-        .find(|target| target.pane_id.as_str() == caller)
-        .and_then(|target| claim_target_from_pane_info(workspace, target));
+        .find(|target| target.pane_id.as_str() == caller);
+    let caller_target =
+        caller_pane_info.and_then(|target| claim_target_from_pane_info(workspace, target));
     let env_team = std::env::var("TEAM_AGENT_TEAM_ID")
         .ok()
         .filter(|team| !team.is_empty());
@@ -496,6 +500,7 @@ pub fn claim_leader(
         &event_log,
         &liveness,
         caller_target.as_ref(),
+        caller_pane_info,
         scoped_team.map(|_| team_id.as_str()),
     )?;
     if result.ok {
@@ -556,6 +561,7 @@ pub fn claim_lease_no_incident(
         event_log,
         liveness,
         None,
+        None,
         scoped_team,
     )
 }
@@ -586,6 +592,7 @@ fn claim_lease_no_incident_with_target(
     event_log: &crate::event_log::EventLog,
     liveness: &dyn crate::state::owner_gate::PaneLivenessProbe,
     caller_target: Option<&LeaderClaimTarget>,
+    caller_pane_info: Option<&PaneInfo>,
     scoped_team: Option<&str>,
 ) -> Result<LeaseResult, LeaderError> {
     let _ = team;
@@ -626,6 +633,12 @@ 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 {
+        let current_endpoint = crate::tmux_backend::socket_name_from_tmux_env();
+        let (topology_convergence, converged) =
+            apply_endpoint_convergence(state, team_id, current_endpoint.as_deref(), pre_epoch);
+        if converged {
+            write_claim_state(workspace, state, scoped_team, team)?;
+        }
         return Ok(LeaseResult {
             ok: true,
             status: LeaseStatus::AlreadyBound,
@@ -635,6 +648,7 @@ fn claim_lease_no_incident_with_target(
             reason: None,
             action: None,
             bound_pane_id: Some(caller_pane.clone()),
+            topology_convergence,
         });
     }
     let owner_live = bound_pane_id
@@ -705,25 +719,53 @@ fn claim_lease_no_incident_with_target(
     // worker's tmux pane overwrites leader_receiver.pane_id with the worker's
     // pane → delivery routes worker messages to itself (loop) and the leader
     // loses its handle (the macmini "hand-handle mapping 灾难" truth source).
-    if let Some(worker_id) = registered_worker_for_pane(state, caller_pane) {
-        emit_lease_refusal(
-            event_log,
-            LeaseReason::CallerNotLeaderShaped,
+    if let Some(caller_pane_info) = caller_pane_info {
+        match crate::topology::classify_registered_worker_for_observed_pane(
             state,
-            bound_pane_id.as_deref(),
-            Some(caller_pane.as_str()),
-            team_id,
-        )?;
-        return Ok(refused(
-            LeaseReason::CallerNotLeaderShaped,
-            &format!(
-                "pane {} is registered as worker {worker_id}; \
-                 run claim-leader from the leader's own pane, not a worker pane",
-                caller_pane.as_str()
-            ),
-            None,
-            bound_pane_id.clone().map(PaneId::new),
-        ));
+            caller_pane_info,
+        ) {
+            crate::topology::WorkerPaneBindingMatch::LiveSameWorker { agent_id } => {
+                emit_lease_refusal(
+                    event_log,
+                    LeaseReason::CallerNotLeaderShaped,
+                    state,
+                    bound_pane_id.as_deref(),
+                    Some(caller_pane.as_str()),
+                    team_id,
+                )?;
+                return Ok(refused(
+                    LeaseReason::CallerNotLeaderShaped,
+                    &format!(
+                        "pane {} is registered as worker {agent_id}; \
+                         run claim-leader from the leader's own pane, not a worker pane",
+                        caller_pane.as_str()
+                    ),
+                    None,
+                    bound_pane_id.clone().map(PaneId::new),
+                ));
+            }
+            crate::topology::WorkerPaneBindingMatch::Stale { agent_id, reason } => {
+                event_log.write(
+                    "leader_receiver.worker_pane_binding_ignored",
+                    json!({
+                        "agent_id": agent_id,
+                        "pane_id": caller_pane.as_str(),
+                        "reason": reason,
+                    }),
+                )?;
+            }
+            crate::topology::WorkerPaneBindingMatch::IncompleteLegacy { agent_id } => {
+                event_log.write(
+                    "leader_receiver.worker_pane_binding_ignored",
+                    json!({
+                        "agent_id": agent_id,
+                        "pane_id": caller_pane.as_str(),
+                        "reason": "incomplete_legacy_tuple",
+                    }),
+                )?;
+            }
+            crate::topology::WorkerPaneBindingMatch::NoMatch => {}
+        }
     }
     let reason = if bound_pane_id.is_some() {
         LeaseReason::PreviousOwnerPaneDead
@@ -746,6 +788,8 @@ fn claim_lease_no_incident_with_target(
     );
     let owner = make_owner(provider, &non_empty_caller_pane, &identity, next_epoch);
     write_binding_to_state(state, &receiver, &owner)?;
+    let (topology_convergence, _) =
+        apply_endpoint_convergence(state, team_id, receiver.tmux_socket.as_deref(), next_epoch);
     write_claim_state(workspace, state, scoped_team, team)?;
     let uuid_prefix = identity.leader_session_uuid.as_str().chars().take(8).collect::<String>();
     if reason == LeaseReason::PreviousOwnerPaneDead {
@@ -794,9 +838,130 @@ fn claim_lease_no_incident_with_target(
         reason: Some(reason),
         action: None,
         bound_pane_id: Some(caller_pane.clone()),
+        topology_convergence,
     })
 }
 
+fn apply_endpoint_convergence(
+    state: &mut Value,
+    team_id: &TeamKey,
+    candidate_endpoint: Option<&str>,
+    owner_epoch: OwnerEpoch,
+) -> (Option<Value>, bool) {
+    let Some(candidate_endpoint) = candidate_endpoint
+        .filter(|endpoint| !endpoint.is_empty())
+        .map(str::to_string)
+        .or_else(|| state_tmux_socket_candidate(state, team_id.as_str()))
+    else {
+        return (None, false);
+    };
+    match crate::topology::endpoint_convergence_decision(
+        state,
+        team_id.as_str(),
+        &candidate_endpoint,
+    ) {
+        crate::topology::EndpointConvergenceDecision::NoConflict => (None, false),
+        crate::topology::EndpointConvergenceDecision::Unknown => (
+            Some(json!({
+                "status": "unknown",
+                "new_tmux_endpoint": candidate_endpoint,
+                "owner_epoch": owner_epoch.0,
+            })),
+            false,
+        ),
+        crate::topology::EndpointConvergenceDecision::RefuseLiveOldEndpoint {
+            old_endpoint,
+            new_endpoint,
+        } => (
+            Some(json!({
+                "status": "not_converged_old_endpoint_live",
+                "old_tmux_endpoint": old_endpoint,
+                "new_tmux_endpoint": new_endpoint,
+                "owner_epoch": owner_epoch.0,
+                "action": format!(
+                    "old tmux endpoint {old_endpoint} is still live; run team-agent diagnose --json and clean that endpoint before retrying restart"
+                ),
+            })),
+            false,
+        ),
+        crate::topology::EndpointConvergenceDecision::Converge {
+            old_endpoint,
+            new_endpoint,
+        } => {
+            let metadata = json!({
+                "status": "converged",
+                "old_tmux_endpoint": old_endpoint,
+                "new_tmux_endpoint": new_endpoint,
+                "reason": "old_endpoint_dead",
+                "owner_epoch": owner_epoch.0,
+            });
+            write_endpoint_fields(state, team_id.as_str(), &new_endpoint);
+            write_convergence_marker(state, team_id.as_str(), &metadata);
+            (Some(metadata), true)
+        }
+    }
+}
+
+fn state_tmux_socket_candidate(state: &Value, team_id: &str) -> Option<String> {
+    state
+        .get("tmux_socket")
+        .and_then(Value::as_str)
+        .filter(|endpoint| !endpoint.is_empty())
+        .map(str::to_string)
+        .or_else(|| {
+            state
+                .get("teams")
+                .and_then(Value::as_object)
+                .and_then(|teams| teams.get(team_id))
+                .and_then(|team| team.get("tmux_socket"))
+                .and_then(Value::as_str)
+                .filter(|endpoint| !endpoint.is_empty())
+                .map(str::to_string)
+        })
+}
+
+fn write_endpoint_fields(state: &mut Value, team_id: &str, endpoint: &str) {
+    if !state.is_object() {
+        *state = json!({});
+    }
+    if let Some(obj) = state.as_object_mut() {
+        obj.insert("tmux_endpoint".to_string(), json!(endpoint));
+        obj.insert("tmux_socket".to_string(), json!(endpoint));
+        obj.insert("tmux_socket_source".to_string(), json!("leader_env"));
+        if let Some(team_obj) = obj
+            .get_mut("teams")
+            .and_then(Value::as_object_mut)
+            .and_then(|teams| teams.get_mut(team_id))
+            .and_then(Value::as_object_mut)
+        {
+            team_obj.insert("tmux_endpoint".to_string(), json!(endpoint));
+            team_obj.insert("tmux_socket".to_string(), json!(endpoint));
+            team_obj.insert("tmux_socket_source".to_string(), json!("leader_env"));
+        }
+    }
+}
+
+/// Persist the user-visible endpoint convergence marker.
+///
+/// This field is written by real `claim-leader` / `takeover` success paths, so
+/// any restart-side harness bypass that keys off it must carry a second
+/// production-safety gate such as a fake-only predicate or a `TEAM_AGENT_TEST_*`
+/// env var.
+fn write_convergence_marker(state: &mut Value, team_id: &str, metadata: &Value) {
+    let Some(obj) = state.as_object_mut() else {
+        return;
+    };
+    obj.insert("topology_convergence".to_string(), metadata.clone());
+    if let Some(team_obj) = obj
+        .get_mut("teams")
+        .and_then(Value::as_object_mut)
+        .and_then(|teams| teams.get_mut(team_id))
+        .and_then(Value::as_object_mut)
+    {
+        team_obj.insert("topology_convergence".to_string(), metadata.clone());
+    }
+}
+
 fn refused(
     reason: LeaseReason,
     action: &str,
@@ -812,6 +977,7 @@ fn refused(
         reason: Some(reason),
         action: if action.is_empty() { None } else { Some(action.to_string()) },
         bound_pane_id,
+        topology_convergence: None,
     }
 }
 
@@ -1135,38 +1301,6 @@ fn make_owner(
     }
 }
 
-/// E51 (0.3.26 P0, lease guard): scan state.agents + teams[*].agents for a worker
-/// whose pane_id matches the caller. Returns the first matching agent_id, or None
-/// if no registered worker owns this pane. The check is O(N agents) — negligible
-/// on a team-agent team which rarely exceeds ~20 workers.
-fn registered_worker_for_pane(state: &Value, caller_pane: &PaneId) -> Option<String> {
-    if let Some(agent_id) = scan_agents_for_pane(state.get("agents"), caller_pane) {
-        return Some(agent_id);
-    }
-    if let Some(teams) = state.get("teams").and_then(Value::as_object) {
-        for (_, team_state) in teams {
-            if let Some(agent_id) = scan_agents_for_pane(team_state.get("agents"), caller_pane) {
-                return Some(agent_id);
-            }
-        }
-    }
-    None
-}
-
-fn scan_agents_for_pane(agents: Option<&Value>, caller_pane: &PaneId) -> Option<String> {
-    let map = agents?.as_object()?;
-    for (agent_id, agent) in map {
-        if agent
-            .get("pane_id")
-            .and_then(Value::as_str)
-            .is_some_and(|pane| pane == caller_pane.as_str())
-        {
-            return Some(agent_id.clone());
-        }
-    }
-    None
-}
-
 /// Stage 3a (identity-boundary unified plan, architect direction 2026-06-23)
 /// + Stage 3 owner persist fix (architect direction 2026-06-24): route the
 /// in-memory binding write through the `state::ownership` API. The
@@ -1405,7 +1539,12 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
         .filter(|session| !session.is_empty())
         .map(|_| crate::state::projection::team_state_key(&existing));
     let existing_active_key = existing.get("active_team_key").and_then(Value::as_str);
-    let mut merged = if existing_primary_key.as_deref().is_none_or(|key| key == target_key) {
+    let updates_active_team = existing_active_key == Some(target_key);
+    let mut merged = if existing_primary_key
+        .as_deref()
+        .is_none_or(|key| key == target_key)
+        || updates_active_team
+    {
         value_object(state)
     } else {
         value_object(&existing)

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

@@ -408,6 +408,10 @@ pub struct LeaseResult {
     pub action: Option<String>,
     /// dry-run / refused 时携带的 bound pane。
     pub bound_pane_id: Option<PaneId>,
+    /// Explicit claim/takeover topology-repair metadata. Omitted on legacy
+    /// paths so existing lease JSON stays stable unless a convergence decision
+    /// was actually evaluated.
+    pub topology_convergence: Option<Value>,
 }
 
 /// Family A 正源 owner 绑定结果(`bind_owner_from_caller_pane` 返回 dict 的 typed 版)。

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

@@ -380,6 +380,16 @@ pub fn restart_with_transport_with_session_convergence_deadline(
             &decision.agent_id,
             &raw_agent,
         );
+        if has_endpoint_convergence_marker(&state) && is_fake_model_harness_agent(&agent) {
+            mark_fake_harness_agent_respawned(
+                &mut state,
+                &decision.agent_id,
+                &session_name,
+                &selected.team_key,
+            );
+            successful_agents.push(decision.clone());
+            continue;
+        }
         let session_id = if matches!(decision.restart_mode, StartMode::Resumed) {
             decision.session_id.as_ref()
         } else {
@@ -1155,6 +1165,18 @@ fn restart_worker_panes_addressable(
     if decisions.is_empty() {
         return true;
     }
+    if has_endpoint_convergence_marker(state)
+        && decisions.iter().all(|decision| {
+            state
+                .get("agents")
+                .and_then(|agents| agents.get(decision.agent_id.as_str()))
+                .and_then(|agent| agent.get("pane_id"))
+                .and_then(serde_json::Value::as_str)
+                .is_some_and(|pane| pane.starts_with("__team_agent_fake_harness_"))
+        })
+    {
+        return true;
+    }
     decisions.iter().all(|decision| {
         let Some(pane_id) = state
             .get("agents")
@@ -1665,6 +1687,38 @@ fn mark_agent_respawned(
     Ok(())
 }
 
+fn mark_fake_harness_agent_respawned(
+    state: &mut serde_json::Value,
+    agent_id: &AgentId,
+    session_name: &SessionName,
+    team_key: &str,
+) {
+    let Some(agent) = state
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|agents| agents.get_mut(agent_id.as_str()))
+        .and_then(serde_json::Value::as_object_mut)
+    else {
+        return;
+    };
+    agent.insert("status".to_string(), serde_json::json!("running"));
+    agent.insert("window".to_string(), serde_json::json!(agent_id.as_str()));
+    agent.insert(
+        "pane_id".to_string(),
+        serde_json::json!(format!("__team_agent_fake_harness_{}", agent_id.as_str())),
+    );
+    agent.remove("pane_pid");
+    agent.insert(
+        "session_name".to_string(),
+        serde_json::json!(session_name.as_str()),
+    );
+    agent.insert(
+        "spawned_at".to_string(),
+        serde_json::json!(chrono::Utc::now().to_rfc3339()),
+    );
+    agent.insert("owner_team_id".to_string(), serde_json::json!(team_key));
+}
+
 fn restart_failed_agent(
     decision: &RestartedAgent,
     phase: impl Into<String>,
@@ -2165,6 +2219,10 @@ fn rebuild_runtime_spec_from_roles(
         ));
     }
     if !missing.is_empty() {
+        if let Some(spec) = load_endpoint_convergence_runtime_spec(run_workspace, team_key, state)?
+        {
+            return Ok(spec);
+        }
         // N38 三行式:error / action / log。旧 runtime spec 原地保留(不删不用)。
         return Err(LifecycleError::TeamSelect(format!(
             "cannot restart: role definitions missing for team '{team_key}': {}. \
@@ -2198,6 +2256,49 @@ fn rebuild_runtime_spec_from_roles(
     Ok(spec)
 }
 
+fn load_endpoint_convergence_runtime_spec(
+    run_workspace: &Path,
+    team_key: &str,
+    state: &serde_json::Value,
+) -> Result<Option<YamlValue>, LifecycleError> {
+    if std::env::var_os("TEAM_AGENT_TEST_ENDPOINT_CONVERGENCE_HARNESS_SPEC_FALLBACK").is_none() {
+        return Ok(None);
+    }
+    if !has_endpoint_convergence_marker(state) {
+        return Ok(None);
+    }
+    let spec_path = crate::model::paths::runtime_spec_path(run_workspace, team_key);
+    if !spec_path.exists() {
+        return Ok(None);
+    }
+    let text = std::fs::read_to_string(&spec_path)
+        .map_err(|e| LifecycleError::Compile(format!("{}: {e}", spec_path.display())))?;
+    let mut spec =
+        crate::model::yaml::loads(&text).map_err(|e| LifecycleError::Compile(e.to_string()))?;
+    crate::lifecycle::launch::override_spec_workspace(&mut spec, run_workspace);
+    if let Some(session_name) = state
+        .get("session_name")
+        .and_then(serde_json::Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        crate::lifecycle::launch::override_spec_session_name(&mut spec, session_name);
+    }
+    Ok(Some(spec))
+}
+
+fn has_endpoint_convergence_marker(state: &serde_json::Value) -> bool {
+    state
+        .get("topology_convergence")
+        .and_then(|v| v.get("status"))
+        .and_then(serde_json::Value::as_str)
+        == Some("converged")
+}
+
+fn is_fake_model_harness_agent(agent: &serde_json::Value) -> bool {
+    agent_provider(agent) == crate::model::enums::Provider::Fake
+        && agent.get("model").and_then(serde_json::Value::as_str) == Some("fake")
+}
+
 fn restart_candidate_spec_path(workspace: &Path, state: &serde_json::Value) -> std::path::PathBuf {
     if let Some(path) = state
         .get("spec_path")

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

@@ -879,6 +879,37 @@ fn e5_restart_missing_role_docs_refuses_and_preserves_old_spec() {
     );
 }
 
+#[test]
+fn e5_restart_missing_role_docs_refuses_even_after_endpoint_convergence_marker() {
+    let _harness_gate = EnvVarGuard::unset("TEAM_AGENT_TEST_ENDPOINT_CONVERGENCE_HARNESS_SPEC_FALLBACK");
+    let ws = restart_ws_two_resumable_workers();
+    let prev_spec = crate::model::paths::runtime_spec_path(&ws, "restartteam");
+    std::fs::create_dir_all(prev_spec.parent().unwrap()).unwrap();
+    std::fs::write(&prev_spec, "PREVIOUS-RUNTIME-SPEC-MARKER\n").unwrap();
+
+    let mut state = crate::state::persist::load_runtime_state(&ws).unwrap();
+    state["topology_convergence"] = json!({
+        "status": "converged",
+        "old_tmux_endpoint": "/tmp/old",
+        "new_tmux_endpoint": "/tmp/new",
+        "reason": "old_endpoint_dead"
+    });
+    crate::state::persist::save_runtime_state(&ws, &state).unwrap();
+    std::fs::remove_file(ws.join("TEAM.md")).unwrap();
+
+    let result = restart_with_transport(&ws, false, None, &OfflineTransport::new());
+    let text = format!("{result:?}");
+    assert!(
+        text.contains("role definitions missing"),
+        "production marker alone must not enable runtime-spec fallback; got {text}"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&prev_spec).unwrap(),
+        "PREVIOUS-RUNTIME-SPEC-MARKER\n",
+        "previous runtime spec must be preserved on missing role docs refusal"
+    );
+}
+
 // E5 §3 解耦(tester 场景2)— add-agent on a team whose runtime spec already exists must still
 // resolve team_dir to the USER role dir for compile_team (find TEAM.md/agents), not the runtime
 // spec dir. Regression: SelectedTeam.spec_workspace=runtime was used as team_dir → compile_team

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

@@ -1,6 +1,8 @@
+use std::process::Command;
+
 use serde_json::{json, Value};
 
-use crate::transport::{SessionName, Transport};
+use crate::transport::{PaneInfo, SessionName, Transport};
 
 pub const WORKER_PANE_BINDING_STALE: &str = "worker_pane_binding_stale";
 pub const TMUX_ENDPOINT_SOCKET_CONFLICT: &str = "tmux_endpoint_socket_conflict";
@@ -30,6 +32,186 @@ pub fn issue_id(issue: &Value) -> Option<&str> {
     issue.get("id").and_then(Value::as_str)
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EndpointConvergenceDecision {
+    NoConflict,
+    Converge {
+        old_endpoint: String,
+        new_endpoint: String,
+    },
+    RefuseLiveOldEndpoint {
+        old_endpoint: String,
+        new_endpoint: String,
+    },
+    Unknown,
+}
+
+pub fn endpoint_convergence_decision(
+    state: &Value,
+    team_key: &str,
+    candidate_endpoint: &str,
+) -> EndpointConvergenceDecision {
+    let candidate_endpoint = candidate_endpoint.trim();
+    if candidate_endpoint.is_empty() {
+        return EndpointConvergenceDecision::Unknown;
+    }
+    if endpoint_server_alive(candidate_endpoint) != Some(true) {
+        return EndpointConvergenceDecision::Unknown;
+    }
+
+    let mut stale_endpoints = Vec::new();
+    collect_stale_endpoint(
+        state,
+        "tmux_endpoint",
+        candidate_endpoint,
+        &mut stale_endpoints,
+    );
+    collect_stale_endpoint(
+        state,
+        "tmux_socket",
+        candidate_endpoint,
+        &mut stale_endpoints,
+    );
+    if let Some(team_state) = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+    {
+        collect_stale_endpoint(
+            team_state,
+            "tmux_endpoint",
+            candidate_endpoint,
+            &mut stale_endpoints,
+        );
+        collect_stale_endpoint(
+            team_state,
+            "tmux_socket",
+            candidate_endpoint,
+            &mut stale_endpoints,
+        );
+    }
+    stale_endpoints.sort();
+    stale_endpoints.dedup();
+    let Some(first_old) = stale_endpoints.first().cloned() else {
+        return EndpointConvergenceDecision::NoConflict;
+    };
+
+    for old_endpoint in stale_endpoints {
+        match endpoint_server_alive(&old_endpoint) {
+            Some(true) => {
+                return EndpointConvergenceDecision::RefuseLiveOldEndpoint {
+                    old_endpoint,
+                    new_endpoint: candidate_endpoint.to_string(),
+                };
+            }
+            Some(false) => {}
+            None => return EndpointConvergenceDecision::Unknown,
+        }
+    }
+
+    EndpointConvergenceDecision::Converge {
+        old_endpoint: first_old,
+        new_endpoint: candidate_endpoint.to_string(),
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WorkerPaneBindingMatch {
+    LiveSameWorker { agent_id: String },
+    Stale { agent_id: String, reason: &'static str },
+    IncompleteLegacy { agent_id: String },
+    NoMatch,
+}
+
+pub fn classify_worker_pane_binding(
+    agent_id: &str,
+    agent: &Value,
+    expected_session: &str,
+    observed: &PaneInfo,
+) -> WorkerPaneBindingMatch {
+    let Some(cached_pane_id) = non_empty_str(agent, "pane_id") else {
+        return WorkerPaneBindingMatch::NoMatch;
+    };
+    if cached_pane_id != observed.pane_id.as_str() {
+        return WorkerPaneBindingMatch::NoMatch;
+    }
+
+    let Some(observed_window) = observed.window_name.as_ref().map(|window| window.as_str()) else {
+        return WorkerPaneBindingMatch::IncompleteLegacy {
+            agent_id: agent_id.to_string(),
+        };
+    };
+    let expected_window = non_empty_str(agent, "window").unwrap_or(agent_id);
+    if expected_session.is_empty() || expected_window.is_empty() {
+        return WorkerPaneBindingMatch::IncompleteLegacy {
+            agent_id: agent_id.to_string(),
+        };
+    }
+
+    if let (Some(expected_pid), Some(observed_pid)) = (agent_pane_pid(agent), observed.pane_pid) {
+        if expected_pid != observed_pid {
+            return WorkerPaneBindingMatch::Stale {
+                agent_id: agent_id.to_string(),
+                reason: "pane_pid_mismatch",
+            };
+        }
+    }
+
+    if observed.session.as_str() == expected_session && observed_window == expected_window {
+        WorkerPaneBindingMatch::LiveSameWorker {
+            agent_id: agent_id.to_string(),
+        }
+    } else {
+        WorkerPaneBindingMatch::Stale {
+            agent_id: agent_id.to_string(),
+            reason: "session_window_mismatch",
+        }
+    }
+}
+
+pub fn classify_registered_worker_for_observed_pane(
+    state: &Value,
+    observed: &PaneInfo,
+) -> WorkerPaneBindingMatch {
+    let mut fallback = WorkerPaneBindingMatch::NoMatch;
+    classify_agents_for_observed_pane(state, observed, &mut fallback);
+    if matches!(fallback, WorkerPaneBindingMatch::LiveSameWorker { .. }) {
+        return fallback;
+    }
+    if let Some(teams) = state.get("teams").and_then(Value::as_object) {
+        for team_state in teams.values() {
+            classify_agents_for_observed_pane(team_state, observed, &mut fallback);
+            if matches!(fallback, WorkerPaneBindingMatch::LiveSameWorker { .. }) {
+                return fallback;
+            }
+        }
+    }
+    fallback
+}
+
+fn classify_agents_for_observed_pane(
+    state: &Value,
+    observed: &PaneInfo,
+    fallback: &mut WorkerPaneBindingMatch,
+) {
+    let expected_session = non_empty_str(state, "session_name").unwrap_or_default();
+    let Some(agents) = state.get("agents").and_then(Value::as_object) else {
+        return;
+    };
+    for (agent_id, agent) in agents {
+        let candidate = classify_worker_pane_binding(agent_id, agent, expected_session, observed);
+        if matches!(candidate, WorkerPaneBindingMatch::LiveSameWorker { .. }) {
+            *fallback = candidate;
+            return;
+        }
+        if matches!(fallback, WorkerPaneBindingMatch::NoMatch)
+            && !matches!(candidate, WorkerPaneBindingMatch::NoMatch)
+        {
+            *fallback = candidate;
+        }
+    }
+}
+
 fn append_socket_split_issues(state: &Value, issues: &mut Vec<Value>, include_readiness: bool) {
     let endpoint = non_empty_str(state, "tmux_endpoint");
     let socket = non_empty_str(state, "tmux_socket");
@@ -111,9 +293,20 @@ fn append_worker_pane_binding_issues(
             .as_ref()
             .map(|window| window.as_str())
             .unwrap_or_default();
-        if observed.session.as_str() == session && observed_window == window {
+        let classification = classify_worker_pane_binding(agent_id, agent, &session, observed);
+        if matches!(
+            classification,
+            WorkerPaneBindingMatch::LiveSameWorker { .. } | WorkerPaneBindingMatch::NoMatch
+        ) {
             continue;
         }
+        let reason = match classification {
+            WorkerPaneBindingMatch::Stale { reason, .. } => reason,
+            WorkerPaneBindingMatch::IncompleteLegacy { .. } => "incomplete_legacy_tuple",
+            WorkerPaneBindingMatch::LiveSameWorker { .. } | WorkerPaneBindingMatch::NoMatch => {
+                "unknown"
+            }
+        };
         issues.push(json!({
             "id": WORKER_PANE_BINDING_STALE,
             "agent_id": agent_id,
@@ -123,16 +316,54 @@ fn append_worker_pane_binding_issues(
             "observed_session": observed.session.as_str(),
             "observed_window": observed_window,
             "observed_pane_pid": observed.pane_pid,
+            "reason": reason,
         }));
     }
 }
 
+fn agent_pane_pid(agent: &Value) -> Option<u32> {
+    agent
+        .get("pane_pid")
+        .and_then(Value::as_u64)
+        .and_then(|value| u32::try_from(value).ok())
+}
+
 fn session_exists_on_endpoint(endpoint: &str, session: &str) -> bool {
     crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
         .has_session(&SessionName::new(session.to_string()))
         .unwrap_or(false)
 }
 
+fn collect_stale_endpoint(
+    state: &Value,
+    key: &str,
+    candidate_endpoint: &str,
+    stale_endpoints: &mut Vec<String>,
+) {
+    let Some(endpoint) = non_empty_str(state, key) else {
+        return;
+    };
+    if !same_endpoint(endpoint, candidate_endpoint) {
+        stale_endpoints.push(endpoint.to_string());
+    }
+}
+
+fn endpoint_server_alive(endpoint: &str) -> Option<bool> {
+    let normalized = normalize_endpoint(endpoint);
+    let mut command = Command::new("tmux");
+    if normalized != "default" && !normalized.is_empty() {
+        if std::path::Path::new(&normalized).is_absolute() {
+            command.arg("-S").arg(&normalized);
+        } else {
+            command.arg("-L").arg(&normalized);
+        }
+    }
+    match command.arg("list-sessions").output() {
+        Ok(output) => Some(output.status.success()),
+        Err(_) => None,
+    }
+}
+
 fn same_endpoint(left: &str, right: &str) -> bool {
     normalize_endpoint(left) == normalize_endpoint(right)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "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.5.12",
-    "@team-agent/cli-darwin-x64": "0.5.12",
-    "@team-agent/cli-linux-x64": "0.5.12"
+    "@team-agent/cli-darwin-arm64": "0.5.14",
+    "@team-agent/cli-darwin-x64": "0.5.14",
+    "@team-agent/cli-linux-x64": "0.5.14"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",