@team-agent/installer 0.5.25 → 0.5.27

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.25"
+version = "0.5.27"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.25"
+version = "0.5.27"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/emit.rs

@@ -203,7 +203,13 @@ const DISPATCH_COMMANDS: &[&str] = &[
     "coordinator",
 ];
 
-const SPEC_ONLY_HELP_COMMANDS: &[&str] = &["start", "purge-agent"];
+// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.6):
+// `purge-agent` was previously listed in help but had no dispatch arm,
+// so it read as a supported recovery command while actually failing with
+// "invalid choice". The dispatch registration remains out of scope for
+// 0.5.26 (destructive semantics deserve their own CR); keep the help
+// consistent with the dispatch table so it is no longer advertised.
+const SPEC_ONLY_HELP_COMMANDS: &[&str] = &["start"];
 // Command grammar, not provider identity parsing: these are top-level CLI
 // passthrough verbs for starting a leader under a provider executable.
 const LEADER_PASSTHROUGH_COMMANDS: &[&str] = &["codex", "claude", "copilot"];
@@ -272,7 +278,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("fork-agent") => "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("remove-agent") => "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]".to_string(),
-        Some("purge-agent") => "usage: team-agent purge-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--json]".to_string(),
+        // 0.5.26 (§7.6): removed from help; dispatch was never wired.
         Some("stuck-list") => "usage: team-agent stuck-list [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("stuck-cancel") => "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]".to_string(),
         Some("acknowledge-idle") => "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
@@ -875,7 +881,8 @@ fn quick_start_args(args: &[String], cwd: &Path) -> Result<QuickStartArgs, CliEr
         return Err(CliError::Usage(
             "quick-start no longer accepts --fresh. Reset semantics moved to \
              `team-agent restart --allow-fresh`, which requires explicit user \
-             confirmation.".to_string(),
+             confirmation."
+                .to_string(),
         ));
     }
     let parsed = parse_args(args);
