@team-agent/installer 0.5.24 → 0.5.26

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.24"
+version = "0.5.26"
 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.24"
+version = "0.5.26"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -171,10 +171,23 @@ pub(crate) fn diagnose_runtime_for_workspace(
     backend: &dyn Transport,
 ) -> (Value, Value) {
     let (mut issues, mut repairs) = diagnose_runtime(state, backend);
+    append_legacy_snapshot_issue(workspace, state, &mut issues);
     append_coordinator_health_issue(workspace, state, &mut issues, &mut repairs);
     (issues, repairs)
 }
 
+fn append_legacy_snapshot_issue(workspace: &std::path::Path, state: &Value, issues: &mut Value) {
+    let Ok(Some(details)) = crate::leader::detect_dual_state_divergence(workspace, state) else {
+        return;
+    };
+    if let Some(items) = issues.as_array_mut() {
+        items.push(json!({
+            "id": "legacy_snapshot_stale",
+            "details": details,
+        }));
+    }
+}
+
 fn append_coordinator_health_issue(
     workspace: &std::path::Path,
     state: &Value,

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,39 @@ 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):
+    /// scoped shutdown 只有一队,`state.active_team_key` 指向被关的那队。
+    /// 只在 session_killed && !verification_degraded 时被调用。
+    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;
+        };
+        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 +4168,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 +4219,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/leader/lease.rs

@@ -1780,10 +1780,13 @@ pub fn detect_dual_state_divergence( // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diag
         .or_else(|| get_path_u64(state, &["leader_receiver", "owner_epoch"]));
     let team_epoch = get_path_u64(&snap, &["team_owner", "owner_epoch"])
         .or_else(|| get_path_u64(&snap, &["leader_receiver", "owner_epoch"]));
+    let workspace_agent_bindings = agent_binding_summary(state);
+    let team_agent_bindings = agent_binding_summary(&snap);
     let diverged = workspace_owner_pane != team_owner_pane
         || workspace_owner_uuid != team_owner_uuid
         || workspace_receiver_pane != team_receiver_pane
-        || workspace_epoch != team_epoch;
+        || workspace_epoch != team_epoch
+        || workspace_agent_bindings != team_agent_bindings;
     if !diverged {
         return Ok(None);
     }
@@ -1796,10 +1799,38 @@ pub fn detect_dual_state_divergence( // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diag
         "team_receiver_pane": team_receiver_pane,
         "workspace_owner_epoch": workspace_epoch,
         "team_owner_epoch": team_epoch,
+        "workspace_agent_bindings": workspace_agent_bindings,
+        "team_agent_bindings": team_agent_bindings,
         "_legacy_snapshot_stale": true,
     })))
 }
 
