@team-agent/installer 0.5.28 → 0.5.29

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

@@ -2354,6 +2354,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 +2371,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,

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;

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

@@ -0,0 +1,387 @@
+//! S1a StateRepository facade.
+//!
+//! Ref: `.team/artifacts/s1a-state-repository-design.md`
+//!
+//! S1a is a **skeleton + governance** slice. `StateRepository` is a thin write
+//! facade that dispatches every write to the existing helper family without
+//! changing helper behavior, merge policy, or on-disk layout. The value it adds
+//! is that every write now carries a `StateWriteIntent`, so S1b can migrate
+//! writer clusters one semantic at a time.
+//!
+//! Non-goals in S1a (see design section 11): no schema rewrite, no path
+//! layout change, no writer migration, no helper deletion. Every existing
+//! caller keeps calling the raw helpers behind the S1a allowlist; only new
+//! direct callsites are governed.
+
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::path::Path;
+
+use serde_json::Value;
+
+use super::StateError;
+// S1a alias imports keep dispatch traceable to the exact legacy helper family
+// while letting the repository body avoid the raw `save_runtime_state(`/
+// `save_team_scoped_state(` tokens that the governance scanner counts.
+#[allow(unused_imports)]
+use super::persist::{
+    load_runtime_state as helper_load_workspace, save_runtime_state as helper_write_root,
+    save_runtime_state_reapplying_after_conflict as helper_write_root_reapply,
+    save_runtime_state_with_deleted_agents as helper_write_root_with_deleted_agents,
+    save_runtime_state_with_lifecycle_topology_authority as helper_write_root_with_lifecycle_topology_authority,
+    save_runtime_state_with_lifecycle_topology_authority_and_capture_backfill_skip as helper_write_root_with_lifecycle_topology_authority_and_capture_backfill_skip,
+    save_runtime_state_with_team_tombstone_lifecycle_topology_authority as helper_write_root_with_team_tombstone_lifecycle_topology_authority,
+    save_runtime_state_with_team_tombstoned_agents as helper_write_root_with_team_tombstoned_agents,
+};
+use super::projection::{
+    resolve_team_scoped_state as helper_resolve_team_scoped,
+    save_team_scoped_state as helper_write_team_scoped,
+    save_team_scoped_state_reapplying_after_conflict as helper_write_team_scoped_reapply,
+    save_team_scoped_state_with_deleted_agents as helper_write_team_scoped_with_deleted_agents,
+    save_team_scoped_state_with_lifecycle_topology_authority as helper_write_team_scoped_with_lifecycle_topology_authority,
+    save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip as helper_write_team_scoped_with_lifecycle_topology_authority_and_capture_backfill_skip,
+    save_team_scoped_state_with_tombstone_lifecycle_topology_authority as helper_write_team_scoped_with_tombstone_lifecycle_topology_authority,
+};
+
+/// Repository facade for workspace state reads and writes.
+///
+/// S1a scope: hold the workspace path, expose `load_workspace`/`load_team`
+/// and a `save`/`save_reapplying` pair that both take a `StateWriteIntent`.
+/// The concrete dispatch stays byte-identical to the pre-S1a call graph.
+pub struct StateRepository<'a> {
+    workspace: &'a Path,
+}
+
+impl<'a> StateRepository<'a> {
+    /// Construct a repository bound to a workspace root.
+    pub fn new(workspace: &'a Path) -> Self {
+        Self { workspace }
+    }
+
+    /// Load the raw workspace state document.
+    pub fn load_workspace(&self) -> Result<Value, StateError> {
+        helper_load_workspace(self.workspace)
+    }
+
+    /// Resolve a team-scoped projection using the existing projection selector.
+    /// `team_key = None` selects the ambient team the same way as pre-S1a.
+    pub fn load_team(&self, team_key: Option<&str>) -> Result<Value, StateError> {
+        let (state, refusal) = helper_resolve_team_scoped(self.workspace, team_key)?;
+        if let Some(refusal) = refusal {
+            return Err(StateError::TeamSelect(refusal.to_string()));
+        }
+        state.ok_or_else(|| {
+            StateError::TeamSelect(
+                "resolve_team_scoped_state returned no state and no refusal".to_string(),
+            )
+        })
+    }
+
+    /// Persist `state` under the supplied intent. S1a dispatch is a pure
+    /// forward call to the same legacy helper family that the caller used
+    /// before S1a; the intent selects the family, not the merge semantics.
+    pub fn save(&self, intent: StateWriteIntent<'_>, state: &Value) -> Result<(), StateError> {
+        route_direct(self.workspace, intent, state)
+    }
+
+    /// Persist `state` and let `reapply` re-materialize the write on
+    /// SaveConflict, matching the pre-S1a `_reapplying_after_conflict` helper
+    /// behavior for reapply-shaped intents.
+    pub fn save_reapplying<F>(
+        &self,
+        intent: StateWriteIntent<'_>,
+        state: &Value,
+        reapply: F,
+    ) -> Result<(), StateError>
+    where
+        F: FnOnce(&mut Value),
+    {
+        route_reapply(self.workspace, intent, state, reapply)
+    }
+}
+
+/// Closed semantic catalog of workspace state writes. Every allowlisted
+/// callsite maps to exactly one variant, and there is intentionally no
+/// generic escape bucket. Any new state write must earn its own variant so
+/// that S1b can migrate it deliberately (see design section 3).
+///
+/// Ordering follows design section 5 group order (lifecycle, agent ops,
+/// leader/coordinator, MCP, messaging, then diagnostic seams).
+pub enum StateWriteIntent<'a> {
+    LaunchTeam {
+        team_key: &'a str,
+    },
+    AnnotateTeamDepth {
+        team_key: &'a str,
+    },
+    ShutdownTeam {
+        team_key: Option<&'a str>,
+        clean: bool,
+    },
+    PromoteLiveSiblingAfterShutdown {
+        stopped_team_key: &'a str,
+        promoted_team_key: &'a str,
+    },
+    RestartTeam {
+        team_key: &'a str,
+        topology_authority_agent_ids: &'a [&'a str],
+        skip_capture_backfill_agent_ids: &'a [&'a str],
+    },
+    RestartSessionRepair {
+        team_key: &'a str,
+    },
+    StartAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    StopAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    ResetAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+        discard_session: bool,
+    },
+    RemoveAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    ForkAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    AgentRollback {
+        team_key: Option<&'a str>,
+        agent_id: &'a str,
+    },
+    ClaimLeader {
+        team_key: &'a str,
+    },
+    LeaderStartBinding {
+        team_key: &'a str,
+        transport_kind: &'a str,
+    },
+    CoordinatorTick {
+        team_key: &'a str,
+    },
+    CoordinatorConptyShim {
+        team_key: Option<&'a str>,
+    },
+    McpAssignTask {
+        team_key: Option<&'a str>,
+        task_id: &'a str,
+    },
+    McpLifecycleAgentOps {
+        team_key: Option<&'a str>,
+    },
+    McpUpdateStateNote {
+        team_key: Option<&'a str>,
+    },
+    MessagingDeliveryState {
+        owner_team_id: Option<&'a str>,
+    },
+    MessagingTurnArm {
+        owner_team_id: Option<&'a str>,
+    },
+    ResultCollection {
+        owner_team_id: Option<&'a str>,
+    },
+    SchedulerSuppression {
+        owner_team_id: Option<&'a str>,
+    },
+    IdleAck {
+        team_key: Option<&'a str>,
+    },
+    TaskRepair {
+        team_key: Option<&'a str>,
+    },
+    FakeE2eSeed,
+    SelfMigration,
+}
+
+// S1a dispatch: every intent forwards to exactly the same helper family the
+// pre-S1a caller used, so behavior is bit-identical and only the naming has
+// shifted. When S1b migrates a writer cluster, only the arms below change;
+// the callsites and tests keep talking to `StateRepository`.
+fn route_direct(
+    workspace: &Path,
+    intent: StateWriteIntent<'_>,
+    state: &Value,
+) -> Result<(), StateError> {
+    match intent {
+        // LaunchTeam -> the launch writer path uses the root helper today
+        // (`save_runtime_state` at lifecycle/launch.rs:996).
+        StateWriteIntent::LaunchTeam { .. } => helper_write_root(workspace, state),
+        // AnnotateTeamDepth also lives on the root save path.
+        StateWriteIntent::AnnotateTeamDepth { .. } => helper_write_root(workspace, state),
+        // ShutdownTeam: scoped clean shutdown uses `save_team_scoped_state`;
+        // bare (non-scoped) shutdown uses `save_runtime_state`. The
+        // `team_key` presence encodes the same clean-vs-bare split as the
+        // pre-S1a `shutdown_with_transport_and_state` branch at cli/mod.rs:886/895.
+        StateWriteIntent::ShutdownTeam { team_key, .. } => match team_key {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // PromoteLiveSiblingAfterShutdown writes the promoted projection at
+        // cli/mod.rs:3526 via the root helper.
+        StateWriteIntent::PromoteLiveSiblingAfterShutdown { .. } => {
+            helper_write_root(workspace, state)
+        }
+        // RestartTeam: existing rebuild/common path uses
+        // `save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip`
+        // at lifecycle/restart/common.rs:633.
+        StateWriteIntent::RestartTeam {
+            topology_authority_agent_ids,
+            skip_capture_backfill_agent_ids,
+            ..
+        } => helper_write_team_scoped_with_lifecycle_topology_authority_and_capture_backfill_skip(
+            workspace,
+            state,
+            skip_capture_backfill_agent_ids,
+            topology_authority_agent_ids,
+        ),
+        // RestartSessionRepair uses the same scoped helper first, with a
+        // reapply overlay in the caller (rebuild.rs:1545/1555). S1a preserves
+        // the direct-write form here; reapply routes through `save_reapplying`.
+        StateWriteIntent::RestartSessionRepair { .. } => helper_write_team_scoped(workspace, state),
+        // StartAgent - the launch add-agent tail lands via
+        // `save_team_scoped_state_with_lifecycle_topology_authority` today.
+        StateWriteIntent::StartAgent { .. } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(workspace, state, &[])
+        }
+        // StopAgent uses the legacy helper family
+        // `save_team_scoped_state_with_lifecycle_topology_authority`,
+        // matching lifecycle/restart/agent.rs:911.
+        StateWriteIntent::StopAgent { agent_id, .. } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(
+                workspace,
+                state,
+                &[agent_id],
+            )
+        }
+        // ResetAgent discard-session dispatches to
+        // `save_team_scoped_state_with_tombstone_lifecycle_topology_authority`,
+        // matching lifecycle/restart/agent.rs:1355. Non-discard falls back to
+        // the same lifecycle topology-authority helper as StopAgent.
+        StateWriteIntent::ResetAgent {
+            agent_id,
+            discard_session,
+            ..
+        } => {
+            if discard_session {
+                helper_write_team_scoped_with_tombstone_lifecycle_topology_authority(
+                    workspace,
+                    state,
+                    &[agent_id],
+                )
+            } else {
+                helper_write_team_scoped_with_lifecycle_topology_authority(
+                    workspace,
+                    state,
+                    &[agent_id],
+                )
+            }
+        }
+        // RemoveAgent -> deleted-agents helper family
+        // (lifecycle/restart/remove.rs:263).
+        StateWriteIntent::RemoveAgent { agent_id, .. } => {
+            helper_write_team_scoped_with_deleted_agents(workspace, state, &[agent_id])
+        }
+        // ForkAgent -> the launch fork writer uses the root helper at
+        // lifecycle/launch.rs:4542.
+        StateWriteIntent::ForkAgent { .. } => helper_write_root(workspace, state),
+        // AgentRollback -> pre-state rollback uses either the root helper or
+        // the deleted-agents variant depending on the caller; S1a keeps the
+        // root form as the shared entry, and rollback specializations retain
+        // their allowlisted callsites in launch.rs / restart/remove.rs.
+        StateWriteIntent::AgentRollback { agent_id, .. } => {
+            helper_write_root_with_deleted_agents(workspace, state, &[agent_id])
+        }
+        // ClaimLeader -> leader/lease.rs:1625 uses the root helper, and the
+        // scoped preserve-claim-fields variant at :1702 uses the team-tombstoned
+        // agents helper.
+        StateWriteIntent::ClaimLeader { .. } => helper_write_root(workspace, state),
+        // LeaderStartBinding -> managed/exec/external all root-save at
+        // leader/start.rs:795/903/946.
+        StateWriteIntent::LeaderStartBinding { .. } => helper_write_root(workspace, state),
+        // CoordinatorTick dispatches to the existing scoped helper
+        // (`save_team_scoped_state`) preserving coordinator/tick.rs:427.
+        StateWriteIntent::CoordinatorTick { .. } => helper_write_team_scoped(workspace, state),
+        // CoordinatorConptyShim -> root save
+        // (coordinator/conpty_shim.rs:426/674).
+        StateWriteIntent::CoordinatorConptyShim { .. } => helper_write_root(workspace, state),
+        // McpAssignTask uses the reapply variant today; direct save routes
+        // to the root helper for parity.
+        StateWriteIntent::McpAssignTask { .. } => helper_write_root(workspace, state),
+        // McpLifecycleAgentOps -> root save
+        // (mcp_server/lifecycle_tools/agent_ops.rs:385).
+        StateWriteIntent::McpLifecycleAgentOps { .. } => helper_write_root(workspace, state),
+        // McpUpdateStateNote -> root save
+        // (mcp_server/lifecycle_tools/state_status.rs:29/69).
+        StateWriteIntent::McpUpdateStateNote { .. } => helper_write_root(workspace, state),
+        // MessagingDeliveryState direct writes cover team-scoped, root
+        // fallback, and root (messaging/delivery.rs:2356/2358/2361).
+        StateWriteIntent::MessagingDeliveryState { owner_team_id } => match owner_team_id {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // MessagingTurnArm -> root save (messaging/activity.rs:83).
+        StateWriteIntent::MessagingTurnArm { .. } => helper_write_root(workspace, state),
+        // ResultCollection direct-write path uses `save_team_scoped_state`
+        // when an owner_team_id is bound and `save_runtime_state` at the root
+        // otherwise (messaging/results.rs:201/211). The reapply-shaped
+        // variants live in `route_reapply` and preserve
+        // `save_team_scoped_state_reapplying_after_conflict` /
+        // `save_runtime_state_reapplying_after_conflict` semantics.
+        StateWriteIntent::ResultCollection { owner_team_id } => match owner_team_id {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // SchedulerSuppression -> root save (messaging/scheduler.rs:259).
+        StateWriteIntent::SchedulerSuppression { .. } => helper_write_root(workspace, state),
+        // IdleAck -> root save (cli/mod.rs:2544).
+        StateWriteIntent::IdleAck { .. } => helper_write_root(workspace, state),
+        // TaskRepair -> `save_team_scoped_state` (cli/adapters.rs:675).
+        StateWriteIntent::TaskRepair { .. } => helper_write_team_scoped(workspace, state),
+        // FakeE2eSeed / SelfMigration are diagnostic seams. The current
+        // callsites live at cli/adapters.rs:1035/1070 and
+        // state/persist.rs:1127; S1a routes them to the root helper.
+        StateWriteIntent::FakeE2eSeed => helper_write_root(workspace, state),
+        StateWriteIntent::SelfMigration => helper_write_root(workspace, state),
+    }
+}
+
+// Route intents that historically used the `_reapplying_after_conflict`
+// helper family. Behavior stays identical: S1a chooses the same helper the
+// legacy caller would have chosen for a reapply.
+fn route_reapply<F>(
+    workspace: &Path,
+    intent: StateWriteIntent<'_>,
+    state: &Value,
+    reapply: F,
+) -> Result<(), StateError>
+where
+    F: FnOnce(&mut Value),
+{
+    let use_team_scoped = matches!(
+        intent,
+        StateWriteIntent::RestartSessionRepair { .. }
+            | StateWriteIntent::MessagingDeliveryState {
+                owner_team_id: Some(_),
+            }
+            | StateWriteIntent::ResultCollection {
+                owner_team_id: Some(_),
+            }
+            | StateWriteIntent::CoordinatorTick { .. }
+            | StateWriteIntent::McpAssignTask {
+                team_key: Some(_),
+                ..
+            }
+    );
+    if use_team_scoped {
+        helper_write_team_scoped_reapply(workspace, state, reapply)
+    } else {
+        helper_write_root_reapply(workspace, state, reapply)
+    }
+}

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

@@ -38,10 +38,12 @@ pub enum EndpointConvergenceDecision {
     Converge {
         old_endpoint: String,
         new_endpoint: String,
+        reason: &'static str,
     },
     RefuseLiveOldEndpoint {
         old_endpoint: String,
         new_endpoint: String,
+        reason: &'static str,
     },
     Unknown,
 }
@@ -96,13 +98,23 @@ pub fn endpoint_convergence_decision(
         return EndpointConvergenceDecision::NoConflict;
     };
 
+    let mut converge_reason = "old_endpoint_dead";
     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(),
-                };
+                match old_endpoint_team_liveness(state, team_key, &old_endpoint) {
+                    OldEndpointTeamLiveness::TeamLive { reason } => {
+                        return EndpointConvergenceDecision::RefuseLiveOldEndpoint {
+                            old_endpoint,
+                            new_endpoint: candidate_endpoint.to_string(),
+                            reason,
+                        };
+                    }
+                    OldEndpointTeamLiveness::TeamAbsent { reason } => {
+                        converge_reason = reason;
+                    }
+                    OldEndpointTeamLiveness::Unknown => return EndpointConvergenceDecision::Unknown,
+                }
             }
             Some(false) => {}
             None => return EndpointConvergenceDecision::Unknown,