@@ -1307,11 +1314,7 @@ fn stuck_list_args(args: &[String], cwd: &Path) -> StuckListArgs {
 fn stuck_cancel_args(args: &[String], cwd: &Path) -> Result<StuckCancelArgs, CliError> {
     let parsed = parse_args(args);
     let workspace = workspace(&parsed, cwd);
-    refuse_if_multi_alive_team_missing_scope(
-        "stuck-cancel",
-        &workspace,
-        parsed.team.as_deref(),
-    )?;
+    refuse_if_multi_alive_team_missing_scope("stuck-cancel", &workspace, parsed.team.as_deref())?;
     Ok(StuckCancelArgs {
         agent: required_pos(&parsed, 0, "agent")?,
         workspace,
@@ -1827,10 +1830,20 @@ mod tests {
             ("sessions", &["--workspace", "--team", "--json"][..]),
             (
                 "repair-state",
-                &["--task", "--status", "--assignee", "--workspace", "--team", "--json"][..],
+                &[
+                    "--task",
+                    "--status",
+                    "--assignee",
+                    "--workspace",
+                    "--team",
+                    "--json",
+                ][..],
             ),
             ("diagnose", &["--workspace", "--team", "--json"][..]),
-            ("wait-ready", &["--workspace", "--team", "--timeout", "--json"][..]),
+            (
+                "wait-ready",
+                &["--workspace", "--team", "--timeout", "--json"][..],
+            ),
             (
                 "peek",
                 &[
@@ -2059,11 +2072,7 @@ mod tests {
     fn stuck_cancel_args_builder_refuses_on_multi_alive_team() {
         let ws = tmp_workspace();
         seed_two_alive_teams_in(&ws);
-        let argv = cli_argv(&[
-            "worker_a",
-            "--workspace",
-            &ws.to_string_lossy(),
-        ]);
+        let argv = cli_argv(&["worker_a", "--workspace", &ws.to_string_lossy()]);
         let err = stuck_cancel_args(&argv, &ws).expect_err("must refuse");
         assert!(
             err.to_string().contains("multiple alive teams"),
@@ -2156,11 +2165,7 @@ mod tests {
         // not advertised or carried in QuickStartArgs, but scripts that
         // still pass it get a clear redirect to restart --allow-fresh.
         let ws = tmp_workspace();
-        let argv = cli_argv(&[
-            "--workspace",
-            &ws.to_string_lossy(),
-            "--fresh",
-        ]);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy(), "--fresh"]);
         let err = quick_start_args(&argv, &ws).expect_err("must refuse --fresh");
         let message = err.to_string();
         assert!(
@@ -2177,10 +2182,7 @@ mod tests {
     fn quick_start_without_fresh_flag_still_builds_args() {
         // Without --fresh, args build normally (the initial-creation path).
         let ws = tmp_workspace();
-        let argv = cli_argv(&[
-            "--workspace",
-            &ws.to_string_lossy(),
-        ]);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
         let args = quick_start_args(&argv, &ws).expect("must build");
         assert_eq!(args.workspace, ws);
         // No `fresh` field anymore — the struct must compile and round-trip

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

@@ -823,8 +823,10 @@ pub mod lifecycle_port {
         let mut coordinator_pid_for_report = None;
         let coordinator_stop_reason =
             coordinator_stop_reason_for_shutdown(&run_workspace, team, &state)?;
-        let should_stop_coordinator =
-            matches!(coordinator_stop_reason, "bare_shutdown" | "scoped_last_live_team");
+        let should_stop_coordinator = matches!(
+            coordinator_stop_reason,
+            "bare_shutdown" | "scoped_last_live_team"
+        );
         let stopped = if should_stop_coordinator {
             let wp = crate::coordinator::WorkspacePath::new(run_workspace.clone());
             let coordinator_pid_before_stop = crate::coordinator::coordinator_health(&wp).pid;
@@ -867,14 +869,29 @@ pub mod lifecycle_port {
             && session_residuals.is_empty()
             && process_residuals.is_empty()
             && owned_file_residuals.is_empty();
+        // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.2):
+        // shutdown 只把 agent.status 打成 "stopped" 会让 team 自身留在
+        // `status:null` 的"看起来还活着"形态,进而卡活队写入的 SaveConflict。
+        // 只有 session_killed=true(无 kill error / 无 session/process/file
+        // residual / 无 verification degrade)才把匹配 team 的 status 打成
+        // "shutdown";degraded/false-green shutdown 保留 null,由 diagnose
+        // 走 dirty state 排查通道。
         mark_agents_stopped(&mut state);
+        let team_shutdown_status = "shutdown";
         deadline.check("save_state")?;
         if team.is_some() {
+            if session_killed && !verification_degraded {
+                mark_active_team_shutdown(&mut state, team_shutdown_status);
+            }
             crate::state::projection::save_team_scoped_state(&run_workspace, &state)?;
             promote_live_sibling_after_scoped_shutdown(&run_workspace, &state)?;
         } else {
-            let _changed_keys =
-                mark_matching_session_teams_stopped(&mut state, session_name.as_ref());
+            let _changed_keys = mark_matching_session_teams_stopped(
+                &mut state,
+                session_name.as_ref(),
+                session_killed && !verification_degraded,
+                team_shutdown_status,
+            );
             crate::state::persist::save_runtime_state(&run_workspace, &state)?;
         }
         let coordinator_status = if coordinator_timeout {
@@ -1004,7 +1021,8 @@ pub mod lifecycle_port {
         // Failed/degraded shutdowns leave the entry STALE so operators can
         // decide.
         if ok && !verification_degraded && !probe_degraded {
-            let _ = crate::cli::leader_port::unregister_after_shutdown_success(&run_workspace, team);
+            let _ =
+                crate::cli::leader_port::unregister_after_shutdown_success(&run_workspace, team);
         }
         Ok(response)
     }
@@ -2334,7 +2352,8 @@ pub mod lifecycle_port {
         let agent_id = crate::model::ids::AgentId::new(agent);
         match crate::lifecycle::remove_agent_flag_requirements(workspace, &agent_id, team) {
             Ok(requirements) => {
-                if !remove_agent_missing_flags(from_spec, confirm, force, &requirements).is_empty() {
+                if !remove_agent_missing_flags(from_spec, confirm, force, &requirements).is_empty()
+                {
                     return Ok(remove_agent_flag_refusal(
                         workspace,
                         agent,
@@ -3413,6 +3432,8 @@ pub mod lifecycle_port {
     fn mark_matching_session_teams_stopped(
         state: &mut Value,
         session_name: Option<&crate::transport::SessionName>,
+        stamp_team_shutdown: bool,
+        team_shutdown_status: &str,
     ) -> Vec<String> {
         let Some(session_name) = session_name.map(crate::transport::SessionName::as_str) else {
             return Vec::new();
@@ -3428,12 +3449,49 @@ pub mod lifecycle_port {
                 .is_some_and(|session| session == session_name);
             if matches {
                 mark_agents_stopped(team);
+                // 0.5.26 (§7.2): 只在 session_killed && !verification_degraded
+                // 时把 team 自身标成 shutdown,degraded 保留 null 让 diagnose
+                // 走 dirty state。
+                if stamp_team_shutdown {
+                    if let Some(team_obj) = team.as_object_mut() {
+                        team_obj.insert("status".to_string(), json!(team_shutdown_status));
+                    }
+                }
                 out.push(key.clone());
             }
         }
         out
     }
 
+    /// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.2) /
+    /// 0.5.27 (`.team/artifacts/0526-supermarket-shutdown-status-real-fail-locate.md` §5.1):
+    /// scoped shutdown 只有一队,`state.active_team_key` 指向被关的那队;
+    /// 只在 session_killed && !verification_degraded 时被调用。
+    ///
+    /// 同时 stamp 顶层 `state["status"]` 与 `teams[active_key]["status"]`:
+    /// scoped 关队走 `save_team_scoped_state`,反写盘的源是 `compact(top-level)`
+    /// (见 `state/persist.rs::save_team_scoped_state` +
+    /// `projection::compact_team_state`),只标 nested 会被顶层视图 clobber 丢盘。
+    /// 保留 nested 写入以维持同 tick 内的 in-memory 一致(其他 read-back 立即看到)。
+    fn mark_active_team_shutdown(state: &mut Value, status: &str) {
+        let Some(active_key) = state
+            .get("active_team_key")
+            .and_then(Value::as_str)
+            .map(str::to_string)
+        else {
+            return;
+        };
+        if let Some(obj) = state.as_object_mut() {
+            obj.insert("status".to_string(), json!(status));
+        }
+        let Some(teams) = state.get_mut("teams").and_then(Value::as_object_mut) else {
+            return;
+        };
+        if let Some(team_obj) = teams.get_mut(&active_key).and_then(Value::as_object_mut) {
+            team_obj.insert("status".to_string(), json!(status));
+        }
+    }
+
     fn promote_live_sibling_after_scoped_shutdown(
         workspace: &Path,
         stopped_state: &Value,
@@ -4120,9 +4178,7 @@ pub mod leader_port {
         response: &mut Value,
     ) {
         let Some(outcome) = crate::leader::registry::register_binding_from_state_best_effort(
-            workspace,
-            team,
-            source,
+            workspace, team, source,
         ) else {
             return;
         };
@@ -4173,11 +4229,14 @@ pub mod leader_port {
         workspace: &Path,
         team: Option<&str>,
     ) -> Option<PathBuf> {
-        let team_key = team.filter(|t| !t.is_empty()).map(str::to_string).or_else(|| {
-            crate::state::persist::load_runtime_state(workspace)
-                .ok()
-                .map(|s| crate::state::projection::team_state_key(&s))
-        })?;
+        let team_key = team
+            .filter(|t| !t.is_empty())
+            .map(str::to_string)
+            .or_else(|| {
+                crate::state::persist::load_runtime_state(workspace)
+                    .ok()
+                    .map(|s| crate::state::projection::team_state_key(&s))
+            })?;
         let path = crate::leader::registry::unregister_entry(workspace, &team_key)?;
         let event_log = crate::event_log::EventLog::new(workspace);
         let _ = event_log.write(

package/crates/team-agent/src/cli/tests/shutdown_kill_plan.rs

@@ -331,6 +331,129 @@ fn scoped_shutdown_keeps_owned_endpoint_when_sibling_session_remains() {
     );
 }
 
+#[test]
+fn scoped_clean_shutdown_persists_team_shutdown_status_after_disk_roundtrip() {
+    let ws = tmp_shutdown_workspace("scoped-clean-status-roundtrip");
+    crate::state::persist::save_runtime_state(
+        &ws,
+        &json!({
+            "schema_version": 1,
+            "active_team_key": "current",
+            "team_key": "current",
+            "session_name": "team-current",
+            "team_dir": ws.display().to_string(),
+            "workspace": ws.display().to_string(),
+            "agents": {
+                "adminweb": {
+                    "agent_id": "adminweb",
+                    "status": "running",
+                    "provider": "fake",
+                    "window": "adminweb"
+                }
+            },
+            "teams": {
+                "current": {
+                    "team_key": "current",
+                    "session_name": "team-current",
+                    "team_dir": ws.display().to_string(),
+                    "workspace": ws.display().to_string(),
+                    "agents": {
+                        "adminweb": {
+                            "agent_id": "adminweb",
+                            "status": "running",
+                            "provider": "fake",
+                            "window": "adminweb"
+                        }
+                    }
+                }
+            }
+        }),
+    )
+    .unwrap();
+
+    let out = crate::cli::lifecycle_port::shutdown_with_transport(
+        &ws,
+        true,
+        Some("current"),
+        &CleanShutdownTransport::new(),
+    )
+    .expect("shutdown should complete");
+
+    assert_eq!(out["ok"], json!(true), "shutdown report: {out}");
+    assert_eq!(out["session_killed"], json!(true), "shutdown report: {out}");
+    assert_eq!(out["verification_degraded"], json!(false), "shutdown report: {out}");
+    let saved = crate::state::persist::load_runtime_state(&ws).unwrap();
+    assert_eq!(
+        saved.pointer("/teams/current/status").and_then(serde_json::Value::as_str),
+        Some("shutdown"),
+        "0.5.27 RED: clean scoped shutdown returned session_killed=true and not degraded, \
+         so disk state must persist teams.current.status=shutdown. The compact projected \
+         save path must not drop the tombstone; saved={saved}"
+    );
+    assert_eq!(
+        saved
+            .pointer("/teams/current/agents/adminweb/status")
+            .and_then(serde_json::Value::as_str),
+        Some("stopped"),
+        "0.5.27 RED: clean shutdown must also persist stopped agents under the retained team; saved={saved}"
+    );
+}
+
+#[test]
+fn scoped_degraded_shutdown_does_not_persist_team_shutdown_status() {
+    let ws = tmp_shutdown_workspace("scoped-degraded-no-status");
+    crate::state::persist::save_runtime_state(
+        &ws,
+        &json!({
+            "schema_version": 1,
+            "active_team_key": "current",
+            "team_key": "current",
+            "session_name": "team-current",
+            "agents": {
+                "adminweb": {
+                    "agent_id": "adminweb",
+                    "status": "running",
+                    "provider": "fake",
+                    "window": "adminweb"
+                }
+            },
+            "teams": {
+                "current": {
+                    "team_key": "current",
+                    "session_name": "team-current",
+                    "agents": {
+                        "adminweb": {
+                            "agent_id": "adminweb",
+                            "status": "running",
+                            "provider": "fake",
+                            "window": "adminweb"
+                        }
+                    }
+                }
+            }
+        }),
+    )
+    .unwrap();
+
+    let out = crate::cli::lifecycle_port::shutdown_with_transport(
+        &ws,
+        true,
+        Some("current"),
+        &CleanShutdownTransport::new().with_probe_timeout("ps_table"),
+    )
+    .expect("shutdown should complete");
+
+    assert_eq!(out["session_killed"], json!(true), "shutdown report: {out}");
+    assert_eq!(out["verification_degraded"], json!(true), "shutdown report: {out}");
+    let saved = crate::state::persist::load_runtime_state(&ws).unwrap();
+    assert_ne!(
+        saved.pointer("/teams/current/status").and_then(serde_json::Value::as_str),
+        Some("shutdown"),
+        "degraded shutdown must remain dirty/diagnostic and must not stamp \
+         teams.current.status=shutdown; saved={saved}"
+    );
+}
+
 #[test]
 fn repeated_owned_endpoint_shutdowns_leave_no_socket_file_growth() {
     let ws = tmp_shutdown_workspace("owned-loop-no-growth");

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

@@ -3994,8 +3994,19 @@ fn rollback_add_agent_atomic(
     } else {
         let _ = std::fs::remove_file(spec_path);
     }
+    // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.4):
+    // rollback must tombstone the newly-added agent so the persist merge
+    // does not re-attach a `roster_stub` from the latest on disk. Without
+    // the tombstone the half-added `agents.standards` / `teams.<key>.agents.standards`
+    // survives the restore-from-pre_state pass and the retry sees
+    // "agent id already exists".
+    let deleted = [agent_id.as_str()];
     if let Some(state) = pre_runtime_state {
-        let _ = crate::state::persist::save_runtime_state(run_workspace, state);
+        let _ = crate::state::persist::save_runtime_state_with_deleted_agents(
+            run_workspace,
+            state,
+            &deleted,
+        );
     } else {
         // No prior runtime state — drop just the agent we added (load → strip → save).
         if let Ok(mut state) = crate::state::persist::load_runtime_state(run_workspace) {
@@ -4005,7 +4016,24 @@ fn rollback_add_agent_atomic(
             {
                 agents.remove(agent_id.as_str());
             }
-            let _ = crate::state::persist::save_runtime_state(run_workspace, &state);
+            if let Some(teams) = state
+                .get_mut("teams")
+                .and_then(serde_json::Value::as_object_mut)
+            {
+                for team in teams.values_mut() {
+                    if let Some(agents) = team
+                        .get_mut("agents")
+                        .and_then(serde_json::Value::as_object_mut)
+                    {
+                        agents.remove(agent_id.as_str());
+                    }
+                }
+            }
+            let _ = crate::state::persist::save_runtime_state_with_deleted_agents(
+                run_workspace,
+                &state,
+                &deleted,
+            );
         }
     }
 }

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

@@ -451,6 +451,10 @@ fn apply_persist_merge_contract(
     let skip_top_level_capture_backfill =
         should_skip_capture_backfill(top_level_team.as_deref(), skip_capture_backfill_team_key);
     if projection_matches {
+        // 0.5.26 (§7.3): top-level projection uses the incoming root state's
+        // implicit "alive" shape (top-level agents are always the active team).
+        // Passing `None` for team lifecycle keeps historical behavior when the
+        // active team is not lifecycle-marked.
         merge_agent_projection(
             "agents",
             incoming.get_mut("agents"),
@@ -459,6 +463,7 @@ fn apply_persist_merge_contract(
             skip_top_level_capture_backfill,
             skip_capture_backfill_agent_ids,
             topology_update_agent_ids,
+            None,
         )?;
         // Stage 3c (identity-boundary unified plan, architect direction
         // 2026-06-23): top-level owner copy-back removed. Pre-3c this
@@ -495,6 +500,19 @@ fn apply_persist_merge_contract(
                 continue;
             };
             let projection = format!("teams.{team}.agents");
+            // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.3):
+            // decide the containing team's aliveness from BOTH sides — a shutdown
+            // that stamped the incoming as non-alive would otherwise leak the
+            // stale latest into the conflict path. `false` on either side kills
+            // the live-topology protection so a dead sibling's stale pane can't
+            // block a live sibling's write.
+            let team_alive = Some(
+                crate::state::projection::team_is_alive_candidate(latest_entry)
+                    && incoming_entry
+                        .as_object()
+                        .map(|_| crate::state::projection::team_is_alive_candidate(incoming_entry))
+                        .unwrap_or(true),
+            );
             merge_agent_projection(
                 &projection,
                 incoming_entry.get_mut("agents"),
@@ -503,6 +521,7 @@ fn apply_persist_merge_contract(
                 should_skip_capture_backfill(Some(team), skip_capture_backfill_team_key),
                 skip_capture_backfill_agent_ids,
                 topology_update_agent_ids,
+                team_alive,
             )?;
             preserve_latest_ownership_fields(incoming_entry, latest_entry);
             preserve_latest_endpoint_convergence_fields(incoming_entry, latest_entry);
@@ -528,11 +547,7 @@ fn apply_persist_merge_contract(
 fn preserve_transport_shim(incoming: &mut Value, latest: &Value) {
     // The shim block only matters when `latest` has one AND
     // `incoming` doesn't (or `incoming.transport` doesn't exist).
-    let Some(latest_shim) = latest
-        .get("transport")
-        .and_then(|t| t.get("shim"))
-        .cloned()
-    else {
+    let Some(latest_shim) = latest.get("transport").and_then(|t| t.get("shim")).cloned() else {
         return;
     };
     let Some(incoming_obj) = incoming.as_object_mut() else {
@@ -604,21 +619,20 @@ fn latest_has_preferable_endpoint_convergence(incoming: &Value, latest: &Value)
     {
         return false;
     }
-    let latest_epoch = endpoint_convergence_epoch(latest).unwrap_or_else(|| ownership_epoch(latest));
+    let latest_epoch =
+        endpoint_convergence_epoch(latest).unwrap_or_else(|| ownership_epoch(latest));
     let incoming_epoch =
         endpoint_convergence_epoch(incoming).unwrap_or_else(|| ownership_epoch(incoming));
     if latest_epoch < incoming_epoch {
         return false;
     }
-    !incoming
-        .get("topology_convergence")
-        .is_some_and(|marker| {
-            marker.get("status").and_then(Value::as_str) == Some("converged")
-                && marker
-                    .get("owner_epoch")
-                    .and_then(Value::as_u64)
-                    .is_some_and(|epoch| epoch >= latest_epoch)
-        })
+    !incoming.get("topology_convergence").is_some_and(|marker| {
+        marker.get("status").and_then(Value::as_str) == Some("converged")
+            && marker
+                .get("owner_epoch")
+                .and_then(Value::as_u64)
+                .is_some_and(|epoch| epoch >= latest_epoch)
+    })
 }
 
 fn endpoint_convergence_epoch(state: &Value) -> Option<u64> {
@@ -666,6 +680,7 @@ fn ownership_attached(state: &Value) -> bool {
     })
 }
 
+#[allow(clippy::too_many_arguments)]
 fn merge_agent_projection(
     projection: &str,
     incoming_agents: Option<&mut Value>,
@@ -674,6 +689,14 @@ fn merge_agent_projection(
     skip_capture_backfill: bool,
     skip_capture_backfill_agent_ids: &BTreeSet<String>,
     topology_update_agent_ids: &BTreeSet<String>,
+    // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.3):
+    // whether the containing team is a live protection target.
+    // - `None`: top-level projection — historical behavior, protect on truthy topology.
+    // - `Some(true)`: per-team merge for a canonical-alive team — protect.
+    // - `Some(false)`: per-team merge for a shutdown/legacy-stopped team —
+    //   the merge must NOT protect stale topology so a live sibling's write
+    //   can go through.
+    team_alive: Option<bool>,
 ) -> Result<(), StateError> {
     let Some(incoming_agents) = incoming_agents else {
         return Ok(());
@@ -695,7 +718,9 @@ fn merge_agent_projection(
                 if topology_update_agent_ids.contains(agent_id) {
                     continue;
                 }
-                if !tombstoned_for_projection && latest_has_live_topology(latest_agent) {
+                if !tombstoned_for_projection
+                    && latest_has_protected_live_topology(latest_agent, team_alive)
+                {
                     return Err(save_conflict(
                         projection,
                         agent_id,
@@ -708,7 +733,7 @@ fn merge_agent_projection(
             }
             serde_json::map::Entry::Occupied(mut existing) => {
                 if !tombstoned_for_projection && !topology_update_agent_ids.contains(agent_id) {
-                    let fields = topology_conflict_fields(existing.get(), latest_agent);
+                    let fields = topology_conflict_fields(existing.get(), latest_agent, team_alive);
                     if !fields.is_empty() {
                         return Err(save_conflict(projection, agent_id, fields));
                     }
@@ -729,7 +754,23 @@ fn save_conflict(projection: &str, agent_id: &str, fields: Vec<&'static str>) ->
     ))
 }
 
-fn latest_has_live_topology(agent: &Value) -> bool {
+/// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.3):
+/// 谓词收敛。原 `latest_has_live_topology` 只看 topology 字段真值,现改为:
+/// - 若上层告知 `team_alive=Some(false)` → 死队,永不 protect;
+/// - 若 latest 的 agent.status 是终态(stopped/dead/…)→ 永不 protect;
+/// - 否则维持原判据(topology 字段真值 → protect)。
+///
+/// 保守设计:top-level 传 `None` 时行为与 0.5.25 前完全一致(仅看 topology
+/// 真值),避免影响 F0-1/F0-2/E6 已通契约。
+fn latest_has_protected_live_topology(agent: &Value, team_alive: Option<bool>) -> bool {
+    if team_alive == Some(false) {
+        return false;
+    }
+    if let Some(status) = agent.get("status").and_then(Value::as_str) {
+        if crate::state::projection::agent_status_is_terminal(status) {
+            return false;
+        }
+    }
     LIVE_TOPOLOGY_FIELDS
         .iter()
         .any(|field| agent.get(field).is_some_and(json_truthy))
@@ -743,7 +784,16 @@ fn live_topology_fields(agent: &Value) -> Vec<&'static str> {
         .collect()
 }
 
-fn topology_conflict_fields(incoming_agent: &Value, latest_agent: &Value) -> Vec<&'static str> {
+fn topology_conflict_fields(
+    incoming_agent: &Value,
+    latest_agent: &Value,
+    team_alive: Option<bool>,
+) -> Vec<&'static str> {
+    // 0.5.26 (§7.3): 若被守卫的 team 已死 / agent 处终态,不再报 topology
+    // 冲突,允许活队 sibling write 通过。
+    if !latest_has_protected_live_topology(latest_agent, team_alive) {
+        return Vec::new();
+    }
     let latest_live = live_topology_fields(latest_agent);
     if latest_live.is_empty() {
         return Vec::new();

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

@@ -237,8 +237,15 @@ pub fn merge_workspace_team_state(existing: &Value, launched: &Value) -> Value {
     Value::Object(merged)
 }
 
-/// `team_state_candidates`(`state.py:131`):唯一候选源 = `state.teams` 中 `status=="alive"`
-/// (大小写不敏感;缺 status/空 视为 alive)。保留 teams 插入序。
+/// `team_state_candidates`(`state.py:131`):唯一候选源 = `state.teams` 中
+/// `status=="alive"`(大小写不敏感;缺 status/空 视为 alive,但 0.5.26 起
+/// legacy shutdown 残留「无 status + 全体 agents 处于终态」不再算 alive)。
+/// 保留 teams 插入序。
+///
+/// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1):
+/// shutdown 只标 agent stopped 不动 team status,retained state 让 selector
+/// 把死队当活队,进而卡活队写入的 SaveConflict。谓词收敛到
+/// [`team_is_alive_candidate`],这里只做遍历。
 pub fn team_state_candidates(state: &Value) -> Map<String, Value> {
     let mut out = Map::new();
     let teams = match state.get("teams") {
@@ -246,19 +253,7 @@ pub fn team_state_candidates(state: &Value) -> Map<String, Value> {
         _ => return out,
     };
     for (key, value) in teams {
-        if !value.is_object() {
-            continue;
-        }
-        if value.get("archived_at").is_some_and(|v| !v.is_null()) {
-            continue;
-        }
-        // `str(value.get("status") or "alive").lower()` —— None/空串 → "alive"。
-        let status = value
-            .get("status")
-            .and_then(Value::as_str)
-            .filter(|s| !s.is_empty())
-            .unwrap_or("alive");
-        if !status.eq_ignore_ascii_case("alive") {
+        if !team_is_alive_candidate(value) {
             continue;
         }
         out.insert(key.clone(), value.clone());
@@ -266,6 +261,69 @@ pub fn team_state_candidates(state: &Value) -> Map<String, Value> {
     out
 }
 
+/// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1): 唯一 alive
+/// 谓词。规则:
+/// - 非 object → 排除;
+/// - `archived_at` 非空 → 排除;
+/// - 显式 `status` → 只有 case-insensitive `alive` 才算活;
+/// - `status` 缺失/空 + `agents` 有条目且全体处于终态 → legacy shutdown
+///   residue,排除;
+/// - `status` 缺失/空 + 无 agent 或至少一个非终态 agent → 保持兼容 alive。
+pub(crate) fn team_is_alive_candidate(team: &Value) -> bool {
+    if !team.is_object() {
+        return false;
+    }
+    if team.get("archived_at").is_some_and(|v| !v.is_null()) {
+        return false;
+    }
+    let status_raw = team
+        .get("status")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty());
+    if let Some(status) = status_raw {
+        return status.eq_ignore_ascii_case("alive");
+    }
+    if all_present_agents_terminal(team) && !team_has_live_leader_binding(team) {
+        return false;
+    }
+    true
+}
+
+/// 0.5.26: legacy team 缺 `status` 时,若挂着 `leader_receiver`/`team_owner`
+/// 视为仍活的绑定面(0515 endpoint-convergence 家族:worker stopped 但 receiver
+/// attached,restart 预检要能看到 leader_receiver 以派 `leader_receiver_socket_mismatch`)。
+fn team_has_live_leader_binding(team: &Value) -> bool {
+    let is_non_null_object = |key: &str| {
+        team.get(key)
+            .filter(|v| !v.is_null())
+            .and_then(Value::as_object)
+            .is_some_and(|m| !m.is_empty())
+    };
+    is_non_null_object("leader_receiver") || is_non_null_object("team_owner")
+}
+
+fn all_present_agents_terminal(team: &Value) -> bool {
+    let Some(agents) = team.get("agents").and_then(Value::as_object) else {
+        return false;
+    };
+    if agents.is_empty() {
+        return false;
+    }
+    agents.values().all(|agent| {
+        agent
+            .get("status")
+            .and_then(Value::as_str)
+            .is_some_and(agent_status_is_terminal)
+    })
+}
+
+pub(crate) fn agent_status_is_terminal(status: &str) -> bool {
+    matches!(
+        status.to_ascii_lowercase().as_str(),
+        "stopped" | "removed" | "dead" | "terminated" | "failed"
+    )
+}
+
 /// `format_team_candidates`(`state.py:148`):候选摘要串(key 排序;agents 排序逗号连,空→`-`)。
 pub fn format_team_candidates(team_states: &Map<String, Value>) -> String {
     if team_states.is_empty() {
@@ -432,6 +490,19 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
         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))
@@ -466,6 +537,19 @@ pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Valu
         return Ok(project_top_level_view(&state, &only));
     }
     if alive.is_empty() {
+        // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1):
+        // 全体被标 shutdown(bare restart 场景),`active_team_key` 若命中
+        // `state.teams` 则仍投影,让 `project_top_level_view` 用 nested
+        // `teams[key].agents` 覆盖历史顶层注入(E2E-REST-002 前置)。
+        if let Some(active_key) = state.get("active_team_key").and_then(Value::as_str) {
+            if state
+                .get("teams")
+                .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(state);
     }
     Err(StateError::TeamSelect(
@@ -897,11 +981,19 @@ mod tests {
 
     #[test]
     fn candidates_alive_filter_and_order() {
+        // 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1):
+        // 空 bootstrap team(无 agents)在 status 缺失时保 alive 兼容;
+        // 但「status 缺失 + 全体 agent stopped」是 legacy shutdown residue,
+        // 必须被剔除,防止 shutdown --keep-logs 的死队卡活队写入。
         let s = json!({"teams": {
             "alive1": {"status": "alive", "session_name": "sa"},
             "dead1": {"status": "shutdown"},
             "nostatus": {"session_name": "sn"},
             "ALIVE_CASE": {"status": "ALIVE"},
+            "legacy_shutdown_all_stopped": {
+                "session_name": "team-supermarket-suite",
+                "agents": {"adminweb": {"status": "stopped"}}
+            },
         }});
         let cands = team_state_candidates(&s);
         let keys: Vec<&String> = cands.keys().collect();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.25",
+  "version": "0.5.27",
   "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.25",
-    "@team-agent/cli-darwin-x64": "0.5.25",
-    "@team-agent/cli-linux-x64": "0.5.25"
+    "@team-agent/cli-darwin-arm64": "0.5.27",
+    "@team-agent/cli-darwin-x64": "0.5.27",
+    "@team-agent/cli-linux-x64": "0.5.27"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",