@team-agent/installer 0.5.51 → 0.5.53

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

@@ -22,6 +22,8 @@ use crate::state::persist::{
     save_runtime_state_with_team_tombstoned_agents,
 };
 
+pub(crate) const CURRENT_TEAM_ALIAS: &str = "current";
+
 /// `team_state_key`(`state.py:93`):从 team_dir(.name)/spec_path(.parent.name)派生 team key,
 /// 跳过 `.team`/`runtime`;兜底 `session_name` 或 `"current"`。
 pub fn team_state_key(state: &Value) -> String {
@@ -283,6 +285,14 @@ pub(crate) fn team_is_alive_candidate(team: &Value) -> bool {
     if let Some(status) = status_raw {
         return status.eq_ignore_ascii_case("alive");
     }
+    if !team
+        .get("agents")
+        .and_then(Value::as_object)
+        .is_some_and(|agents| !agents.is_empty())
+        && team_has_live_leader_binding(team)
+    {
+        return false;
+    }
     if all_present_agents_terminal(team) && !team_has_live_leader_binding(team) {
         return false;
     }
@@ -302,6 +312,20 @@ fn team_has_live_leader_binding(team: &Value) -> bool {
     is_non_null_object("leader_receiver") || is_non_null_object("team_owner")
 }
 
+fn team_has_attached_leader_receiver(team: &Value) -> bool {
+    let Some(receiver) = team.get("leader_receiver").and_then(Value::as_object) else {
+        return false;
+    };
+    receiver
+        .get("status")
+        .and_then(Value::as_str)
+        .is_some_and(|status| status.eq_ignore_ascii_case("attached"))
+        && receiver
+            .get("pane_id")
+            .and_then(Value::as_str)
+            .is_some_and(|pane| !pane.is_empty())
+}
+
 fn all_present_agents_terminal(team: &Value) -> bool {
     let Some(agents) = team.get("agents").and_then(Value::as_object) else {
         return false;
@@ -458,15 +482,71 @@ pub fn project_top_level_view(state: &Value, team_key: &str) -> Value {
     Value::Object(p)
 }
 
-/// `select_runtime_state`(`state.py:193`):读 state → 按 `team` 选候选 → 投影顶层视图。
-/// 歧义/未找到 → `Err(StateError::TeamSelect(msg))`(msg == Python `str(RuntimeError)`)。
-pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Value, StateError> {
+#[derive(Debug, Clone)]
+pub struct TeamScopeResolution {
+    pub canonical_team_key: String,
+    pub state: Value,
+}
+
+/// Resolve a requested team selector once, returning both the canonical map key and its
+/// projected state. Callers must carry `canonical_team_key` forward rather than deriving team
+/// identity again from the projection or the original alias.
+pub fn resolve_runtime_team_scope(
+    workspace: &Path,
+    team: Option<&str>,
+) -> Result<TeamScopeResolution, StateError> {
     let state = load_runtime_state(workspace)?;
     let alive = team_state_candidates(&state);
     // Python `if team:` —— 空串 falsy,等同无 team(对抗 P1:此前 Some("") 误入 team 分支,空
     // team_dir 匹配致歧义/未找到错误串漂移)。
     let team = team.filter(|t| !t.is_empty());
     if let Some(team) = team {
+        // Intentional semantic split with `persist::apply_persist_merge_contract`:
+        // selector resolution validates the active team against the alive/terminal
+        // view, while the lock-held merge cannot depend on that mutable view. A
+        // change to either CURRENT_TEAM_ALIAS mapping must evaluate the other.
+        let canonical_request = if team.eq_ignore_ascii_case(CURRENT_TEAM_ALIAS) {
+            let teams = state.get("teams").and_then(Value::as_object);
+            state
+                .get("active_team_key")
+                .and_then(Value::as_str)
+                .filter(|active| {
+                    alive.contains_key(*active)
+                        || teams.is_none_or(Map::is_empty)
+                        || teams
+                            .and_then(|teams| teams.get(*active))
+                            .is_some_and(team_has_attached_leader_receiver)
+                })
+                .map(str::to_string)
+                .or_else(|| {
+                    teams
+                        .is_none_or(Map::is_empty)
+                        .then(|| team_state_key(&state))
+                        .filter(|derived| derived != "current")
+                })
+                .ok_or_else(|| {
+                    StateError::TeamSelect(format!(
+                        "team 'current' not found among alive teams. Use --team <team-key> with an explicit team key to address a terminal team. {}",
+                        format_team_candidates(&alive)
+                    ))
+                })?
+        } else {
+            team.to_string()
+        };
+        let team = canonical_request.as_str();
+        // An exact canonical key is authoritative even when the team is terminal or excluded from
+        // the default alive-candidate set. Explicit lifecycle operations must still be able to
+        // address a shutdown team without falling back to the raw root projection.
+        if state
+            .get("teams")
+            .and_then(Value::as_object)
+            .is_some_and(|teams| teams.contains_key(team))
+        {
+            return Ok(TeamScopeResolution {
+                canonical_team_key: team.to_string(),
+                state: project_top_level_view(&state, team),
+            });
+        }
         // 无 alive 但 team 命中 active_team_key / 派生 key → 直接以全量 state 投影。
         if alive.is_empty() {
             let active = state
@@ -484,32 +564,22 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
                     }
                     None => projection = json!({ "active_team_key": team }),
                 }
-                return Ok(projection);
+                return Ok(TeamScopeResolution {
+                    canonical_team_key: team.to_string(),
+                    state: projection,
+                });
             }
         }
-        if alive.contains_key(team) {
-            return Ok(project_top_level_view(&state, team));
-        }
-        // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1):
-        // 显式 `--team X` 命中 `state.teams` 里的键(即使被标 shutdown/终态)
-        // 仍应投影出来,支持「shutdown 后再 restart --team X」多队场景
-        // (E2E-REST-014 家族)。走 project_top_level_view 保证顶层 agents
-        // 与 teams[key].agents 收敛(E2E-REST-002 依赖 projection clobber
-        // 顶层注入的 session_id)。
-        if state
-            .get("teams")
-            .and_then(Value::as_object)
-            .is_some_and(|teams| teams.contains_key(team))
-        {
-            return Ok(project_top_level_view(&state, team));
-        }
         let matches: Vec<&String> = alive
             .iter()
             .filter(|(key, value)| team_selector_matches(team, key, value))
             .map(|(k, _)| k)
             .collect();
         if matches.len() == 1 {
-            return Ok(project_top_level_view(&state, matches[0]));
+            return Ok(TeamScopeResolution {
+                canonical_team_key: matches[0].clone(),
+                state: project_top_level_view(&state, matches[0]),
+            });
         }
         if matches.len() > 1 {
             return Err(StateError::TeamSelect(
@@ -529,12 +599,18 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
         .filter(|s| !s.is_empty());
     if let Some(active) = active {
         if alive.contains_key(active) {
-            return Ok(project_top_level_view(&state, active));
+            return Ok(TeamScopeResolution {
+                canonical_team_key: active.to_string(),
+                state: project_top_level_view(&state, active),
+            });
         }
     }
     if alive.len() == 1 {
         let only = alive.keys().next().cloned().unwrap_or_default();
-        return Ok(project_top_level_view(&state, &only));
+        return Ok(TeamScopeResolution {
+            canonical_team_key: only.clone(),
+            state: project_top_level_view(&state, &only),
+        });
     }
     if alive.is_empty() {
         // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1):
@@ -547,10 +623,22 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
                 .and_then(Value::as_object)
                 .is_some_and(|teams| teams.contains_key(active_key))
             {
-                return Ok(project_top_level_view(&state, active_key));
+                return Ok(TeamScopeResolution {
+                    canonical_team_key: active_key.to_string(),
+                    state: project_top_level_view(&state, active_key),
+                });
             }
         }
-        return Ok(state);
+        let canonical_team_key = state
+            .get("active_team_key")
+            .and_then(Value::as_str)
+            .filter(|key| !key.is_empty())
+            .map(str::to_string)
+            .unwrap_or_else(|| team_state_key(&state));
+        return Ok(TeamScopeResolution {
+            canonical_team_key,
+            state,
+        });
     }
     Err(StateError::TeamSelect(
         "multiple teams found in this workspace; pass --team <team> to choose. ".to_string()
@@ -558,6 +646,11 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
     ))
 }
 
+/// `select_runtime_state`(`state.py:193`):compatibility projection wrapper.
+pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Value, StateError> {
+    resolve_runtime_team_scope(workspace, team).map(|resolved| resolved.state)
+}
+
 fn team_selector_matches(team: &str, key: &str, value: &Value) -> bool {
     if team == key {
         return true;
@@ -678,22 +771,41 @@ pub(crate) fn save_team_scoped_state_with_deleted_agents(
 pub(crate) fn save_team_scoped_state_with_tombstone_lifecycle_topology_authority(
     workspace: &Path,
     team_state: &Value,
+    topology_team_key: &str,
     agent_ids: &[&str],
 ) -> Result<(), StateError> {
-    save_team_scoped_state_with_merge_options(workspace, team_state, &[], agent_ids, &[], agent_ids)
+    save_team_scoped_state_with_merge_options(
+        workspace,
+        team_state,
+        &[],
+        agent_ids,
+        &[],
+        Some(topology_team_key),
+        agent_ids,
+    )
 }
 
 pub(crate) fn save_team_scoped_state_with_lifecycle_topology_authority(
     workspace: &Path,
     team_state: &Value,
+    topology_team_key: &str,
     agent_ids: &[&str],
 ) -> Result<(), StateError> {
-    save_team_scoped_state_with_merge_options(workspace, team_state, &[], &[], &[], agent_ids)
+    save_team_scoped_state_with_merge_options(
+        workspace,
+        team_state,
+        &[],
+        &[],
+        &[],
+        Some(topology_team_key),
+        agent_ids,
+    )
 }
 
 pub(crate) fn save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip(
     workspace: &Path,
     team_state: &Value,
+    topology_team_key: &str,
     skip_capture_backfill_agent_ids: &[&str],
     topology_agent_ids: &[&str],
 ) -> Result<(), StateError> {
@@ -703,6 +815,7 @@ pub(crate) fn save_team_scoped_state_with_lifecycle_topology_authority_and_captu
         &[],
         &[],
         skip_capture_backfill_agent_ids,
+        Some(topology_team_key),
         topology_agent_ids,
     )
 }
@@ -719,6 +832,7 @@ fn save_team_scoped_state_with_merge_exceptions(
         deleted_agent_ids,
         tombstoned_agent_ids,
         &[],
+        None,
         &[],
     )
 }
@@ -729,6 +843,7 @@ fn save_team_scoped_state_with_merge_options(
     deleted_agent_ids: &[&str],
     tombstoned_agent_ids: &[&str],
     skip_capture_backfill_agent_ids: &[&str],
+    topology_team_key: Option<&str>,
     topology_agent_ids: &[&str],
 ) -> Result<(), StateError> {
     let target_key = team_state_key(team_state);
@@ -768,7 +883,7 @@ fn save_team_scoped_state_with_merge_options(
                 return save_runtime_state_with_team_tombstone_lifecycle_topology_authority(
                     workspace,
                     &merged,
-                    &target_key,
+                    topology_team_key.unwrap_or(&target_key),
                     topology_agent_ids,
                 );
             }
@@ -776,7 +891,7 @@ fn save_team_scoped_state_with_merge_options(
                 return save_runtime_state_with_lifecycle_topology_authority_and_capture_backfill_skip(
                     workspace,
                     &merged,
-                    &target_key,
+                    topology_team_key.unwrap_or(&target_key),
                     skip_capture_backfill_agent_ids,
                     topology_agent_ids,
                 );
@@ -784,6 +899,7 @@ fn save_team_scoped_state_with_merge_options(
             return save_runtime_state_with_lifecycle_topology_authority(
                 workspace,
                 &merged,
+                topology_team_key.unwrap_or(&target_key),
                 topology_agent_ids,
             );
         }
@@ -834,7 +950,7 @@ fn save_team_scoped_state_with_merge_options(
                 save_runtime_state_with_lifecycle_topology_authority_and_capture_backfill_skip(
                     workspace,
                     &Value::Object(merged),
-                    &target_key,
+                    topology_team_key.unwrap_or(&target_key),
                     skip_capture_backfill_agent_ids,
                     topology_agent_ids,
                 )
@@ -842,6 +958,7 @@ fn save_team_scoped_state_with_merge_options(
                 save_runtime_state_with_lifecycle_topology_authority(
                     workspace,
                     &Value::Object(merged),
+                    topology_team_key.unwrap_or(&target_key),
                     topology_agent_ids,
                 )
             }
@@ -1113,6 +1230,104 @@ mod tests {
         );
     }
 
+    #[test]
+    fn resolve_runtime_team_scope_current_uses_valid_active_key() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "alpha",
+            "teams": {
+                "alpha": {"status": "alive", "session_name": "team-alpha", "agents": {"worker": {}}},
+                "old-team": {"team_owner": {"pane_id": "%9"}}
+            }
+        }));
+        let resolved = resolve_runtime_team_scope(&ws, Some("current")).unwrap();
+        assert_eq!(resolved.canonical_team_key, "alpha");
+        assert_eq!(
+            resolved.state.get("active_team_key").and_then(Value::as_str),
+            Some("alpha")
+        );
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_accepts_attached_receiver_recovery() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "alpha",
+            "teams": {
+                "alpha": {
+                    "agents": {},
+                    "leader_receiver": {"status": "attached", "pane_id": "%9"}
+                }
+            }
+        }));
+        let resolved = resolve_runtime_team_scope(&ws, Some("current")).unwrap();
+        assert_eq!(resolved.canonical_team_key, "alpha");
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_accepts_shutdown_receiver_recovery() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "alpha",
+            "teams": {
+                "alpha": {
+                    "status": "shutdown",
+                    "agents": {"worker": {"status": "stopped"}},
+                    "leader_receiver": {"status": "attached", "pane_id": "%9"}
+                }
+            }
+        }));
+        let resolved = resolve_runtime_team_scope(&ws, Some("current")).unwrap();
+        assert_eq!(resolved.canonical_team_key, "alpha");
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_rejects_owner_only_stub() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "old-team",
+            "teams": {
+                "old-team": {"agents": {}, "team_owner": {"pane_id": "%9"}}
+            }
+        }));
+        let error = resolve_runtime_team_scope(&ws, Some("current")).unwrap_err();
+        assert!(error.to_string().contains("team 'current' not found"));
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_fails_without_valid_active_key() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "missing",
+            "teams": {
+                "alpha": {"status": "alive", "session_name": "team-alpha", "agents": {"worker": {}}}
+            }
+        }));
+        let error = resolve_runtime_team_scope(&ws, Some("current")).unwrap_err();
+        assert!(error.to_string().contains("team 'current' not found"));
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_keeps_legacy_single_team_state() {
+        let ws = temp_ws_with_state(&json!({
+            "active_team_key": "legacy",
+            "team_key": "legacy",
+            "session_name": "team-legacy",
+            "agents": {"worker": {"status": "running"}}
+        }));
+        let resolved = resolve_runtime_team_scope(&ws, Some("current")).unwrap();
+        assert_eq!(resolved.canonical_team_key, "legacy");
+        assert_eq!(resolved.state["active_team_key"], json!("legacy"));
+    }
+
+    #[test]
+    fn resolve_runtime_team_scope_current_rejects_empty_workspace_bootstrap() {
+        let ws = temp_ws_with_state(&json!({}));
+        let error = resolve_runtime_team_scope(&ws, Some("current")).unwrap_err();
+        assert!(error.to_string().contains("team 'current' not found"));
+        let saved = load_runtime_state(&ws).unwrap();
+        assert_ne!(
+            saved.get("active_team_key").and_then(Value::as_str),
+            Some("current")
+        );
+        assert!(!crate::model::paths::runtime_spec_path(&ws, "current").exists());
+    }
+
     // 对抗 P1:空串 team 必须走「无 team」分支(Python `if team:` falsy),报「multiple teams」
     // 而非「team selector is ambiguous」(后者是非空 team 多匹配)。
     #[test]

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

