@team-agent/installer 0.5.73 → 0.5.75

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

@@ -208,13 +208,24 @@ impl Drop for RuntimeLock {
 /// `save_runtime_state`(bug-084)。`state` 是 state.json 的内存 Value(插入序保留)。
 /// 注:Python 在此还调 `_migrate_state_identity`(identity slice 落地后接入;本 slice 不改 state 内容)。
 pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateError> {
-    save_runtime_state_with_merge_options(workspace, state, &[], None, &[], None, &[], None)
+    save_runtime_state_with_merge_options(
+        workspace,
+        state,
+        &[],
+        None,
+        &[],
+        None,
+        &[],
+        None,
+        None,
+    )
 }
 
 pub(crate) fn save_runtime_state_with_receiver_authority(
     workspace: &Path,
     state: &Value,
     receiver_team_key: &str,
+    exact_owner_seed_to_clear: Option<&Value>,
 ) -> Result<(), StateError> {
     save_runtime_state_with_merge_options(
         workspace,
@@ -225,6 +236,7 @@ pub(crate) fn save_runtime_state_with_receiver_authority(
         None,
         &[],
         Some(receiver_team_key),
+        exact_owner_seed_to_clear,
     )
 }
 
@@ -262,6 +274,7 @@ pub(crate) fn save_runtime_state_with_lifecycle_topology_authority(
         Some(topology_team_key),
         agent_ids,
         None,
+        None,
     )
 }
 
@@ -281,6 +294,7 @@ pub(crate) fn save_runtime_state_with_lifecycle_topology_authority_and_capture_b
         Some(skip_capture_backfill_team_key),
         topology_agent_ids,
         None,
+        None,
     )
 }
 
@@ -298,6 +312,7 @@ pub(crate) fn save_runtime_state_with_deleted_agents(
         None,
         &[],
         None,
+        None,
     )
 }
 
@@ -316,6 +331,7 @@ pub(crate) fn save_runtime_state_with_team_tombstoned_agents(
         None,
         &[],
         None,
+        None,
     )
 }
 
@@ -334,6 +350,7 @@ pub(crate) fn save_runtime_state_with_team_tombstone_lifecycle_topology_authorit
         Some(tombstoned_team_key),
         agent_ids,
         None,
+        None,
     )
 }
 
@@ -346,6 +363,79 @@ fn save_runtime_state_with_merge_options(
     topology_update_team_key: Option<&str>,
     topology_update_agent_ids: &[&str],
     receiver_update_team_key: Option<&str>,
+    exact_owner_seed_to_clear: Option<&Value>,
+) -> Result<(), StateError> {
+    persist_runtime_state_with_merge_options_and_expected(
+        workspace,
+        state,
+        deleted_agent_ids,
+        skip_capture_backfill_team_key,
+        skip_capture_backfill_agent_ids,
+        topology_update_team_key,
+        topology_update_agent_ids,
+        receiver_update_team_key,
+        exact_owner_seed_to_clear,
+        None,
+        None,
+    )
+}
+
+pub(crate) fn save_runtime_state_with_receiver_authority_and_expected(
+    workspace: &Path,
+    state: &Value,
+    receiver_team_key: &str,
+    expected_owner: &Value,
+    expected_receiver: &Value,
+) -> Result<(), StateError> {
+    persist_runtime_state_with_merge_options_and_expected(
+        workspace,
+        state,
+        &[],
+        None,
+        &[],
+        None,
+        &[],
+        Some(receiver_team_key),
+        None,
+        Some((expected_owner, expected_receiver)),
+        None,
+    )
+}
+
+pub(crate) fn save_runtime_state_with_exact_owner_receiver_cleanup(
+    workspace: &Path,
+    state: &Value,
+    team_key: &str,
+    expected_owner: &Value,
+    expected_receiver: &Value,
+) -> Result<(), StateError> {
+    persist_runtime_state_with_merge_options_and_expected(
+        workspace,
+        state,
+        &[],
+        None,
+        &[],
+        None,
+        &[],
+        Some(team_key),
+        None,
+        None,
+        Some((team_key, expected_owner, expected_receiver)),
+    )
+}
+
+fn persist_runtime_state_with_merge_options_and_expected(
+    workspace: &Path,
+    state: &Value,
+    deleted_agent_ids: &[&str],
+    skip_capture_backfill_team_key: Option<&str>,
+    skip_capture_backfill_agent_ids: &[&str],
+    topology_update_team_key: Option<&str>,
+    topology_update_agent_ids: &[&str],
+    receiver_update_team_key: Option<&str>,
+    exact_owner_seed_to_clear: Option<&Value>,
+    expected_owner_receiver: Option<(&Value, &Value)>,
+    exact_owner_receiver_to_clear: Option<(&str, &Value, &Value)>,
 ) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
     // Python `state.py:497`:先对入参 state 跑 `_migrate_state_identity`(就地填缺失 leader uuid)。
