@team-agent/installer 0.5.115 → 0.5.116

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

@@ -45,7 +45,7 @@ mod contract_route_tests {
     fn mixed_team_retains_legacy_classification_without_native_codex_fallback() {
         let state = serde_json::json!({"agents": {
             "native": {"provider":"cursor","status":"running","session_id":"native-id"},
-            "legacy": {"provider":"pi","status":"stopped"},
+            "legacy": {"provider":"pi","status":"running"},
         }});
         let plan = classify_restart_plan(&state, false).unwrap();
         assert_eq!(plan.decisions.len(), 1);
@@ -54,6 +54,31 @@ mod contract_route_tests {
     }
 }
 
+#[cfg(test)]
+mod stopped_restart_tests {
+    use super::*;
+
+    #[test]
+    fn stopped_rows_never_enter_validation_or_fresh_spawn_even_with_allow_fresh() {
+        let state = serde_json::json!({"agents": {
+            "stopped": {"provider":"pi","status":"stopped","explicit_stop":true,
+                "session_id":"preserved","generation":7,"first_send_at":false},
+            "legacy_stopped": {"provider":"pi","status":"stopped"},
+            "marker": {"provider":"pi","status":"running","explicit_stop":true},
+            "active": {"provider":"pi","status":"running"}
+        }});
+        let before = state.clone();
+        for allow_fresh in [false, true] {
+            let plan = classify_restart_plan(&state, allow_fresh).unwrap();
+            assert_eq!(plan.decisions.len(), 1);
+            assert_eq!(plan.decisions[0].agent_id.as_str(), "active");
+            assert!(plan.corrupt_entries.is_empty());
+            assert!(plan.unresumable.is_empty());
+            assert_eq!(state, before);
+        }
+    }
+}
+
 /// ---
 /// purpose: 定出该席位这次的启动模式
 /// params:
@@ -266,13 +291,13 @@ pub(crate) fn python_type_name(value: &serde_json::Value) -> &'static str {
 /// purpose: 纯计算出整队的 restart 计划
 /// params:
 ///   allow_fresh: 允许无会话席位改跑全新会话
-/// returns: 每个非 paused 席位的 resume 决策、损坏的 first_send_at 条目与不可 resume 名单
+/// returns: 每个非 paused/非 stopped 席位的 resume 决策、损坏的 first_send_at 条目与不可 resume 名单
 /// errors: 计算过程中的错误以 LifecycleError 返回
 /// contract_id: lifecycle.selection.classify_restart_plan
 /// ---
 /// Route B 全量验证(纯计算,**无破坏性副作用**;`_emit_resume_decisions` +
 /// `_collect_corrupt_first_send_at`,`orchestration.py:430/467`)。读 fixture state 的
-/// `agents.<id>`,对每非 paused worker:
+/// `agents.<id>`,对每非 paused/非 stopped worker（explicit_stop 也跳过）:
 /// (1) corrupt first_send_at → 收进 `corrupt_entries`(carry python type-name);
 /// (2) 算 resume 决策(`session_id→Resume` / `null session && allow_fresh→FreshStart` /
 ///     否则 `Refuse`;E6 层2:null session 不再因 first_send_at=null 静默 fresh);
@@ -317,11 +342,8 @@ pub(crate) fn classify_restart_plan_with_resume_validation(
         // not this legacy enum's unknown-provider Codex default.
         #[cfg(unix)]
         if crate::contract_runtime::framework::is_contract(agent) { continue; }
-        if agent
-            .get("status")
-            .and_then(|v| v.as_str())
-            .map(|s| s == "paused")
-            .unwrap_or(false)
+        if crate::state::projection::agent_stopped_for_restart(agent)
+            || agent.get("status").and_then(|v| v.as_str()) == Some("paused")
         {
             continue;
         }

package/crates/team-agent/src/provider/session/capture.rs

@@ -868,7 +868,8 @@ fn incomplete_resumable_provider<F>(agent: &Value, adapter_for: &mut F) -> Optio
 where
     F: FnMut(Provider) -> Box<dyn ProviderAdapter>,
 {
-    if agent
+    if crate::state::projection::agent_explicit_stop(agent)
+        || agent
         .get("status")
         .and_then(Value::as_str)
         .is_some_and(|status| status != "running")
@@ -892,6 +893,28 @@ where
     Some(provider)
 }
 
+#[cfg(test)]
+mod stopped_capture_tests {
+    use super::*;
+
+    #[test]
+    fn explicit_stop_is_checked_before_adapter_or_backing_probes() {
+        for row in [
+            serde_json::json!({"status":"stopped","provider":"pi","spawn_cwd":"/controlled"}),
+            serde_json::json!({"status":"running","explicit_stop":true,"provider":"pi","spawn_cwd":"/controlled"}),
+            serde_json::json!({"status":"running","explicit_stop":"false","provider":"pi","spawn_cwd":"/controlled"}),
+        ] {
+            assert!(incomplete_resumable_provider(&row, &mut |_| panic!("held seat reached adapter lookup")).is_none());
+        }
+        let mut calls = 0;
+        let _ = incomplete_resumable_provider(
+            &serde_json::json!({"status":"running","explicit_stop":false,"provider":"pi","spawn_cwd":"/controlled"}),
+            &mut |provider| { calls += 1; crate::provider::get_adapter(provider) },
+        );
+        assert_eq!(calls, 1, "active control must still be eligible for capture");
+    }
+}
+
 fn agent_session_complete(agent: &Value) -> bool {
     // RM-039-SESS-001 step 1 (architect verdict 2026-06-22): historically
     // this returned true the moment `rollout_path` was non-empty — even when

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

@@ -48,7 +48,7 @@ const SESSION_STATE_FIELDS: [&str; 6] = [
 ];
 const LIVE_TOPOLOGY_FIELDS: [&str; 5] =
     ["pane_id", "pane_pid", "window", "spawned_at", "spawn_epoch"];
-const ROSTER_STUB_ALLOWLIST: [&str; 16] = [
+const ROSTER_STUB_ALLOWLIST: [&str; 17] = [
     "agent_id",
     "provider",
     "auth_mode",
@@ -65,6 +65,7 @@ const ROSTER_STUB_ALLOWLIST: [&str; 16] = [
     "claude_config_dir",
     "claude_projects_root",
     "profile_launch",
+    "explicit_stop",
 ];
 
 /// `state.py:_RUNTIME_STATE_CACHE`:进程级 path→state 缓存(deep-equal 早返回)。
@@ -626,6 +627,16 @@ fn persist_runtime_state_with_merge_options_and_expected(
 pub(super) fn update_runtime_state(
     workspace: &Path,
     update: impl FnOnce(&Value) -> Result<Value, StateError>,
+) -> Result<Value, StateError> {
+    update_runtime_state_with_lifecycle_target(workspace, None, update)
+}
+
+/// Keep bounded StartAgent's exact team/seat authority inside the same state-save
+/// transaction. Ordinary deltas retain every existing stale-writer guard.
+pub(super) fn update_runtime_state_with_lifecycle_target(
+    workspace: &Path,
+    target: Option<(&str, &str)>,
+    update: impl FnOnce(&Value) -> Result<Value, StateError>,
 ) -> Result<Value, StateError> {
     let path = runtime_state_path(workspace);
     let _lock = RuntimeLock::acquire(workspace, "state-save", 2.0)?;
@@ -639,7 +650,12 @@ pub(super) fn update_runtime_state(
     migrate_state_identity(&mut latest, &SystemEnv, workspace)?;
     let _ = migrate_active_team_key(&mut latest);
     let mut committed = update(&latest)?;
-    merge_ordinary_state(&mut committed, &latest)?;
+    let topology_updates = target.into_iter()
+        .map(|(team, agent)| (team.to_owned(), agent.to_owned())).collect();
+    apply_persist_merge_contract(
+        &mut committed, &latest, &BTreeSet::new(), None, &BTreeSet::new(),
+        &topology_updates, &BTreeSet::new(), None, None, None,
+    )?;
     migrate_state_identity(&mut committed, &SystemEnv, workspace)?;
     crate::state::ownership::strip_top_level_ownership_if_canonical_present(&mut committed);
     if committed == latest {
@@ -1264,6 +1280,13 @@ fn merge_agent_projection(
                 .is_some_and(|source| !source.is_empty());
         match incoming_map.entry(agent_id.clone()) {
             serde_json::map::Entry::Vacant(slot) => {
+                // Omission by an ordinary/stale writer cannot retire a stopped
+                // seat or discard its resume metadata. Explicit RemoveAgent
+                // has already been admitted through deleted_agent_ids above.
+                if crate::state::projection::agent_explicit_stop(latest_agent) {
+                    slot.insert(latest_agent.clone());
+                    continue;
+                }
                 if fork_target {
                     slot.insert(latest_agent.clone());
                     continue;
@@ -1295,6 +1318,17 @@ fn merge_agent_projection(
                 }
             }
             serde_json::map::Entry::Occupied(mut existing) => {
+                if !topology_update_agent_ids.contains(agent_id) {
+                    if crate::state::projection::agent_explicit_stop(latest_agent) {
+                        *existing.get_mut() = latest_agent.clone();
+                        continue;
+                    }
+                    if let Some(marker) = latest_agent.get("explicit_stop") {
+                        if let Some(row) = existing.get_mut().as_object_mut() {
+                            row.insert("explicit_stop".into(), marker.clone());
+                        }
+                    }
+                }
                 if !tombstoned_for_projection && !topology_update_agent_ids.contains(agent_id) {
                     let fields = topology_conflict_fields(existing.get(), latest_agent, team_alive);
                     if !fields.is_empty() {
@@ -2453,6 +2487,42 @@ mod tests {
         );
     }
 
+    #[test]
+    fn stopped_intent_and_resume_metadata_survive_stale_writers_until_targeted_start() {
+        let ws = temp_ws();
+        let held = json!({"agent_id":"held","provider":"codex","status":"stopped","explicit_stop":true,
+            "session_id":"same-session","rollout_path":"/controlled/rollout","captured_at":"2026-10-12T00:00:00Z",
+            "captured_via":"native","generation":7});
+        let mut latest = json!({"session_name":"team-a","active_team_key":"team-a","agents":{"held":held},
+            "teams":{"team-a":{"session_name":"team-a","agents":{"held":held}}}});
+        normalize_agent_session_state(&mut latest);
+        for omit in [false, true] {
+            write_state(&ws, &latest);
+            let before = read_state(&ws);
+            let held_root = before.pointer("/agents/held").unwrap().clone();
+            let held_team = before.pointer("/teams/team-a/agents/held").unwrap().clone();
+            let rows = if omit { json!({}) } else { json!({"held":{"agent_id":"held","provider":"codex","status":"running","explicit_stop":false,"session_id":"stale"}}) };
+            let stale = json!({"session_name":"team-a","active_team_key":"team-a","agents":rows,
+                "teams":{"team-a":{"session_name":"team-a","agents":rows}},"delivery":{"message":"observed"}});
+            save_runtime_state(&ws, &stale).unwrap();
+            let saved = read_state(&ws);
+            assert_eq!(saved.pointer("/agents/held"), Some(&held_root));
+            assert_eq!(saved.pointer("/teams/team-a/agents/held"), Some(&held_team));
+            assert_eq!(saved.pointer("/delivery/message"), Some(&json!("observed")));
+        }
+        let mut started = latest;
+        for pointer in ["/agents/held", "/teams/team-a/agents/held"] {
+            let row = started.pointer_mut(pointer).unwrap();
+            row["status"] = json!("running");
+            row["explicit_stop"] = json!(false);
+        }
+        save_runtime_state_with_lifecycle_topology_authority(&ws, &started, "team-a", &["held"]).unwrap();
+        let saved = read_state(&ws);
+        assert_eq!(saved.pointer("/agents/held/explicit_stop"), Some(&json!(false)));
+        assert_eq!(saved.pointer("/agents/held/session_id"), Some(&json!("same-session")));
+        assert_eq!(saved.pointer("/teams/team-a/agents/held/explicit_stop"), Some(&json!(false)));
+    }
+
     #[test]
     fn lifecycle_topology_authority_only_applies_to_target_agent() {
         let ws = temp_ws();

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

@@ -363,6 +363,20 @@ fn all_present_agents_terminal(team: &Value) -> bool {
     })
 }
 
+/// Team restart never consumes an explicit stop or legacy stopped row.
+/// A malformed persisted marker is held closed, not coerced to false.
+pub(crate) fn agent_stopped_for_restart(agent: &Value) -> bool {
+    agent.get("status").and_then(Value::as_str)
+        .is_some_and(|status| status.eq_ignore_ascii_case("stopped"))
+        || agent_explicit_stop(agent)
+}
+
+/// Only an explicit persisted stop freezes metadata against ordinary writers.
+/// Historical stopped rows still follow existing roster-pruning semantics.
+pub(crate) fn agent_explicit_stop(agent: &Value) -> bool {
+    !matches!(agent.get("explicit_stop"), None | Some(Value::Bool(false)))
+}
+
 pub(crate) fn agent_status_is_terminal(status: &str) -> bool {
     matches!(
         status.to_ascii_lowercase().as_str(),
@@ -1149,6 +1163,21 @@ mod tests {
         ws
     }
 
+    #[test]
+    fn restart_stop_marker_is_conservative_without_blocking_crash_states() {
+        for row in [
+            json!({"status":"stopped"}),
+            json!({"status":"stopped","explicit_stop":false}),
+            json!({"status":"running","explicit_stop":true}),
+            json!({"status":"running","explicit_stop":"false"}),
+        ] {
+            assert!(agent_stopped_for_restart(&row));
+        }
+        for status in ["running", "dead", "restart_failed"] {
+            assert!(!agent_stopped_for_restart(&json!({"status":status,"explicit_stop":false})));
+        }
+    }
+
     #[test]
     fn team_state_key_cases() {
         assert_eq!(

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

@@ -112,3 +112,73 @@ fn coordinator_observations_keep_legacy_identity_and_shape()
     std::fs::remove_dir_all(workspace)?;
     Ok(())
 }
+
+#[test]
+fn stopped_start_commit_updates_exact_target_and_both_mirrors()
+    -> Result<(), Box<dyn std::error::Error>> {
+    use serde_json::json;
+    for target in ["team-a", "team-b"] {
+        let nonce = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?.as_nanos();
+        let workspace = std::env::temp_dir().join(format!("state-start-stopped-{target}-{nonce}"));
+        let held = json!({"agent_id":"worker","provider":"grok_build","runtime_family":"contract",
+            "status":"stopped","explicit_stop":true,"generation":1,"contract_instance":"instance-one",
+            "session_id":"same-session","native_endpoint":"old-endpoint"});
+        let peer = json!({"agent_id":"peer","provider":"pi","status":"stopped","explicit_stop":true,
+            "session_id":"peer-session","generation":1});
+        let control = json!({"agent_id":"control","provider":"pi","status":"running","session_id":"control-session"});
+        let agents = json!({"worker":held,"peer":peer,"control":control});
+        let initial = json!({"session_name":"team-a","active_team_key":"team-a","agents":agents,
+            "teams":{"team-a":{"session_name":"team-a","status":"alive","agents":agents},
+                     "team-b":{"session_name":"team-b","status":"alive","agents":agents}}});
+        let path = super::helper_workspace_path(&workspace);
+        std::fs::create_dir_all(path.parent().unwrap())?;
+        std::fs::write(&path, serde_json::to_vec(&initial)?)?;
+        let repository = super::StateRepository::new(&workspace);
+        let before = repository.load_workspace()?;
+        let other = if target == "team-a" { "team-b" } else { "team-a" };
+        let committed = repository.commit(StateWriteIntent::StartAgent { team_key: target, agent_id: "worker" }, |selected| {
+            let row = &mut selected["agents"]["worker"];
+            row["status"] = json!("running");
+            row["explicit_stop"] = json!(false);
+            row["generation"] = json!(2);
+            row["contract_instance"] = json!("instance-two");
+            row["native_endpoint"] = json!("new-endpoint");
+            // Start authority must not leak to an unrelated stopped peer.
+            selected["agents"]["peer"]["status"] = json!("running");
+            selected["agents"]["peer"]["explicit_stop"] = json!(false);
+        })?;
+        let saved = repository.load_workspace()?;
+        let team = &saved["teams"][target];
+        assert_eq!(team["agents"]["worker"]["status"], "running");
+        assert_eq!(team["agents"]["worker"]["generation"], 2);
+        assert_eq!(team["agents"]["worker"]["explicit_stop"], false);
+        assert_eq!(team["agents"]["worker"]["session_id"], "same-session");
+        assert_eq!(committed["agents"]["worker"], team["agents"]["worker"]);
+        assert!(!crate::state::projection::agent_stopped_for_restart(&team["agents"]["worker"]));
+        assert_eq!(team["agents"]["peer"], before["teams"][target]["agents"]["peer"]);
+        assert_eq!(team["agents"]["control"], before["teams"][target]["agents"]["control"]);
+        assert_eq!(saved["teams"][other], before["teams"][other]);
+        // Root normalization retains null session fields that compact team
+        // rows omit. Build an independent root oracle, not the compact schema.
+        let mut expected_root = before["agents"].clone();
+        if target == "team-a" {
+            let row = &mut expected_root["worker"];
+            row["status"] = json!("running");
+            row["explicit_stop"] = json!(false);
+            row["generation"] = json!(2);
+            row["contract_instance"] = json!("instance-two");
+            row["native_endpoint"] = json!("new-endpoint");
+        }
+        assert_eq!(saved["agents"], expected_root);
+        // An ordinary bounded delta still cannot wake a held peer.
+        repository.commit(StateWriteIntent::ResultCollection { owner_team_id: Some(target) }, |selected| {
+            selected["agents"]["peer"]["status"] = json!("running");
+            selected["agents"]["peer"]["explicit_stop"] = json!(false);
+        })?;
+        let ordinary = repository.load_workspace()?;
+        assert_eq!(ordinary["teams"][target]["agents"], team["agents"]);
+        assert_eq!(ordinary["agents"], saved["agents"]);
+        std::fs::remove_dir_all(workspace)?;
+    }
+    Ok(())
+}

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

@@ -160,6 +160,10 @@ impl<'a> StateRepository<'a> {
     {
         #[cfg(test)]
         test_support::before_commit();
+        let lifecycle_target = match &intent {
+            StateWriteIntent::StartAgent { team_key, agent_id } => Some((*team_key, *agent_id)),
+            _ => None,
+        };
         let team_key = match intent {
             StateWriteIntent::ResultCollection { owner_team_id } => owner_team_id,
             StateWriteIntent::ForkAgent { team_key, .. }
@@ -170,7 +174,7 @@ impl<'a> StateRepository<'a> {
                 ))
             }
         };
-        let committed = super::persist::update_runtime_state(self.workspace, |latest| {
+        let committed = super::persist::update_runtime_state_with_lifecycle_target(self.workspace, lifecycle_target, |latest| {
             let mut selected = bounded_team_view(latest, team_key)?;
             update(&mut selected);
             Ok(match team_key {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.115",
+  "version": "0.5.116",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.115",
-    "@team-agent/cli-darwin-x64": "0.5.115",
-    "@team-agent/cli-linux-x64": "0.5.115"
+    "@team-agent/cli-darwin-arm64": "0.5.116",
+    "@team-agent/cli-darwin-x64": "0.5.116",
+    "@team-agent/cli-linux-x64": "0.5.116"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",