@team-agent/installer 0.5.28 → 0.5.31

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

@@ -440,21 +440,18 @@ pub fn claim_leader(
         .unwrap_or_default();
     let raw_state = crate::state::persist::load_runtime_state(workspace)?;
     let event_log = crate::event_log::EventLog::new(workspace);
-    // Phase 1d Batch 6: factory tmux channel helpers for grep-visibility.
-    // Tmux-only leader-claim path (caller pane enumeration).
-    let mut targets = crate::transport_factory::tmux_workspace_transport(workspace)
-        .list_targets()
-        .unwrap_or_default();
-    targets.extend(
-        crate::transport_factory::tmux_default_transport()
-            .list_targets()
-            .unwrap_or_default(),
-    );
-    let caller_pane_info = targets
+    let targets = claim_leader_targets(workspace, &raw_state);
+    let caller_candidate = targets
         .iter()
-        .find(|target| target.pane_id.as_str() == caller);
-    let caller_target =
-        caller_pane_info.and_then(|target| claim_target_from_pane_info(workspace, target));
+        .filter(|target| target.info.pane_id.as_str() == caller)
+        .min_by_key(|target| target.source.priority());
+    let caller_pane_info = caller_candidate.map(|target| &target.info);
+    let caller_target = caller_candidate.and_then(|target| {
+        claim_target_from_pane_info(workspace, &target.info).map(|mut claim_target| {
+            claim_target.endpoint = target.endpoint.clone();
+            claim_target
+        })
+    });
     let env_team = std::env::var("TEAM_AGENT_TEAM_ID")
         .ok()
         .filter(|team| !team.is_empty());
@@ -489,7 +486,7 @@ pub fn claim_leader(
     } else {
         raw_state
     };
-    let liveness = AnyPaneLiveness::from_targets(&targets);
+    let liveness = AnyPaneLiveness::from_claim_targets(&targets);
     let result = claim_lease_no_incident_with_target(
         workspace,
         &mut state,
@@ -634,8 +631,23 @@ fn claim_lease_no_incident_with_target(
     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 observed_endpoint = caller_target.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")
+        } else if current_endpoint.is_some() {
+            Some("fallback_tmux_env")
+        } else {
+            None
+        };
         let (mut topology_convergence, converged) =
-            apply_endpoint_convergence(state, team_id, current_endpoint.as_deref(), pre_epoch);
+            apply_endpoint_convergence(
+                state,
+                team_id,
+                convergence_candidate,
+                candidate_source,
+                pre_epoch,
+            );
         if converged {
             write_claim_state(workspace, state, scoped_team, team)?;
             topology_convergence = verify_persisted_topology_convergence(
@@ -796,7 +808,8 @@ fn claim_lease_no_incident_with_target(
     }
     let next_epoch = OwnerEpoch(pre_epoch.0.saturating_add(1));
     let provider = caller_target.map_or_else(|| prior_provider(state), |target| target.provider);
-    let receiver = make_receiver(
+    let observed_endpoint = caller_target.and_then(|target| target.endpoint.clone());
+    let mut receiver = make_receiver(
         provider,
         &non_empty_caller_pane,
         &identity.leader_session_uuid,
@@ -804,10 +817,26 @@ fn claim_lease_no_incident_with_target(
         Discovery::ClaimLeader,
         caller_target.and_then(|target| target.pane_info.clone()),
     );
+    if let Some(endpoint) = observed_endpoint.as_ref() {
+        receiver.tmux_socket = Some(endpoint.clone());
+    }
     let owner = make_owner(provider, &non_empty_caller_pane, &identity, next_epoch);
     write_binding_to_state(state, &receiver, &owner)?;
+    let candidate_source = if observed_endpoint.is_some() {
+        Some("observed_target_endpoint")
+    } else if receiver.tmux_socket.is_some() {
+        Some("fallback_tmux_env")
+    } else {
+        None
+    };
     let (mut topology_convergence, converged) =
-        apply_endpoint_convergence(state, team_id, receiver.tmux_socket.as_deref(), next_epoch);
+        apply_endpoint_convergence(
+            state,
+            team_id,
+            receiver.tmux_socket.as_deref(),
+            candidate_source,
+            next_epoch,
+        );
     write_claim_state(workspace, state, scoped_team, team)?;
     if converged {
         topology_convergence = verify_persisted_topology_convergence(
@@ -884,13 +913,17 @@ fn apply_endpoint_convergence(
     state: &mut Value,
     team_id: &TeamKey,
     candidate_endpoint: Option<&str>,
+    candidate_source: Option<&'static str>,
     owner_epoch: OwnerEpoch,
 ) -> (Option<Value>, bool) {
-    let Some(candidate_endpoint) = candidate_endpoint
+    let explicit_candidate = candidate_endpoint
         .filter(|endpoint| !endpoint.is_empty())
-        .map(str::to_string)
-        .or_else(|| state_tmux_socket_candidate(state, team_id.as_str()))
-    else {
+        .map(str::to_string);
+    let (candidate_endpoint, candidate_source) = if let Some(endpoint) = explicit_candidate {
+        (endpoint, candidate_source.unwrap_or("candidate"))
+    } else if let Some(endpoint) = state_tmux_socket_candidate(state, team_id.as_str()) {
+        (endpoint, "fallback_state")
+    } else {
         return (None, false);
     };
     match crate::topology::endpoint_convergence_decision(
@@ -903,6 +936,7 @@ fn apply_endpoint_convergence(
             Some(json!({
                 "status": "unknown",
                 "new_tmux_endpoint": candidate_endpoint,
+                "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
             })),
             false,
@@ -910,14 +944,17 @@ fn apply_endpoint_convergence(
         crate::topology::EndpointConvergenceDecision::RefuseLiveOldEndpoint {
             old_endpoint,
             new_endpoint,
+            reason,
         } => (
             Some(json!({
                 "status": "not_converged_old_endpoint_live",
                 "old_tmux_endpoint": old_endpoint,
                 "new_tmux_endpoint": new_endpoint,
+                "reason": reason,
+                "candidate_source": candidate_source,
                 "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"
+                    "old tmux endpoint {old_endpoint} still has this team's session or pane tuple; run team-agent diagnose --json before retrying restart"
                 ),
             })),
             false,
@@ -925,12 +962,14 @@ fn apply_endpoint_convergence(
         crate::topology::EndpointConvergenceDecision::Converge {
             old_endpoint,
             new_endpoint,
+            reason,
         } => {
             let metadata = json!({
                 "status": "converged",
                 "old_tmux_endpoint": old_endpoint,
                 "new_tmux_endpoint": new_endpoint,
-                "reason": "old_endpoint_dead",
+                "reason": reason,
+                "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
             });
             write_endpoint_fields(state, team_id.as_str(), &new_endpoint);
@@ -1175,6 +1214,94 @@ struct LeaderClaimTarget {
     leader_session_uuid: Option<crate::model::ids::LeaderSessionUuid>,
     team_id: Option<String>,
     pane_info: Option<PaneInfo>,
+    endpoint: Option<String>,
+}
+
+#[derive(Clone)]
+struct ClaimLeaderTargetCandidate {
+    info: PaneInfo,
+    endpoint: Option<String>,
+    source: ClaimLeaderTargetSource,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum ClaimLeaderTargetSource {
+    StateRecorded,
+    Workspace,
+    CurrentTmux,
+    Default,
+}
+
+impl ClaimLeaderTargetSource {
+    fn priority(self) -> u8 {
+        match self {
+            Self::StateRecorded => 0,
+            Self::Workspace => 1,
+            Self::CurrentTmux => 2,
+            Self::Default => 3,
+        }
+    }
+}
+
+fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTargetCandidate> {
+    let mut targets = Vec::new();
+    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| ClaimLeaderTargetCandidate {
+                    info,
+                    endpoint: resolved_endpoint.clone(),
+                    source: ClaimLeaderTargetSource::CurrentTmux,
+                }),
+        );
+    }
+    for endpoint in state_recorded_tmux_endpoints(state) {
+        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| ClaimLeaderTargetCandidate {
+                    info,
+                    endpoint: resolved_endpoint.clone(),
+                    source: ClaimLeaderTargetSource::StateRecorded,
+                }),
+        );
+    }
+    let workspace_backend = crate::transport_factory::tmux_workspace_transport(workspace);
+    let workspace_endpoint = workspace_backend.tmux_endpoint();
+    targets.extend(
+        workspace_backend
+            .list_targets()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|info| ClaimLeaderTargetCandidate {
+                info,
+                endpoint: workspace_endpoint.clone(),
+                source: ClaimLeaderTargetSource::Workspace,
+            }),
+    );
+    let default_backend = crate::transport_factory::tmux_default_transport();
+    let default_endpoint = default_backend.tmux_endpoint();
+    targets.extend(
+        default_backend
+            .list_targets()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|info| ClaimLeaderTargetCandidate {
+                info,
+                endpoint: default_endpoint.clone(),
+                source: ClaimLeaderTargetSource::Default,
+            }),
+    );
+    targets
 }
 
 fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<LeaderClaimTarget> {
@@ -1191,6 +1318,7 @@ fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<Le
         leader_session_uuid: target_leader_session_uuid(target),
         team_id: target.leader_env.get("TEAM_AGENT_TEAM_ID").filter(|raw| !raw.is_empty()).cloned(),
         pane_info: Some(target.clone()),
+        endpoint: None,
     })
 }
 
@@ -1290,11 +1418,11 @@ struct AnyPaneLiveness {
 }
 
 impl AnyPaneLiveness {
-    fn from_targets(targets: &[PaneInfo]) -> Self {
+    fn from_claim_targets(targets: &[ClaimLeaderTargetCandidate]) -> Self {
         Self {
             live_panes: targets
                 .iter()
-                .map(|target| target.pane_id.as_str().to_string())
+                .map(|target| target.info.pane_id.as_str().to_string())
                 .collect(),
         }
     }
@@ -1677,10 +1805,16 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
         .map(|_| crate::state::projection::team_state_key(&existing));
     let existing_active_key = existing.get("active_team_key").and_then(Value::as_str);
     let updates_active_team = existing_active_key == Some(target_key);
+    let writes_endpoint_convergence = state
+        .get("topology_convergence")
+        .and_then(|marker| marker.get("status"))
+        .and_then(Value::as_str)
+        == Some("converged");
     let mut merged = if existing_primary_key
         .as_deref()
         .is_none_or(|key| key == target_key)
         || updates_active_team
+        || writes_endpoint_convergence
     {
         value_object(state)
     } else {
@@ -1697,7 +1831,12 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
     // / coordinator tick / promote sibling. `had_existing_teams` /
     // primary/active key computations are retained as dead writes only
     // via _ binding — they no longer gate any owner promote.
-    let _ = (had_existing_teams, existing_primary_key, existing_active_key);
+    let _ = (
+        had_existing_teams,
+        existing_primary_key,
+        existing_active_key,
+        writes_endpoint_convergence,
+    );
     merged.insert("teams".to_string(), Value::Object(teams));
     crate::state::persist::save_runtime_state(workspace, &Value::Object(merged))?;
     Ok(())

package/crates/team-agent/src/lifecycle/launch.rs

@@ -4130,7 +4130,12 @@ fn upsert_agent_state_from_role(
 
 /// E5 Bug1:把 add-agent 就地编译出的 agent 条目注入 base team spec(`agents` 列表 +
 /// `routing.rules` 加 `route-<id>`),复刻 [`compile_team`] 的路由规则形态。不落任何文件。
-fn inject_agent_into_spec(
+///
+/// 0.5.30 (`.team/artifacts/add-agent-restart-saveconflict-locate.md` §5.2):
+/// `pub(crate)` 让 restart/rebuild.rs::rebuild_runtime_spec_from_roles 复用
+/// 同一去重注入逻辑,把 add-agent 记录的 dynamic_role_file 合并回 restart
+/// 重建 spec,防止 live helper 被 prune 后触发 SaveConflict。行为不变。
+pub(crate) fn inject_agent_into_spec(
     spec: &mut Value,
     agent: Value,
     agent_id: &str,

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

@@ -433,7 +433,9 @@ fn restart_with_selected_team_and_transport(
             &decision.agent_id,
             &raw_agent,
         );
-        if has_endpoint_convergence_marker(&state) && is_fake_model_harness_agent(&agent) {
+        if endpoint_convergence_fake_harness_enabled(&state)
+            && is_fake_model_harness_agent(&agent)
+        {
             write_fake_harness_spawn_argv_event(
                 &selected.run_workspace,
                 decision,
@@ -1242,7 +1244,7 @@ fn restart_worker_panes_addressable(
     if decisions.is_empty() {
         return true;
     }
-    if has_endpoint_convergence_marker(state)
+    if endpoint_convergence_fake_harness_enabled(state)
         && decisions.iter().all(|decision| {
             state
                 .get("agents")
@@ -2354,6 +2356,11 @@ fn rebuild_runtime_spec_from_roles(
     {
         crate::lifecycle::launch::override_spec_session_name(&mut spec, session_name);
     }
+    // 0.5.30 (`.team/artifacts/add-agent-restart-saveconflict-locate.md` §4/§11):
+    // 把 add-agent 记录的 dynamic_role_file 合并回 restart 重建 spec —— 单一真相 =
+    // 静态 team_dir/agents/*.md + state 记录的 dynamic role source。缺文件 fail-closed
+    // 三行式,不静默 prune 已 live 的 helper(persist SaveConflict 保护继续生效)。
+    merge_state_dynamic_role_files(&mut spec, run_workspace, &team_dir, team_key, state)?;
     // 写 runtime spec(覆盖,原子 tmp+rename;Bug2)。
     let spec_path = crate::model::paths::runtime_spec_path(run_workspace, team_key);
     crate::lifecycle::launch::write_spec_atomic(&spec_path, &spec)?;
@@ -2366,6 +2373,86 @@ fn rebuild_runtime_spec_from_roles(
     Ok(spec)
 }
 
+/// 0.5.30 (`add-agent-restart-saveconflict-locate.md` §4/§11): 把 add-agent
+/// 写入 `state.agents.<id>.dynamic_role_file` 的动态 role 文档合并回 restart
+/// 重建 spec。规则:
+/// - path 为空 / 缺失字段 → 跳过(纯静态 team_dir agent);
+/// - path 存在但文件 missing → fail-closed 三行式错误(不 prune live helper);
+/// - path 有效 → 编译成 CompiledRole,校验 compiled.id 等于 agent_id;
+/// - 复用 launch::inject_agent_into_spec 去重注入(名字已在 spec → 跳过)。
+fn merge_state_dynamic_role_files(
+    spec: &mut YamlValue,
+    run_workspace: &Path,
+    team_dir: &Path,
+    team_key: &str,
+    state: &serde_json::Value,
+) -> Result<(), LifecycleError> {
+    let Some(agents) = state.get("agents").and_then(serde_json::Value::as_object) else {
+        return Ok(());
+    };
+    if agents.is_empty() {
+        return Ok(());
+    }
+    let team_meta = crate::compiler::read_front_matter(&team_dir.join("TEAM.md"))
+        .map(|(meta, _)| meta)
+        .unwrap_or(YamlValue::Null);
+    let workspace_s = spec
+        .get("team")
+        .and_then(|team| team.get("workspace"))
+        .and_then(YamlValue::as_str)
+        .unwrap_or_else(|| team_dir.to_str().unwrap_or_default())
+        .to_string();
+    let mut dynamic_ids: Vec<(String, String)> = agents
+        .iter()
+        .filter_map(|(agent_id, agent)| {
+            agent
+                .get("dynamic_role_file")
+                .and_then(serde_json::Value::as_str)
+                .filter(|s| !s.is_empty())
+                .map(|raw| (agent_id.clone(), raw.to_string()))
+        })
+        .collect();
+    dynamic_ids.sort_by(|(a, _), (b, _)| a.cmp(b));
+    for (agent_id, raw_path) in dynamic_ids {
+        let role_path = {
+            let candidate = std::path::PathBuf::from(&raw_path);
+            if candidate.is_absolute() {
+                candidate
+            } else {
+                run_workspace.join(&candidate)
+            }
+        };
+        if !role_path.exists() {
+            // N38 三行式:error / action / log。不 prune live helper。
+            return Err(LifecycleError::TeamSelect(format!(
+                "cannot restart: dynamic role file missing for agent '{agent_id}' in team \
+                 '{team_key}': {}. \
+                 action: restore the dynamic role file at that path, or run team-agent \
+                 remove-agent {agent_id} --force to drop the dynamic worker before restart. \
+                 log: workspace={}",
+                role_path.display(),
+                run_workspace.display(),
+            )));
+        }
+        let compiled = crate::compiler::compile_role_agent(&role_path, &team_meta, &workspace_s)
+            .map_err(|e| LifecycleError::Compile(e.to_string()))?;
+        if compiled.id != agent_id {
+            return Err(LifecycleError::Compile(format!(
+                "dynamic role file for agent '{agent_id}' declares name '{}' at {}; \
+                 restart cannot rename a live worker. \
+                 action: fix the role file's front-matter name to match agent_id, or run \
+                 team-agent remove-agent {agent_id} --force before restart. \
+                 log: workspace={}",
+                compiled.id,
+                role_path.display(),
+                run_workspace.display(),
+            )));
+        }
+        crate::lifecycle::launch::inject_agent_into_spec(spec, compiled.agent, &compiled.id)?;
+    }
+    Ok(())
+}
+
 fn load_endpoint_convergence_runtime_spec(
     run_workspace: &Path,
     team_key: &str,
@@ -2404,6 +2491,11 @@ fn has_endpoint_convergence_marker(state: &serde_json::Value) -> bool {
         == Some("converged")
 }
 
+fn endpoint_convergence_fake_harness_enabled(state: &serde_json::Value) -> bool {
+    has_endpoint_convergence_marker(state)
+        && std::env::var_os("TEAM_AGENT_TEST_ENDPOINT_CONVERGENCE_HARNESS_SPEC_FALLBACK").is_some()
+}
+
 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")

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

@@ -26,6 +26,7 @@ pub mod ownership;
 pub mod paths;
 pub mod persist;
 pub mod projection;
+pub mod repository;
 pub mod selector;
 
 use serde_json::Value;