@@ -364,14 +454,20 @@ fn save_runtime_state_with_merge_options(
     // entirely. Moving migrate+strip ahead of every cache_equals makes
     // the canonical-only shape the cache invariant for new writes.
     crate::state::ownership::strip_top_level_ownership_if_canonical_present(&mut migrated);
-    if cache_equals(&path, &migrated) {
+    // Exact-seed cleanup must observe lock-held disk, not a pre-lock cache or
+    // byte-equality hit. A matching in-memory document would otherwise no-op
+    // and leave the seed, or skip copying a concurrent owner.
+    let skip_pre_lock_fast_path = exact_owner_seed_to_clear.is_some()
+        || expected_owner_receiver.is_some()
+        || exact_owner_receiver_to_clear.is_some();
+    if !skip_pre_lock_fast_path && cache_equals(&path, &migrated) {
         return Ok(());
     }
     // 与磁盘已有内容「迁移后」相同 → 更新缓存返回(避免无谓重写)。字节对拍 Python:对 `existing` 先
     // `normalize_agent_session_state` + `_migrate_state_identity` 再比(读/迁移失败 try/except: pass →
     // 落写路径)。**修对抗 P1**:此前比较 raw `existing` 漏了这两步,会把「磁盘已是迁移等价形」的 legacy
     // 文件误判为不同而 spurious 重写,破坏 load+save 字节恒等。
-    if path.exists() {
+    if !skip_pre_lock_fast_path && path.exists() {
         if let Ok(text) = std::fs::read_to_string(&path) {
             if let Ok(mut existing) = serde_json::from_str::<Value>(&text) {
                 normalize_agent_session_state(&mut existing);
@@ -396,7 +492,21 @@ fn save_runtime_state_with_merge_options(
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
     }
-    if let Some(latest) = read_latest_state_under_lock(workspace, &path) {
+    let latest = read_latest_state_under_lock(workspace, &path);
+    if let Some((expected_owner, expected_receiver)) = expected_owner_receiver {
+        let expected_matches = latest.as_ref().is_some_and(|latest| {
+            latest_team_owner_receiver(latest, receiver_update_team_key)
+                .is_some_and(|(owner, receiver)| {
+                    owner == expected_owner && receiver == expected_receiver
+                })
+        });
+        if !expected_matches {
+            return Err(StateError::SaveConflict(
+                "fresh caller owner/receiver changed before commit".to_string(),
+            ));
+        }
+    }
+    if let Some(latest) = latest {
         let deleted = deleted_agent_ids
             .iter()
             .copied()
@@ -432,6 +542,8 @@ fn save_runtime_state_with_merge_options(
             &skip_capture_backfill,
             &topology_updates,
             &receiver_updates,
+            receiver_update_team_key.zip(exact_owner_seed_to_clear),
+            exact_owner_receiver_to_clear,
         )?;
     }
     // Stage 3 save-output strip second pass (defence-in-depth): after the
@@ -499,6 +611,8 @@ fn apply_persist_merge_contract(
     skip_capture_backfill_agent_ids: &BTreeSet<String>,
     topology_updates: &BTreeSet<(String, String)>,
     receiver_updates: &BTreeSet<String>,
+    exact_owner_seed_to_clear: Option<(&str, &Value)>,
+    exact_owner_receiver_to_clear: Option<(&str, &Value, &Value)>,
 ) -> Result<(), StateError> {
     // A0/R1: the projection gate only guards the TOP-LEVEL passes (top-level agents and
     // the top-level<->active-team cross projections depend on which team is active); the
@@ -616,6 +730,21 @@ fn apply_persist_merge_contract(
                 latest_entry,
                 receiver_update_authoritative,
             );
+            if let Some((clear_team, seed)) = exact_owner_seed_to_clear {
+                if team == clear_team {
+                    apply_lock_held_exact_owner_cleanup(incoming_entry, latest_entry, seed);
+                }
+            }
+            if let Some((clear_team, seed, expected_receiver)) = exact_owner_receiver_to_clear {
+                if team == clear_team {
+                    apply_lock_held_exact_owner_receiver_cleanup(
+                        incoming_entry,
+                        latest_entry,
+                        seed,
+                        Some(expected_receiver),
+                    );
+                }
+            }
             preserve_latest_endpoint_convergence_fields(incoming_entry, latest_entry);
         }
     }
@@ -746,6 +875,50 @@ fn preserve_latest_ownership_fields(
     }
 }
 
+fn apply_lock_held_exact_owner_cleanup(incoming: &mut Value, latest: &Value, seed: &Value) {
+    apply_lock_held_exact_owner_receiver_cleanup(incoming, latest, seed, None);
+}
+
+fn apply_lock_held_exact_owner_receiver_cleanup(
+    incoming: &mut Value,
+    latest: &Value,
+    seed: &Value,
+    expected_receiver: Option<&Value>,
+) {
+    // Compare the lock-held disk owner and, when supplied, receiver to the
+    // attempt-local grant. A same-owner receiver update is a concurrent
+    // winner and must survive cleanup just like a different owner/epoch.
+    let latest_owner = latest.get("team_owner");
+    let receiver_matches = expected_receiver.is_none_or(|expected| {
+        latest.get("leader_receiver") == Some(expected)
+    });
+    let Some(incoming_obj) = incoming.as_object_mut() else {
+        return;
+    };
+    if latest_owner == Some(seed) && receiver_matches {
+        incoming_obj.insert("team_owner".to_string(), Value::Null);
+        incoming_obj.insert("leader_receiver".to_string(), Value::Null);
+        if let Some(epoch) = latest
+            .get("owner_epoch")
+            .cloned()
+            .or_else(|| latest_owner.and_then(|owner| owner.get("owner_epoch")).cloned())
+        {
+            incoming_obj.insert("owner_epoch".to_string(), epoch);
+        }
+        return;
+    }
+    for key in ["team_owner", "leader_receiver", "owner_epoch"] {
+        match latest.get(key) {
+            Some(value) => {
+                incoming_obj.insert(key.to_string(), value.clone());
+            }
+            None => {
+                incoming_obj.remove(key);
+            }
+        }
+    }
+}
+
 fn preserve_latest_endpoint_convergence_fields(incoming: &mut Value, latest: &Value) {
     if !latest_has_preferable_endpoint_convergence(incoming, latest) {
         return;
@@ -812,6 +985,21 @@ fn latest_has_preferable_ownership(
         && (ownership_attached(latest) || !ownership_attached(incoming))
 }
 
+fn latest_team_owner_receiver<'a>(
+    latest: &'a Value,
+    team_key: Option<&str>,
+) -> Option<(&'a Value, &'a Value)> {
+    let entry = if let Some(team_key) = team_key {
+        latest
+            .get("teams")
+            .and_then(Value::as_object)
+            .and_then(|teams| teams.get(team_key))?
+    } else {
+        latest
+    };
+    Some((entry.get("team_owner")?, entry.get("leader_receiver")?))
+}
+
 fn ownership_epoch(state: &Value) -> u64 {
     state
         .get("owner_epoch")
@@ -2923,6 +3111,8 @@ mod tests {
             &BTreeSet::new(),
             &BTreeSet::new(),
             &BTreeSet::new(),
+            None,
+            None,
         )
         .unwrap();
 
@@ -2957,6 +3147,8 @@ mod tests {
             &BTreeSet::new(),
             &BTreeSet::new(),
             &receiver_updates,
+            None,
+            None,
         )
         .unwrap();
 
@@ -2979,4 +3171,241 @@ mod tests {
             "team-scoped receiver authority must not overwrite a sibling's latest tuple"
         );
     }
+
+    fn seed_owner(epoch: u64) -> Value {
+        json!({
+            "pane_id": "%42",
+            "provider": "pi",
+            "leader_session_uuid": "uuid-seed",
+            "owner_epoch": epoch,
+            "claimed_via": "quick-start"
+        })
+    }
+
+    fn seed_receiver(epoch: u64) -> Value {
+        json!({
+            "mode": "direct_tmux",
+            "status": "attached",
+            "pane_id": "%42",
+            "provider": "pi",
+            "leader_session_uuid": "uuid-seed",
+            "owner_epoch": epoch
+        })
+    }
+
+    fn takeover_owner(epoch: u64) -> Value {
+        json!({
+            "pane_id": "%99",
+            "provider": "codex",
+            "leader_session_uuid": "uuid-other",
+            "owner_epoch": epoch,
+            "claimed_via": "claim-leader"
+        })
+    }
+
+    fn takeover_receiver(epoch: u64) -> Value {
+        json!({
+            "mode": "direct_tmux",
+            "status": "attached",
+            "pane_id": "%99",
+            "provider": "codex",
+            "leader_session_uuid": "uuid-other",
+            "owner_epoch": epoch,
+            "tmux_socket": "/tmp/other"
+        })
+    }
+
+    fn team_state_with_binding(ws: &Path, owner: Value, receiver: Value, epoch: u64) -> Value {
+        json!({
+            "workspace": ws.display().to_string(),
+            "active_team_key": "fresh",
+            "team_key": "fresh",
+            "session_name": "team-fresh",
+            "agents": {"sol": {"status": "running"}},
+            "teams": {
+                "fresh": {
+                    "team_key": "fresh",
+                    "session_name": "team-fresh",
+                    "agents": {"sol": {"status": "running"}},
+                    "team_owner": owner,
+                    "leader_receiver": receiver,
+                    "owner_epoch": epoch
+                }
+            }
+        })
+    }
+
+    fn tombstone_incoming(ws: &Path, epoch: u64) -> Value {
+        let mut incoming = team_state_with_binding(
+            ws,
+            seed_owner(epoch),
+            seed_receiver(epoch),
+            epoch,
+        );
+        incoming["teams"]["fresh"]["team_owner"] = Value::Null;
+        incoming["teams"]["fresh"]["leader_receiver"] = Value::Null;
+        incoming
+    }
+
+    fn assert_fresh_binding(persisted: &Value, owner: &Value, receiver: &Value, epoch: u64) {
+        assert_eq!(&persisted["teams"]["fresh"]["team_owner"], owner);
+        assert_eq!(&persisted["teams"]["fresh"]["leader_receiver"], receiver);
+        assert_eq!(persisted["teams"]["fresh"]["owner_epoch"], json!(epoch));
+    }
+
+    fn persisted_fresh_owner(ws: &Path) -> Value {
+        load_runtime_state(ws).unwrap()["teams"]["fresh"]["team_owner"].clone()
+    }
+
+    #[test]
+    fn exact_seed_cleanup_ignores_pre_lock_cache_and_equality_fast_path() {
+        let ws = temp_ws();
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, seed_owner(1), seed_receiver(1), 1),
+        )
+        .unwrap();
+        let incoming = load_runtime_state(&ws).unwrap();
+        let seed = persisted_fresh_owner(&ws);
+        save_runtime_state_with_receiver_authority(&ws, &incoming, "fresh", Some(&seed)).unwrap();
+        let persisted = load_runtime_state(&ws).unwrap();
+        assert!(
+            persisted
+                .pointer("/teams/fresh/team_owner")
+                .is_some_and(Value::is_null),
+            "cache/equality hit must not skip exact-seed cleanup; got {}",
+            persisted["teams"]["fresh"]["team_owner"]
+        );
+        assert_eq!(persisted["teams"]["fresh"]["owner_epoch"], json!(1));
+    }
+
+    #[test]
+    fn lock_held_exact_seed_cleanup_clears_matching_owner_without_epoch_bump() {
+        let ws = temp_ws();
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, seed_owner(1), seed_receiver(1), 1),
+        )
+        .unwrap();
+        let seed = persisted_fresh_owner(&ws);
+        save_runtime_state_with_receiver_authority(
+            &ws,
+            &tombstone_incoming(&ws, 1),
+            "fresh",
+            Some(&seed),
+        )
+        .unwrap();
+        let persisted = load_runtime_state(&ws).unwrap();
+        assert!(
+            persisted
+                .pointer("/teams/fresh/team_owner")
+                .is_some_and(Value::is_null),
+            "exact seed must be cleared; got {}",
+            persisted["teams"]["fresh"]["team_owner"]
+        );
+        assert!(
+            persisted
+                .pointer("/teams/fresh/leader_receiver")
+                .is_some_and(Value::is_null)
+        );
+        assert_eq!(
+            persisted["teams"]["fresh"]["owner_epoch"],
+            json!(1),
+            "cleanup must not bump epoch past a same-epoch concurrent owner"
+        );
+    }
+
+    #[test]
+    fn lock_held_exact_seed_cleanup_preserves_equal_epoch_concurrent_binding() {
+        let ws = temp_ws();
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, seed_owner(1), seed_receiver(1), 1),
+        )
+        .unwrap();
+        let seed = persisted_fresh_owner(&ws);
+        save_runtime_state_with_receiver_authority(
+            &ws,
+            &team_state_with_binding(&ws, takeover_owner(1), takeover_receiver(1), 1),
+            "fresh",
+            None,
+        )
+        .unwrap();
+        let expected = load_runtime_state(&ws).unwrap();
+        assert_fresh_binding(&expected, &takeover_owner(1), &takeover_receiver(1), 1);
+        save_runtime_state_with_receiver_authority(
+            &ws,
+            &tombstone_incoming(&ws, 1),
+            "fresh",
+            Some(&seed),
+        )
+        .unwrap();
+        assert_fresh_binding(
+            &load_runtime_state(&ws).unwrap(),
+            &expected["teams"]["fresh"]["team_owner"],
+            &expected["teams"]["fresh"]["leader_receiver"],
+            1,
+        );
+    }
+
+    #[test]
+    fn lock_held_exact_seed_receiver_cleanup_preserves_same_owner_receiver_update() {
+        let ws = temp_ws();
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, seed_owner(1), seed_receiver(1), 1),
+        )
+        .unwrap();
+        let seed = persisted_fresh_owner(&ws);
+        let seeded_receiver = load_runtime_state(&ws).unwrap()["teams"]["fresh"]
+            ["leader_receiver"]
+            .clone();
+        let mut winner = team_state_with_binding(&ws, seed_owner(1), takeover_receiver(1), 1);
+        winner["teams"]["fresh"]["team_owner"] = seed.clone();
+        save_runtime_state_with_receiver_authority(&ws, &winner, "fresh", None).unwrap();
+        save_runtime_state_with_exact_owner_receiver_cleanup(
+            &ws,
+            &tombstone_incoming(&ws, 1),
+            "fresh",
+            &seed,
+            &seeded_receiver,
+        )
+        .unwrap();
+        assert_fresh_binding(
+            &load_runtime_state(&ws).unwrap(),
+            &seed,
+            &takeover_receiver(1),
+            1,
+        );
+    }
+
+    #[test]
+    fn lock_held_exact_seed_cleanup_preserves_epoch2_takeover_binding() {
+        let ws = temp_ws();
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, seed_owner(1), seed_receiver(1), 1),
+        )
+        .unwrap();
+        let seed = persisted_fresh_owner(&ws);
+        save_runtime_state(
+            &ws,
+            &team_state_with_binding(&ws, takeover_owner(2), takeover_receiver(2), 2),
+        )
+        .unwrap();
+        let expected = load_runtime_state(&ws).unwrap();
+        save_runtime_state_with_receiver_authority(
+            &ws,
+            &tombstone_incoming(&ws, 1),
+            "fresh",
+            Some(&seed),
+        )
+        .unwrap();
+        assert_fresh_binding(
+            &load_runtime_state(&ws).unwrap(),
+            &expected["teams"]["fresh"]["team_owner"],
+            &expected["teams"]["fresh"]["leader_receiver"],
+            2,
+        );
+    }
 }

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