+fn agent_binding_summary(state: &Value) -> Value {
+    let mut out = serde_json::Map::new();
+    let Some(agents) = state.get("agents").and_then(Value::as_object) else {
+        return Value::Object(out);
+    };
+    for (agent_id, agent) in agents {
+        let mut binding = serde_json::Map::new();
+        for key in [
+            "pane_id",
+            "pane_pid",
+            "tmux_endpoint",
+            "tmux_socket",
+            "window",
+            "window_name",
+        ] {
+            if let Some(value) = agent.get(key) {
+                binding.insert(key.to_string(), value.clone());
+            }
+        }
+        if !binding.is_empty() {
+            out.insert(agent_id.clone(), Value::Object(binding));
+        }
+    }
+    Value::Object(out)
+}
+
 fn readable_team_snapshot_path(workspace: &Path, session_name: &str) -> PathBuf { // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diagnostic-only path resolver.
     let safe_path = crate::lifecycle::helpers::team_snapshot_path(workspace, session_name); // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: reuses helpers safe legacy path.
     if safe_path.exists() {

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/mcp_server/normalize.rs

@@ -238,6 +238,9 @@ pub fn compact_tool_result(result: &Value) -> ToolResult {
             "durably_stored",
             "result_id",
             "task_id",
+            "attributed_message_id",
+            "attribution_scope",
+            "task_id_source",
             "agent_id",
             "new_agent_id",
             "source_agent_id",

package/crates/team-agent/src/mcp_server/tools.rs

@@ -20,10 +20,10 @@ use crate::state::persist::{
 use crate::messaging::{self, MessageTarget, SendOptions};
 
 use super::helpers::{
-    delivery_outcome_value, direct_message_attribution_for, ensure_object, enum_value,
-    insert_array, is_worker_recipient, json_dumps_default, latest_task_for_assignee,
-    non_empty_string, normalized_envelope_value, object_fields, requires_ack_for_target,
-    tool_runtime_error, DirectMessageAttribution,
+    current_reportable_message_for, delivery_outcome_value, direct_message_attribution_for,
+    ensure_object, enum_value, insert_array, is_worker_recipient, json_dumps_default,
+    latest_task_for_assignee, non_empty_string, normalized_envelope_value, object_fields,
+    requires_ack_for_target, tool_runtime_error, DirectMessageAttribution,
 };
 use super::normalize::{
     compact_tool_result, normalize_report_envelope, normalize_result_status_observed,
@@ -341,45 +341,76 @@ impl TeamOrchestratorTools {
                 //      only when no newer failed/refused/blocked direct turn blocks fallback
                 //   5. "manual" — truly uncorrelated; collect still rejects
                 let owner_team_id_str = self.owner_team_id.as_ref().map(|t| t.as_str().to_string());
+                let mut attributed_message_id = None;
+                let mut attribution_scope = None;
+                let mut task_id_source = None;
                 let resolved = if let Some(task_id) = task_id {
                     task_id.to_string()
                 } else if let Some(agent) = self.agent_id.as_ref() {
-                    match direct_message_attribution_for(
+                    if let Some(message_id) = current_reportable_message_for(
                         &self.workspace,
                         agent.as_str(),
                         owner_team_id_str.as_deref(),
                     ) {
-                        DirectMessageAttribution::Reportable(message_id) => message_id,
-                        DirectMessageAttribution::BlockedByNewer {
-                            message_id,
-                            status,
-                            error,
-                        } => {
-                            push_report_warning(
-                                obj,
-                                serde_json::json!({
-                                    "code": "result_attribution_blocked_by_newer_direct_message",
-                                    "field": "task_id",
-                                    "severity": "warning",
-                                    "advisory": true,
-                                    "message_id": message_id,
-                                    "message_status": status,
-                                    "message_error": error,
-                                }),
-                            );
-                            "manual".to_string()
-                        }
-                        DirectMessageAttribution::None => latest_task_for_assignee(
+                        attributed_message_id = Some(message_id.clone());
+                        attribution_scope = Some("message");
+                        task_id_source = Some("current_turn_message");
+                        message_id
+                    } else {
+                        match direct_message_attribution_for(
                             &self.workspace,
                             agent.as_str(),
                             owner_team_id_str.as_deref(),
-                        )
-                        .unwrap_or_else(|| "manual".to_string()),
+                        ) {
+                            DirectMessageAttribution::Reportable(message_id) => {
+                                attributed_message_id = Some(message_id.clone());
+                                attribution_scope = Some("message");
+                                task_id_source = Some("direct_message");
+                                message_id
+                            }
+                            DirectMessageAttribution::BlockedByNewer {
+                                message_id,
+                                status,
+                                error,
+                            } => {
+                                push_report_warning(
+                                    obj,
+                                    serde_json::json!({
+                                        "code": "result_attribution_blocked_by_newer_direct_message",
+                                        "field": "task_id",
+                                        "severity": "warning",
+                                        "advisory": true,
+                                        "message_id": message_id,
+                                        "message_status": status,
+                                        "message_error": error,
+                                    }),
+                                );
+                                "manual".to_string()
+                            }
+                            DirectMessageAttribution::None => latest_task_for_assignee(
+                                &self.workspace,
+                                agent.as_str(),
+                                owner_team_id_str.as_deref(),
+                            )
+                            .unwrap_or_else(|| "manual".to_string()),
+                        }
                     }
                 } else {
                     "manual".to_string()
                 };
                 obj.insert("task_id".to_string(), Value::String(resolved));
+                if let Some(message_id) = attributed_message_id {
+                    obj.entry("attributed_message_id")
+                        .or_insert(Value::String(message_id));
+                }
+                if let Some(scope) = attribution_scope {
+                    obj.entry("attribution_scope")
+                        .or_insert(Value::String(scope.to_string()));
+                }
+                if let Some(source) = task_id_source {
+                    obj.entry("task_id_source")
+                        .or_insert(Value::String(source.to_string()));
+                }
             }
             if !obj.contains_key("agent_id") {
                 let resolved = agent_id
@@ -419,6 +450,7 @@ impl TeamOrchestratorTools {
         let normalized = normalize_report_envelope(&base);
         let warnings = report_result_integrity_warnings(&base, &normalized);
         let mut env_value = normalized_envelope_value(&normalized);
+        copy_report_attribution_fields(&base, &mut env_value);
         if !warnings.is_empty() {
             if let Some(obj) = env_value.as_object_mut() {
                 obj.insert("warnings".to_string(), Value::Array(warnings));
@@ -985,6 +1017,24 @@ fn merge_object_fields(existing: &mut Value, incoming: &Value) {
     }
 }
 
+fn copy_report_attribution_fields(source: &Value, target: &mut Value) {
+    let Some(src) = source.as_object() else {
+        return;
+    };
+    let Some(dst) = target.as_object_mut() else {
+        return;
+    };
+    for key in [
+        "attributed_message_id",
+        "attribution_scope",
+        "task_id_source",
+    ] {
+        if let Some(value) = src.get(key) {
+            dst.entry(key.to_string()).or_insert(value.clone());
+        }
+    }
+}
+
 fn push_report_warning(obj: &mut serde_json::Map<String, Value>, warning: Value) {
     let Some(code) = warning.get("code").and_then(Value::as_str) else {
         return;

package/crates/team-agent/src/messaging/results.rs

@@ -697,6 +697,7 @@ fn report_result_for_owner_team_inner(
             "task_id".to_string(),
             serde_json::Value::String(task_id.to_string()),
         );
+        copy_report_attribution_fields(envelope, &mut out);
         out.insert(
             "agent_id".to_string(),
             serde_json::Value::String(agent_id.to_string()),
@@ -927,6 +928,7 @@ fn report_result_for_owner_team_inner(
         "task_id".to_string(),
         serde_json::Value::String(task_id.to_string()),
     );
+    copy_report_attribution_fields(envelope, &mut out);
     out.insert(
         "agent_id".to_string(),
         serde_json::Value::String(agent_id.to_string()),
@@ -968,6 +970,21 @@ fn report_result_for_owner_team_inner(
     Ok(serde_json::Value::Object(out))
 }
 
+fn copy_report_attribution_fields(
+    envelope: &serde_json::Value,
+    out: &mut serde_json::Map<String, serde_json::Value>,
+) {
+    for key in [
+        "attributed_message_id",
+        "attribution_scope",
+        "task_id_source",
+    ] {
+        if let Some(value) = envelope.get(key) {
+            out.insert(key.to_string(), value.clone());
+        }
+    }
+}
+
 fn fallback_primary_error_text(cli_primary_error: Option<&str>, observed: String) -> String {
     match cli_primary_error.filter(|error| !error.trim().is_empty()) {
         Some(error) => format!("{error}; {observed}"),

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

@@ -5,7 +5,7 @@
 //! paths or behaviour. It introduces a shared vocabulary that Stage 2 (owner
 //! repository), Stage 5 (per-team runtime state), and Stage 6 (per-team
 //! coordinator) will all consume, so that no later stage has to hand-build
-//! `.team/runtime/<team_key>/...` paths or guess the canonical team_key from
+//! `.team/runtime/teams/<team_key>/...` paths or guess the canonical team_key from
 //! a display name.
 //!
 //! Canonical rules:
@@ -15,10 +15,10 @@
 //! - For the foundation slice, `TeamScope::new(team_key)` accepts whatever
 //!   the caller already resolved (state/selector + state/persist already do
 //!   this work). Slug/hash promotion to global uniqueness lands in Stage 5.
-//! - `TeamRuntimePaths` is the SINGLE place where the
-//!   `.team/runtime/<team_key>/` layout is constructed. Anywhere downstream
-//!   code today hand-joins `runtime_dir(ws).join(team_key).join(...)` it
-//!   should migrate to call a method on `TeamRuntimePaths` in a later stage.
+//! - `TeamRuntimePaths` is the SINGLE place where the future B3
+//!   `.team/runtime/teams/<team_key>/` layout is constructed. Anywhere
+//!   downstream code today hand-joins runtime team paths should migrate to
+//!   call a method on `TeamRuntimePaths` in a later stage.
 //!
 //! Single-team behaviour: unchanged. The foundation does not move data, does
 //! not introduce new files, and is invoked by zero existing call sites yet.
@@ -72,15 +72,15 @@ impl TeamScope {
     }
 }
 
-/// Single source of `.team/runtime/<team_key>/...` path construction.
+/// Single source of future B3 `.team/runtime/teams/<team_key>/...` path construction.
 ///
 /// Stage 2 (owner repository), Stage 5 (per-team state), Stage 6 (per-team
 /// coordinator), and Stage 7 (per-team tmux socket) will all migrate from
 /// hand-built paths to `TeamRuntimePaths`. Today nothing reads from these
 /// methods yet — the foundation just owns the layout decision so when later
-/// stages start writing `.team/runtime/<team_key>/state.json` (Stage 5) or
-/// `.team/runtime/<team_key>/coordinator.pid` (Stage 6), there is exactly
-/// one place to change the layout.
+/// stages start writing `.team/runtime/teams/<team_key>/state.json` (Stage 5)
+/// or `.team/runtime/teams/<team_key>/coordinator.pid` (Stage 6), there is
+/// exactly one place to change the layout.
 #[derive(Debug, Clone)]
 pub struct TeamRuntimePaths {
     workspace: PathBuf,
@@ -110,34 +110,36 @@ impl TeamRuntimePaths {
         &self.team_key
     }
 
-    /// `.team/runtime/<team_key>/` — the team's runtime directory. Today this
-    /// already exists (runtime_spec lives under it). Stage 5 will start
-    /// writing `state.json` here too.
+    /// `.team/runtime/teams/<team_key>/` — the team's future B3 runtime
+    /// directory. It is not used as product authority until the B3 migration;
+    /// current callers must keep using `runtime_state_path`.
     pub fn team_dir(&self) -> PathBuf {
-        runtime_dir(&self.workspace).join(&self.team_key)
+        runtime_dir(&self.workspace)
+            .join("teams")
+            .join(&self.team_key)
     }
 
-    /// `.team/runtime/<team_key>/team.spec.yaml` — runtime spec. Mirrors the
-    /// existing `runtime_spec_path` helper; provided here so downstream
-    /// callers don't need to import two layout APIs.
+    /// Transitional runtime spec path. Mirrors the existing
+    /// `runtime_spec_path` helper while specs remain at
+    /// `.team/runtime/<team_key>/team.spec.yaml`.
     pub fn spec_path(&self) -> PathBuf {
         runtime_spec_path(&self.workspace, &self.team_key)
     }
 
-    /// `.team/runtime/<team_key>/state.json` — the canonical per-team state
-    /// path that Stage 5 will start writing. Not used by Stage 0 product
-    /// code; callers must continue using `runtime_state_path` until Stage 5
+    /// `.team/runtime/teams/<team_key>/state.json` — the canonical per-team
+    /// state path that B3 will start writing. Not used by current product
+    /// code; callers must continue using `runtime_state_path` until B3
     /// migrates the truth source.
     pub fn state_path(&self) -> PathBuf {
         self.team_dir().join("state.json")
     }
 
-    /// `.team/runtime/<team_key>/coordinator.pid` — Stage 6 sidecar location.
+    /// `.team/runtime/teams/<team_key>/coordinator.pid` — future sidecar location.
     pub fn coordinator_pid_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.pid")
     }
 
-    /// `.team/runtime/<team_key>/coordinator.log` — Stage 6 sidecar location.
+    /// `.team/runtime/teams/<team_key>/coordinator.log` — future sidecar location.
     pub fn coordinator_log_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.log")
     }
@@ -240,23 +242,20 @@ mod tests {
     }
 
     #[test]
-    fn team_runtime_paths_layout_matches_existing_runtime_dir_layout() {
+    fn team_runtime_paths_layout_preannounces_b3_state_dir() {
         let paths = TeamRuntimePaths::new(PathBuf::from("/ws/proj"), "alpha");
-        assert_eq!(
-            paths.team_dir(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha")
-        );
+        let b3_team_dir = PathBuf::from("/ws/proj/.team/runtime")
+            .join("teams")
+            .join("alpha");
+        assert_eq!(paths.team_dir(), b3_team_dir);
         assert_eq!(
             paths.spec_path(),
             PathBuf::from("/ws/proj/.team/runtime/alpha/team.spec.yaml")
         );
-        assert_eq!(
-            paths.state_path(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha/state.json")
-        );
+        assert_eq!(paths.state_path(), b3_team_dir.join("state.json"));
         assert_eq!(
             paths.coordinator_pid_path(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha/coordinator.pid")
+            b3_team_dir.join("coordinator.pid")
         );
     }
 

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.24",
+  "version": "0.5.26",
   "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.24",
-    "@team-agent/cli-darwin-x64": "0.5.24",
-    "@team-agent/cli-linux-x64": "0.5.24"
+    "@team-agent/cli-darwin-arm64": "0.5.26",
+    "@team-agent/cli-darwin-x64": "0.5.26",
+    "@team-agent/cli-linux-x64": "0.5.26"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",