@team-agent/installer 0.5.13 → 0.5.15

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.13"
+version = "0.5.15"
 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.13"
+version = "0.5.15"
 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,23 +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": [
-                    "team-agent diagnose --json",
-                    "team-agent claim-leader --confirm --json",
-                    "team-agent takeover --confirm --json"
-                ],
-                "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,
+                })
+            }
         }
     }
 
@@ -3961,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)
@@ -3994,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)
@@ -4123,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,
@@ -4253,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/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,
     })
 }
 
@@ -630,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,
@@ -639,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
@@ -778,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 {
@@ -826,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,
@@ -844,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,
     }
 }
 
@@ -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/agent.rs

@@ -255,6 +255,7 @@ pub(crate) fn start_agent_at_paths(
         Some(&safety),
         layout_placement.as_ref(),
         None,
+        None,
         Some(resolved_team_key.as_str()),
     )?;
     verify_spawned_pane_matches_target(

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

@@ -26,6 +26,7 @@ pub(super) fn spawn_agent_window(
     safety: Option<&DangerousApproval>,
     layout_placement: Option<&crate::lifecycle::launch::LayoutPlacement>,
     spawn_cwd_override: Option<&Path>,
+    tmux_endpoint_source: Option<&str>,
     // Issue 2 (Round 3b gate review §6): explicit owner_team_id override.
     // When `Some`, callers (restart/rebuild.rs, restart/agent.rs) thread the
     // resolved `selected.team_key` through here so the worker's MCP env /
@@ -205,6 +206,7 @@ pub(super) fn spawn_agent_window(
         let tmux_start_mode_pre_spawn =
             predict_tmux_start_mode(layout_placement, into_existing_session);
         let spawn_epoch = state_spawn_epoch_for_agent(workspace, agent_id);
+        let tmux_endpoint = transport.tmux_endpoint();
         let event_log = crate::event_log::EventLog::new(workspace);
         let _ = event_log.write(
             "provider.worker.spawn_argv",
@@ -220,6 +222,8 @@ pub(super) fn spawn_agent_window(
                 "tmux_start_mode": tmux_start_mode_pre_spawn,
                 "spawn_epoch": spawn_epoch,
                 "source": "restart",
+                "tmux_endpoint": tmux_endpoint,
+                "tmux_endpoint_source": tmux_endpoint_source.unwrap_or("transport"),
             }),
         );
     }
@@ -564,6 +568,27 @@ pub(crate) fn lifecycle_worker_transport_for_selected_state(
         .map_err(|e| LifecycleError::TeamSelect(e.to_string()))
 }
 
+pub(super) fn lifecycle_worker_tmux_backend_selection_for_state(
+    run_workspace: &Path,
+    state: &serde_json::Value,
+) -> Result<crate::tmux_backend::RuntimeTmuxBackendSelection, LifecycleError> {
+    if let Some(kind) = state.pointer("/transport/kind").and_then(|v| v.as_str()) {
+        if kind.eq_ignore_ascii_case("conpty") {
+            return Err(LifecycleError::TeamSelect(format!(
+                "backend_kind_mismatch: state.transport.kind={kind:?} but the legacy \
+                 tmux-typed lifecycle resolver was invoked; caller must migrate to \
+                 `lifecycle_worker_transport_for_selected_state` (Phase 1d Batch 2/3)"
+            )));
+        }
+    }
+    Ok(
+        crate::tmux_backend::tmux_backend_for_runtime_state_or_workspace(
+            run_workspace,
+            Some(state),
+        ),
+    )
+}
+
 pub(super) fn lifecycle_worker_tmux_backend_for_state(
     run_workspace: &Path,
     state: &serde_json::Value,

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

@@ -23,18 +23,53 @@ pub fn restart_with_session_convergence_deadline(
     team: Option<&str>,
     session_converge_deadline_ms: Option<u64>,
 ) -> Result<RestartReport, LifecycleError> {
-    let paths = lifecycle_paths(workspace, team)?;
-    let transport = lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
-    restart_with_transport_with_session_convergence_deadline(
-        workspace,
+    let context = resolve_restart_context(workspace, team)?;
+    restart_with_selected_team_and_transport(
+        context.selected,
         allow_fresh,
-        team,
-        &transport,
+        &context.transport,
         session_converge_deadline_ms,
         None,
+        Some(context.tmux_endpoint_source),
     )
 }
 
+struct ResolvedRestartContext {
+    selected: crate::state::selector::SelectedTeam,
+    transport: crate::tmux_backend::TmuxBackend,
+    tmux_endpoint_source: &'static str,
+}
+
+fn resolve_restart_context(
+    workspace: &Path,
+    team: Option<&str>,
+) -> Result<ResolvedRestartContext, LifecycleError> {
+    let resolved_ws = crate::model::paths::canonical_run_workspace(workspace)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    if crate::lifecycle::restart::input_has_no_local_team_context(&resolved_ws) {
+        return Err(LifecycleError::TeamSelect(format!(
+            "active team spec not found: input_workspace={} expected_runtime_dir={}",
+            workspace.display(),
+            crate::model::paths::runtime_dir(&resolved_ws).display()
+        )));
+    }
+    let selected = crate::state::selector::resolve_active_team(
+        workspace,
+        team,
+        crate::state::selector::SelectorMode::RequireSpec,
+    )
+    .map_err(|e| LifecycleError::TeamSelect(e.to_string()))?;
+    let transport_selection = lifecycle_worker_tmux_backend_selection_for_state(
+        &selected.run_workspace,
+        &selected.state,
+    )?;
+    Ok(ResolvedRestartContext {
+        selected,
+        transport: transport_selection.backend,
+        tmux_endpoint_source: transport_selection.tmux_endpoint_source.as_str(),
+    })
+}
+
 /// `restart` with an injected transport (tests: recording mock; prod: real TmuxBackend). The Route-B
 /// resume/fresh worker spawn + start_coordinator are wired here over `transport`. (rt-host-a sweep:
 /// was a stub returning RequirementUnmet at the spawn boundary — never spawned/resumed/started coordinator.)
@@ -129,6 +164,24 @@ pub fn restart_with_transport_with_session_convergence_deadline(
             expected.display()
         )));
     }