@@ -48,6 +48,10 @@ use super::persist::{
     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_receiver_authority_and_expected
+        as helper_write_root_with_receiver_authority_and_expected,
+    save_runtime_state_with_exact_owner_receiver_cleanup
+        as helper_write_root_with_exact_owner_receiver_cleanup,
     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,
@@ -206,6 +210,20 @@ pub enum StateWriteIntent<'a> {
     ClaimLeader {
         team_key: &'a str,
     },
+    ClaimLeaderFreshCaller {
+        team_key: &'a str,
+        expected_owner: &'a Value,
+        expected_receiver: &'a Value,
+    },
+    ClearExactTeamOwner {
+        team_key: &'a str,
+        seed: &'a Value,
+    },
+    ClearExactTeamOwnerAndReceiver {
+        team_key: &'a str,
+        seed: &'a Value,
+        expected_receiver: &'a Value,
+    },
     LeaderBindingRestoreNonTargetTeams {
         target_team_key: &'a str,
     },
@@ -383,15 +401,40 @@ fn route_direct(
         // scoped preserve-claim-fields variant at :1702 uses the team-tombstoned
         // agents helper.
         StateWriteIntent::ClaimLeader { team_key } => {
-            helper_write_root_with_receiver_authority(workspace, state, team_key)
+            helper_write_root_with_receiver_authority(workspace, state, team_key, None)
         }
+        StateWriteIntent::ClaimLeaderFreshCaller {
+            team_key,
+            expected_owner,
+            expected_receiver,
+        } => helper_write_root_with_receiver_authority_and_expected(
+            workspace,
+            state,
+            team_key,
+            expected_owner,
+            expected_receiver,
+        ),
+        StateWriteIntent::ClearExactTeamOwner { team_key, seed } => {
+            helper_write_root_with_receiver_authority(workspace, state, team_key, Some(seed))
+        }
+        StateWriteIntent::ClearExactTeamOwnerAndReceiver {
+            team_key,
+            seed,
+            expected_receiver,
+        } => helper_write_root_with_exact_owner_receiver_cleanup(
+            workspace,
+            state,
+            team_key,
+            seed,
+            expected_receiver,
+        ),
         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 { team_key, .. } => {
-            helper_write_root_with_receiver_authority(workspace, state, team_key)
+            helper_write_root_with_receiver_authority(workspace, state, team_key, None)
         }
         // CoordinatorTick dispatches to the existing scoped helper
         // (`save_team_scoped_state`) preserving coordinator/tick.rs:427.