@@ -0,0 +1,13 @@
+use super::StateWriteIntent;
+
+impl<'a> StateWriteIntent<'a> {
+    pub(crate) fn launch_team_or_add_agent(
+        team_key: &'a str,
+        added_agent_id: Option<&'a str>,
+    ) -> Self {
+        match added_agent_id {
+            Some(agent_id) => Self::AddAgent { team_key, agent_id },
+            None => Self::LaunchTeam { team_key },
+        }
+    }
+}

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

@@ -46,6 +46,7 @@ use super::persist::{
     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_receiver_authority as helper_write_root_with_receiver_authority,
     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,
     save_runtime_state_without_migrations as helper_write_root_without_migrations,
@@ -60,6 +61,8 @@ use super::projection::{
     save_team_scoped_state_with_tombstone_lifecycle_topology_authority as helper_write_team_scoped_with_tombstone_lifecycle_topology_authority,
 };
 
+mod intent;
+
 /// Repository facade for workspace state reads and writes.
 ///
 /// S1a scope: hold the workspace path, expose `load_workspace`/`load_team`
@@ -141,6 +144,10 @@ pub enum StateWriteIntent<'a> {
     LaunchTeam {
         team_key: &'a str,
     },
+    AddAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
     AnnotateTeamDepth {
         team_key: &'a str,
     },
@@ -245,9 +252,8 @@ pub enum StateWriteIntent<'a> {
     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;
+// S1a dispatch: every intent forwards to the same pre-S1a helper family; only naming 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,
@@ -258,6 +264,14 @@ fn route_direct(
         // 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),
+        StateWriteIntent::AddAgent { team_key, agent_id } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(
+                workspace,
+                state,
+                team_key,
+                &[agent_id],
+            )
+        }
         // AnnotateTeamDepth also lives on the root save path.
         StateWriteIntent::AnnotateTeamDepth { .. } => helper_write_root(workspace, state),
         // ShutdownTeam: scoped clean shutdown uses `save_team_scoped_state`;
@@ -277,12 +291,13 @@ fn route_direct(
         // `save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip`
         // at lifecycle/restart/common.rs:633.
         StateWriteIntent::RestartTeam {
+            team_key,
             topology_authority_agent_ids,
             skip_capture_backfill_agent_ids,
-            ..
         } => helper_write_team_scoped_with_lifecycle_topology_authority_and_capture_backfill_skip(
             workspace,
             state,
+            team_key,
             skip_capture_backfill_agent_ids,
             topology_authority_agent_ids,
         ),
@@ -292,16 +307,17 @@ fn route_direct(
         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, &[])
+        StateWriteIntent::StartAgent { team_key, .. } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(workspace, state, team_key, &[])
         }
         // StopAgent uses the legacy helper family
         // `save_team_scoped_state_with_lifecycle_topology_authority`,
         // matching lifecycle/restart/agent.rs:911.
-        StateWriteIntent::StopAgent { agent_id, .. } => {
+        StateWriteIntent::StopAgent { team_key, agent_id } => {
             helper_write_team_scoped_with_lifecycle_topology_authority(
                 workspace,
                 state,
+                team_key,
                 &[agent_id],
             )
         }
@@ -310,20 +326,22 @@ fn route_direct(
         // matching lifecycle/restart/agent.rs:1355. Non-discard falls back to
         // the same lifecycle topology-authority helper as StopAgent.
         StateWriteIntent::ResetAgent {
+            team_key,
             agent_id,
             discard_session,
-            ..
         } => {
             if discard_session {
                 helper_write_team_scoped_with_tombstone_lifecycle_topology_authority(
                     workspace,
                     state,
+                    team_key,
                     &[agent_id],
                 )
             } else {
                 helper_write_team_scoped_with_lifecycle_topology_authority(
                     workspace,
                     state,
+                    team_key,
                     &[agent_id],
                 )
             }
@@ -335,10 +353,11 @@ fn route_direct(
         }
         // ForkAgent mutates a selected team projection, so persist it back to
         // that projection with the forked row as lifecycle topology authority.
-        StateWriteIntent::ForkAgent { agent_id, .. } => {
+        StateWriteIntent::ForkAgent { team_key, agent_id } => {
             helper_write_team_scoped_with_lifecycle_topology_authority(
                 workspace,
                 state,
+                team_key,
                 &[agent_id],
             )
         }
@@ -352,23 +371,28 @@ fn route_direct(
         // Force-recreate rollback restores an existing row after the
         // replacement spawn has advanced its lifecycle tuple. The selected
         // row is therefore the explicit topology authority.
-        StateWriteIntent::ForceRecreateRollback { agent_id, .. } => {
+        StateWriteIntent::ForceRecreateRollback { team_key, agent_id } => {
             helper_write_team_scoped_with_lifecycle_topology_authority(
                 workspace,
                 state,
+                team_key,
                 &[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),
+        StateWriteIntent::ClaimLeader { team_key } => {
+            helper_write_root_with_receiver_authority(workspace, state, team_key)
+        }
         StateWriteIntent::LeaderBindingRestoreNonTargetTeams { .. } => {
             helper_write_root_without_migrations(workspace, state)
         }
         // LeaderStartBinding -> managed/exec/external all root-save at
         // leader/start.rs:795/903/946.
-        StateWriteIntent::LeaderStartBinding { .. } => helper_write_root(workspace, state),
+        StateWriteIntent::LeaderStartBinding { team_key, .. } => {
+            helper_write_root_with_receiver_authority(workspace, state, team_key)
+        }
         // CoordinatorTick dispatches to the existing scoped helper
         // (`save_team_scoped_state`) preserving coordinator/tick.rs:427.
         StateWriteIntent::CoordinatorTick { .. } => helper_write_team_scoped(workspace, state),

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

@@ -5,8 +5,8 @@ use std::path::{Path, PathBuf};
 use serde_json::Value;
 
 use crate::model::paths::{canonical_run_workspace, runtime_spec_path, team_workspace};
-use crate::state::persist::{load_runtime_state, runtime_state_path};
-use crate::state::projection::{select_runtime_state, team_state_key};
+use crate::state::persist::runtime_state_path;
+use crate::state::projection::resolve_runtime_team_scope;
 use crate::state::StateError;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -36,15 +36,15 @@ pub fn resolve_active_team(
     mode: SelectorMode,
 ) -> Result<SelectedTeam, StateError> {
     let explicit_spec = input.join("team.spec.yaml");
-    let (run_workspace, state) = if explicit_spec.exists() {
+    let (run_workspace, resolved) = if explicit_spec.exists() {
         let team_run = team_workspace(input).map_err(|e| StateError::TeamSelect(e.to_string()))?;
         let run = if runtime_state_path(input).exists() || !runtime_state_path(&team_run).exists() {
             input.to_path_buf()
         } else {
             team_run
         };
-        let state = select_runtime_state(&run, team).or_else(|_| load_runtime_state(&run))?;
-        (run, state)
+        let resolved = resolve_runtime_team_scope(&run, team)?;
+        (run, resolved)
     } else {
         let run =
             canonical_run_workspace(input).map_err(|e| StateError::TeamSelect(e.to_string()))?;
@@ -58,15 +58,16 @@ pub fn resolve_active_team(
                 input.display()
             )));
         }
-        let state = select_runtime_state(&run, team).or_else(|_| load_runtime_state(&run))?;
-        (run, state)
+        let resolved = resolve_runtime_team_scope(&run, team)?;
+        (run, resolved)
     };
+    let state = resolved.state;
 
     // E5 spec 迁移·读序 B(architect+leader 裁定):
     //   1) runtime spec 优先严格:<run_ws>/.team/runtime/<team_key>/team.spec.yaml 存在即必用。
     //   2) 缺失才**只读回落**用户目录旧 spec(过渡腿;绝不在此写/迁移——迁移+清理只属启动重建)。
     // TODO(E5 后续版本):新 team 永不写用户目录(G1),回落腿可在 legacy 清零后移除。
-    let team_key = selected_team_key(&state, team);
+    let team_key = resolved.canonical_team_key;
     let runtime_spec = runtime_spec_path(&run_workspace, &team_key);
     let (spec_workspace, spec_path) = if runtime_spec.exists() {
         (
@@ -136,13 +137,3 @@ fn spec_workspace_from_state(state: &Value) -> Option<PathBuf> {
                 .map(PathBuf::from)
         })
 }
-
-fn selected_team_key(state: &Value, team: Option<&str>) -> String {
-    state
-        .get("active_team_key")
-        .and_then(Value::as_str)
-        .filter(|s| !s.is_empty())
-        .map(ToString::to_string)
-        .or_else(|| team.filter(|s| !s.is_empty()).map(ToString::to_string))
-        .unwrap_or_else(|| team_state_key(state))
-}