@@ -112,9 +124,118 @@ pub fn endpoint_convergence_decision(
     EndpointConvergenceDecision::Converge {
         old_endpoint: first_old,
         new_endpoint: candidate_endpoint.to_string(),
+        reason: converge_reason,
+    }
+}
+
+enum OldEndpointTeamLiveness {
+    TeamLive { reason: &'static str },
+    TeamAbsent { reason: &'static str },
+    Unknown,
+}
+
+fn old_endpoint_team_liveness(
+    state: &Value,
+    team_key: &str,
+    old_endpoint: &str,
+) -> OldEndpointTeamLiveness {
+    let team_state = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+        .unwrap_or(state);
+    let session = non_empty_str(team_state, "session_name")
+        .or_else(|| non_empty_str(state, "session_name"))
+        .unwrap_or_default();
+    if !session.is_empty() {
+        match session_exists_on_endpoint_checked(old_endpoint, session) {
+            Some(true) => {
+                return OldEndpointTeamLiveness::TeamLive {
+                    reason: "old_team_session_live",
+                };
+            }
+            Some(false) => {}
+            None => return OldEndpointTeamLiveness::Unknown,
+        }
+    }
+    match old_endpoint_has_live_team_tuple(state, team_key, old_endpoint) {
+        Some(true) => OldEndpointTeamLiveness::TeamLive {
+            reason: "old_team_tuple_live",
+        },
+        Some(false) => OldEndpointTeamLiveness::TeamAbsent {
+            reason: "old_team_session_absent_on_live_endpoint",
+        },
+        None => OldEndpointTeamLiveness::Unknown,
     }
 }
 
+fn old_endpoint_has_live_team_tuple(
+    state: &Value,
+    team_key: &str,
+    old_endpoint: &str,
+) -> Option<bool> {
+    let backend = crate::tmux_backend::TmuxBackend::for_tmux_endpoint(old_endpoint);
+    let targets = backend.list_targets().ok()?;
+    let team_state = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key));
+    for observed in &targets {
+        if matches!(
+            classify_registered_worker_for_observed_pane(team_state.unwrap_or(state), observed),
+            WorkerPaneBindingMatch::LiveSameWorker { .. }
+        ) || leader_receiver_tuple_matches(team_state.unwrap_or(state), observed)
+        {
+            return Some(true);
+        }
+        if team_state.is_some() {
+            continue;
+        }
+        if let Some(teams) = state.get("teams").and_then(Value::as_object) {
+            if teams.values().any(|entry| {
+                matches!(
+                    classify_registered_worker_for_observed_pane(entry, observed),
+                    WorkerPaneBindingMatch::LiveSameWorker { .. }
+                ) || leader_receiver_tuple_matches(entry, observed)
+            }) {
+                return Some(true);
+            }
+        }
+    }
+    Some(false)
+}
+
+fn leader_receiver_tuple_matches(state: &Value, observed: &PaneInfo) -> bool {
+    let Some(receiver) = state.get("leader_receiver") else {
+        return false;
+    };
+    let Some(cached_pane_id) = non_empty_str(receiver, "pane_id") else {
+        return false;
+    };
+    if cached_pane_id != observed.pane_id.as_str() {
+        return false;
+    }
+    let expected_session = non_empty_str(receiver, "session_name")
+        .or_else(|| non_empty_str(state, "session_name"))
+        .unwrap_or_default();
+    if !expected_session.is_empty() && observed.session.as_str() != expected_session {
+        return false;
+    }
+    if let Some(expected_window) = non_empty_str(receiver, "window_name") {
+        if observed.window_name.as_ref().map(|w| w.as_str()) != Some(expected_window) {
+            return false;
+        }
+    }
+    if let (Some(expected_pid), Some(observed_pid)) =
+        (agent_pane_pid(receiver), observed.pane_pid)
+    {
+        if expected_pid != observed_pid {
+            return false;
+        }
+    }
+    true
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum WorkerPaneBindingMatch {
     LiveSameWorker { agent_id: String },
@@ -329,9 +450,13 @@ fn agent_pane_pid(agent: &Value) -> Option<u32> {
 }
 
 fn session_exists_on_endpoint(endpoint: &str, session: &str) -> bool {
+    session_exists_on_endpoint_checked(endpoint, session).unwrap_or(false)
+}
+
+fn session_exists_on_endpoint_checked(endpoint: &str, session: &str) -> Option<bool> {
     crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
         .has_session(&SessionName::new(session.to_string()))
-        .unwrap_or(false)
+        .ok()
 }
 
 fn collect_stale_endpoint(