+    restart_with_selected_team_and_transport(
+        selected,
+        allow_fresh,
+        transport,
+        session_converge_deadline_ms,
+        readiness_deadline_ms,
+        None,
+    )
+}
+
+fn restart_with_selected_team_and_transport(
+    selected: crate::state::selector::SelectedTeam,
+    allow_fresh: bool,
+    transport: &dyn crate::transport::Transport,
+    session_converge_deadline_ms: Option<u64>,
+    readiness_deadline_ms: Option<u64>,
+    tmux_endpoint_source: Option<&str>,
+) -> Result<RestartReport, LifecycleError> {
     let lifecycle_lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
         workspace: &selected.run_workspace,
         operation: "restart",
@@ -380,6 +433,23 @@ 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) {
+            write_fake_harness_spawn_argv_event(
+                &selected.run_workspace,
+                decision,
+                &agent,
+                transport,
+                tmux_endpoint_source,
+            );
+            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 {
@@ -428,6 +498,7 @@ pub fn restart_with_transport_with_session_convergence_deadline(
             Some(&safety),
             layout_placement.as_ref(),
             None,
+            tmux_endpoint_source,
             // Issue 2 (Round 3b gate review §6): thread the resolved
             // selected.team_key so the worker MCP env carries the right
             // owner_team_id even when top-level active_team_key is stale.
@@ -773,7 +844,14 @@ pub fn restart_with_transport_with_session_convergence_deadline(
         restart_readiness_poll_interval(),
     )?;
     let attach_commands =
-        crate::tmux_backend::attach_command_for_session(&selected.run_workspace, &session_name)
+        crate::tmux_backend::attach_command_for_transport_session(transport, &session_name)
+            .or_else(|| {
+                crate::tmux_backend::attach_command_for_runtime_state_session_or_workspace(
+                    &selected.run_workspace,
+                    Some(&state),
+                    &session_name,
+                )
+            })
             .into_iter()
             .collect::<Vec<_>>();
     let mut next_actions = Vec::new();
@@ -1155,6 +1233,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 +1755,61 @@ 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 write_fake_harness_spawn_argv_event(
+    workspace: &Path,
+    decision: &RestartedAgent,
+    agent: &serde_json::Value,
+    transport: &dyn crate::transport::Transport,
+    tmux_endpoint_source: Option<&str>,
+) {
+    let _ = crate::event_log::EventLog::new(workspace).write(
+        "provider.worker.spawn_argv",
+        serde_json::json!({
+            "agent_id": decision.agent_id.as_str(),
+            "provider": agent_provider(agent),
+            "argv": [],
+            "session_id_in_argv": null,
+            "expected_session_id": decision.session_id.as_ref().map(|s| s.as_str()),
+            "tmux_start_mode": "fake_harness",
+            "source": "restart",
+            "tmux_endpoint": transport.tmux_endpoint(),
+            "tmux_endpoint_source": tmux_endpoint_source.unwrap_or("transport"),
+        }),
+    );
+}
+
 fn restart_failed_agent(
     decision: &RestartedAgent,
     phase: impl Into<String>,
@@ -2165,6 +2310,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 +2347,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/lifecycle/tests/phase_golden.rs

@@ -524,7 +524,7 @@ fn normalize_string(text: String, ctx: &mut NormalizeCtx, key: Option<&str>) ->
     if key_is_timestamp(key) {
         return json!("<TS>");
     }
-    if key.contains("endpoint") {
+    if key.contains("endpoint") && value_looks_like_endpoint_path(&text) {
         return json!("<SOCKET>");
     }
     if key_is_id(key, &text) {
@@ -557,6 +557,13 @@ fn normalize_path_string(text: &str, ctx: &NormalizeCtx) -> String {
     normalize_socket_token(&out)
 }
 
+fn value_looks_like_endpoint_path(text: &str) -> bool {
+    text.starts_with('/')
+        || text.starts_with("ta-")
+        || text.contains("/tmux-")
+        || text.contains("tmux-")
+}
+
 fn normalize_team_agent_binary_path(text: &str) -> String {
     let mut out = text.to_string();
     // 0.5.0 hermetic 教训「环境路径类 token 化」的直接延伸

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

@@ -566,6 +566,14 @@ pub(crate) fn attach_command_for_session(
     ))
 }
 
+pub(crate) fn attach_command_for_transport_session(
+    transport: &dyn crate::transport::Transport,
+    session_name: &SessionName,
+) -> Option<String> {
+    let endpoint = transport.tmux_endpoint()?;
+    Some(attach_command_for_endpoint_session(&endpoint, session_name))
+}
+
 /// Bug #7 (prerelease 0.4.0 gate review §6): when the runtime state carries a
 /// persisted `tmux_endpoint` / `tmux_socket` (e.g. `/private/tmp/tmux-501/default`),
 /// the attach command MUST point at THAT endpoint, not the workspace-hash
@@ -591,6 +599,26 @@ pub(crate) fn attach_command_for_runtime_state_or_workspace(
     attach_command_for_workspace(workspace, session_name, window_name)
 }
 
+pub(crate) fn attach_command_for_runtime_state_session_or_workspace(
+    workspace: &Path,
+    state: Option<&serde_json::Value>,
+    session_name: &SessionName,
+) -> Option<String> {
+    if let Some((endpoint, _source)) = runtime_tmux_endpoint_from_state(state) {
+        return Some(attach_command_for_endpoint_session(endpoint, session_name));
+    }
+    attach_command_for_session(workspace, session_name)
+}
+
+fn attach_command_for_endpoint_session(endpoint: &str, session_name: &SessionName) -> String {
+    let flag = if Path::new(endpoint).is_absolute() {
+        "-S"
+    } else {
+        "-L"
+    };
+    format!("tmux {flag} {endpoint} attach -t {}", session_name.as_str())
+}
+
 pub(crate) fn attach_commands_for_windows<'a>(
     workspace: &Path,
     session_name: &SessionName,

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

@@ -1,3 +1,5 @@
+use std::process::Command;
+
 use serde_json::{json, Value};
 
 use crate::transport::{PaneInfo, SessionName, Transport};
@@ -30,6 +32,89 @@ 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 },
@@ -249,6 +334,36 @@ fn session_exists_on_endpoint(endpoint: &str, session: &str) -> bool {
         .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.13",
+  "version": "0.5.15",
   "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.13",
-    "@team-agent/cli-darwin-x64": "0.5.13",
-    "@team-agent/cli-linux-x64": "0.5.13"
+    "@team-agent/cli-darwin-arm64": "0.5.15",
+    "@team-agent/cli-darwin-x64": "0.5.15",
+    "@team-agent/cli-linux-x64": "0.5.15"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",