@team-agent/installer 0.3.7 → 0.3.9

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

@@ -768,28 +768,165 @@ fn env_nonempty(key: &str) -> bool {
 ///   action : `unset TEAM_AGENT_LEADER_PANE_ID, or set it to a live tmux pane id`
 ///   log    : `TEAM_AGENT_LEADER_PANE_ID=%<id>`
 /// env 未设(或空)→ Ok(())。
-/// env 设了但 transport.liveness(pane) 报 Dead → Err(RequirementUnmet)。
-/// liveness 返 Unknown 不挡(被动路径降级):本主动路径只对【显式 Dead】fail-fast,
+/// env 设了但 pane 可判定为 Dead/Absent → Err(RequirementUnmet)。
+/// 真实 tmux 后端跨所有现存 tmux socket server 探测:TEAM_AGENT_LEADER_PANE_ID 是用户
+/// override 指针,不归属当前 team socket。
+/// probe 返 Unknown 不挡(被动路径降级):本主动路径只对【显式 Dead/Absent】fail-fast,
 /// MUST-17 不过度设计 / unset 走 pass-through(b7_unset_leader_pane_env_passes_through 守)。
 pub(crate) fn validate_active_leader_pane_env(
     transport: &dyn Transport,
+) -> Result<(), LifecycleError> {
+    validate_active_leader_pane_env_with_workspaces(transport, &[])
+}
+
+pub(crate) fn validate_active_leader_pane_env_with_workspace(
+    transport: &dyn Transport,
+    workspace: Option<&Path>,
+) -> Result<(), LifecycleError> {
+    let workspaces = workspace.into_iter().collect::<Vec<_>>();
+    validate_active_leader_pane_env_with_workspaces(transport, &workspaces)
+}
+
+pub(crate) fn validate_active_leader_pane_env_with_workspaces(
+    transport: &dyn Transport,
+    workspaces: &[&Path],
 ) -> Result<(), LifecycleError> {
     let pane_id_raw = match std::env::var("TEAM_AGENT_LEADER_PANE_ID") {
         Ok(v) if !v.is_empty() => v,
         _ => return Ok(()),
     };
-    let probe = transport.liveness(&crate::transport::PaneId::new(&pane_id_raw));
-    let dead = matches!(probe, Ok(crate::transport::PaneLiveness::Dead));
-    if !dead {
+    let pane = crate::transport::PaneId::new(&pane_id_raw);
+    if !is_tmux_pane_id_format(&pane) {
+        write_invalid_leader_pane_env_warning(workspaces, &pane_id_raw);
         return Ok(());
     }
+    let failure = match leader_pane_env_state_for_validation(transport, &pane) {
+        LeaderPaneEnvState::Dead => Some("dead"),
+        LeaderPaneEnvState::Absent => Some("absent"),
+        LeaderPaneEnvState::Live | LeaderPaneEnvState::Unknown => None,
+    };
+    let Some(reason) = failure else {
+        return Ok(());
+    };
     Err(LifecycleError::RequirementUnmet(format!(
-        "TEAM_AGENT_LEADER_PANE_ID points at a dead/absent pane: {pane_id_raw}\n\
+        "TEAM_AGENT_LEADER_PANE_ID points at a {reason} pane: {pane_id_raw}\n\
          action: unset TEAM_AGENT_LEADER_PANE_ID, or set it to a live tmux pane id\n\
          log: TEAM_AGENT_LEADER_PANE_ID={pane_id_raw}"
     )))
 }
 
+fn write_invalid_leader_pane_env_warning(workspaces: &[&Path], pane_id_raw: &str) {
+    let message = "invalid pane id format, skipping validation";
+    let mut wrote = false;
+    let mut errors = Vec::new();
+    let mut seen = BTreeSet::new();
+    for workspace in workspaces {
+        let key = workspace.to_string_lossy().to_string();
+        if !seen.insert(key.clone()) {
+            continue;
+        }
+        match crate::event_log::EventLog::new(workspace).write(
+            "leader_pane_env.validation_warning",
+            serde_json::json!({
+                "env": "TEAM_AGENT_LEADER_PANE_ID",
+                "value": pane_id_raw,
+                "warning": message,
+            }),
+        ) {
+            Ok(_) => wrote = true,
+            Err(err) => errors.push(format!("{key}: {err}")),
+        }
+    }
+    if !wrote {
+        eprintln!("TEAM_AGENT_LEADER_PANE_ID={pane_id_raw}: {message}");
+        if !errors.is_empty() {
+            eprintln!(
+                "TEAM_AGENT_LEADER_PANE_ID warning event write failed: {}",
+                errors.join("; ")
+            );
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum LeaderPaneEnvState {
+    Live,
+    Dead,
+    Absent,
+    Unknown,
+}
+
+fn leader_pane_env_state_for_validation(
+    transport: &dyn Transport,
+    pane: &crate::transport::PaneId,
+) -> LeaderPaneEnvState {
+    if !is_tmux_pane_id_format(pane) {
+        return LeaderPaneEnvState::Unknown;
+    }
+    if transport.probes_real_tmux_socket_roots() {
+        return active_leader_pane_state_across_tmux_sockets(pane);
+    }
+    active_leader_pane_state(transport, pane)
+}
+
+fn is_tmux_pane_id_format(pane: &crate::transport::PaneId) -> bool {
+    let pane = pane.as_str();
+    pane.len() > 1 && pane.starts_with('%') && pane[1..].chars().all(|ch| ch.is_ascii_digit())
+}
+
+fn active_leader_pane_state_across_tmux_sockets(
+    pane: &crate::transport::PaneId,
+) -> LeaderPaneEnvState {
+    let endpoints = crate::tmux_backend::tmux_socket_endpoints();
+    let transports = endpoints
+        .iter()
+        .map(|endpoint| crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint))
+        .collect::<Vec<_>>();
+    active_leader_pane_state_across_transports(
+        transports.iter().map(|transport| transport as &dyn Transport),
+        pane,
+    )
+}
+
+pub(crate) fn active_leader_pane_state_across_transports<'a>(
+    transports: impl IntoIterator<Item = &'a dyn Transport>,
+    pane: &crate::transport::PaneId,
+) -> LeaderPaneEnvState {
+    let mut found_absent = false;
+    let mut found_dead = false;
+    for transport in transports {
+        match active_leader_pane_state(transport, pane) {
+            LeaderPaneEnvState::Live => return LeaderPaneEnvState::Live,
+            LeaderPaneEnvState::Dead => found_dead = true,
+            LeaderPaneEnvState::Absent => found_absent = true,
+            LeaderPaneEnvState::Unknown => {}
+        }
+    }
+    if found_dead {
+        LeaderPaneEnvState::Dead
+    } else if found_absent {
+        LeaderPaneEnvState::Absent
+    } else {
+        LeaderPaneEnvState::Unknown
+    }
+}
+
+fn active_leader_pane_state(
+    transport: &dyn Transport,
+    pane: &crate::transport::PaneId,
+) -> LeaderPaneEnvState {
+    match transport.has_pane(pane) {
+        Ok(Some(true)) => return LeaderPaneEnvState::Live,
+        Ok(Some(false)) => return LeaderPaneEnvState::Absent,
+        Ok(None) | Err(_) => {}
+    }
+    match transport.liveness(pane) {
+        Ok(crate::transport::PaneLiveness::Live) => LeaderPaneEnvState::Live,
+        Ok(crate::transport::PaneLiveness::Dead) => LeaderPaneEnvState::Dead,
+        Ok(crate::transport::PaneLiveness::Unknown) | Err(_) => LeaderPaneEnvState::Unknown,
+    }
+}
+
 fn seed_unbound_launched_owner(launched: &mut serde_json::Value, launched_key: &str) {
     let Some(owner) = unbound_launched_owner(launched, launched_key) else {
         return;
@@ -1884,7 +2021,9 @@ pub fn quick_start_with_transport_in_workspace(
     // owner_bind / lease / display 任一消费点。被动路径(display/seed 等)各自走
     // 降级+event,不在这里挡。错误三行式:error(含 pane id 字面)/action(unset
     // 或修 env)/log(env var 名)。
-    validate_active_leader_pane_env(transport)?;
+    let team_workspace = team_workspace(agents_dir);
+    let warning_workspaces = [workspace, team_workspace.as_path()];
+    validate_active_leader_pane_env_with_workspaces(transport, &warning_workspaces)?;
     if !agents_dir.exists() {
         return Err(LifecycleError::Compile(format!(
             "agents dir not found: {}",
@@ -1920,18 +2059,40 @@ pub fn quick_start_with_transport_in_workspace(
                 .as_deref()
                 .is_none_or(|team| runtime_state_has_quick_start_team(&state, team))
             {
+                let session_name = state
+                    .get("session_name")
+                    .and_then(serde_json::Value::as_str)
+                    .filter(|s| !s.is_empty())
+                    .map(SessionName::new);
+                let attach_commands = session_name
+                    .as_ref()
+                    .map(|session| {
+                        let windows = quick_start_attach_window_names(&state);
+                        crate::tmux_backend::attach_commands_for_windows(
+                            &workspace,
+                            session,
+                            windows.iter().map(String::as_str),
+                        )
+                    })
+                    .unwrap_or_default();
+                let mut next_actions = vec![
+                    "run restart to resume the existing team or pass --fresh to replace it"
+                        .to_string(),
+                ];
+                if session_name.is_some() {
+                    if crate::tmux_backend::socket_probe_missing_for_workspace(&workspace) {
+                        next_actions.push(crate::tmux_backend::socket_missing_hint_for_workspace(
+                            &workspace,
+                        ));
+                    }
+                    next_actions.extend(attach_commands.iter().cloned());
+                }
                 return Ok(QuickStartReport::ExistingRuntime {
                     team: requested_team.clone(),
-                    session_name: state
-                        .get("session_name")
-                        .and_then(serde_json::Value::as_str)
-                        .filter(|s| !s.is_empty())
-                        .map(SessionName::new),
+                    session_name,
                     state_path: Some(state_path),
-                    next_actions: vec![
-                        "run restart to resume the existing team or pass --fresh to replace it"
-                            .to_string(),
-                    ],
+                    next_actions,
+                    attach_commands,
                 });
             }
         }
@@ -2008,6 +2169,9 @@ pub fn quick_start_with_transport_in_workspace(
     let mut next_actions = vec![format!(
         "team compiled; real spawn is behind the transport/provider boundary; {coordinator_action}"
     )];
+    if crate::tmux_backend::socket_probe_missing_for_workspace(&workspace) {
+        next_actions.push(crate::tmux_backend::socket_missing_hint_for_workspace(&workspace));
+    }
     next_actions.extend(attach_commands.iter().cloned());
     let display_backend = state
         .get("display_backend")
@@ -2024,6 +2188,29 @@ pub fn quick_start_with_transport_in_workspace(
     })
 }
 
+fn quick_start_attach_window_names(state: &serde_json::Value) -> Vec<String> {
+    let mut windows = state
+        .get("agents")
+        .and_then(serde_json::Value::as_object)
+        .map(|agents| {
+            agents
+                .iter()
+                .filter_map(|(agent_id, agent)| {
+                    agent
+                        .get("window")
+                        .and_then(serde_json::Value::as_str)
+                        .filter(|window| !window.is_empty())
+                        .map(str::to_string)
+                        .or_else(|| Some(agent_id.clone()))
+                })
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    windows.sort();
+    windows.dedup();
+    windows
+}
+
 /// BUG-7 helper: derive a [`QuickStartReadiness`] verdict from the just-written
 /// runtime state. Reads `agents[*].status`; any non-`running` agent flips the
 /// verdict to `Degraded { unhealthy_agents }` (sorted, deduped); otherwise

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

@@ -77,28 +77,41 @@ pub fn restart_with_transport_with_session_convergence_deadline(
     transport: &dyn crate::transport::Transport,
     session_converge_deadline_ms: Option<u64>,
 ) -> Result<RestartReport, LifecycleError> {
-    if crate::lifecycle::restart::input_has_no_local_team_context(workspace) {
-        return Err(LifecycleError::TeamSelect(format!(
-            "missing spec for restart: {}",
-            workspace.join("team.spec.yaml").display()
-        )));
-    }
-    let run_candidate = crate::model::paths::canonical_run_workspace(workspace)
+    // RED-2-STILL(P0):入口门必须在 canonical_run_workspace 解析后的路径上判,不用 raw workspace。
+    // 根因:quick-start <dir> 把 .team/runtime/spec 落在 team_workspace(dir)=**parent**/.team;
+    // 入口门查 raw dir 自身的 .team/state(空,它在 parent)→ 误判"无 team context"早退,到不了
+    // 067f78f 下移后的第二道门。canonical_run_workspace 已能正确解析到 parent(走 parent.join(".team")
+    // 分支),在它之上判 input_has_no_local_team_context 才对齐 quick-start 落点。
+    let resolved_ws = crate::model::paths::canonical_run_workspace(workspace)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
-    if !workspace.join("team.spec.yaml").exists()
-        && !crate::state::persist::runtime_state_path(&run_candidate).exists()
-    {
+    if crate::lifecycle::restart::input_has_no_local_team_context(&resolved_ws) {
         return Err(LifecycleError::TeamSelect(format!(
-            "missing spec for restart: {}",
-            workspace.join("team.spec.yaml").display()
+            "missing spec for restart: {} (run `team-agent quick-start <teamdir>` first)",
+            crate::model::paths::runtime_dir(&resolved_ws).display()
         )));
     }
+    // RED-2(P0)修:存在性门下移到 resolve 之后,用 selected.spec_path(读序 B:runtime 优先、
+    // legacy 用户目录回落)判,而非 resolve 前自拼 workspace/team.spec.yaml(spec-demote 后 spec
+    // 不在用户目录 → 旧门误报缺)。resolve_active_team(RequireSpec) 内部已按 spec_path 校验存在性,
+    // 故直接交给它;失败信息(含真实 expected runtime spec 路径)即正确的 N38。
     let selected = crate::state::selector::resolve_active_team(
         workspace,
         team,
         crate::state::selector::SelectorMode::RequireSpec,
     )
     .map_err(|e| LifecycleError::TeamSelect(e.to_string()))?;
+    // 显式存在性门(下移后):selected.spec_path 经读序 B 已定位 runtime/legacy spec。
+    // 缺(空目录 restart 等)→ 报真实期望路径,不误导去用户目录找。
+    if !selected.spec_path.as_ref().is_some_and(|p| p.exists()) {
+        let expected = selected
+            .spec_path
+            .clone()
+            .unwrap_or_else(|| crate::model::paths::runtime_spec_path(&selected.run_workspace, &selected.team_key));
+        return Err(LifecycleError::TeamSelect(format!(
+            "missing spec for restart: {} (run `team-agent quick-start <teamdir>` first, or restore the team's role docs)",
+            expected.display()
+        )));
+    }
     let mut state = selected.state;
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, None)?;
     // E5 task#3 / RC-A6a + E4(leader 裁定:每次 restart 都从角色定义重建 runtime spec,覆盖):

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

@@ -49,11 +49,15 @@ pub(crate) fn lifecycle_run_workspace(workspace: &Path) -> Result<std::path::Pat
 }
 
 fn lifecycle_paths(workspace: &Path, team: Option<&str>) -> Result<LifecyclePaths, LifecycleError> {
-    if input_has_no_local_team_context(workspace) {
+    // RED-2-STILL(P0):入口门在 canonical_run_workspace 解析后的路径上判(quick-start 的 .team 落
+    // team_dir 父目录,raw team_dir 必 miss)。期望路径报解析后 runtime 落点,不指 raw team_dir。
+    let resolved_ws = crate::model::paths::canonical_run_workspace(workspace)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    if input_has_no_local_team_context(&resolved_ws) {
         return Err(LifecycleError::TeamSelect(format!(
-            "active team spec not found: input_workspace={} expected_spec_path={}",
+            "active team spec not found: input_workspace={} expected_runtime_dir={}",
             workspace.display(),
-            workspace.join("team.spec.yaml").display()
+            crate::model::paths::runtime_dir(&resolved_ws).display()
         )));
     }
     let selected = crate::state::selector::resolve_active_team(

package/crates/team-agent/src/lifecycle/tests/core.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::transport::PaneLiveness;
 
 // ───────────────────────────────────────────────────────────────────────
 // classify_first_send_at — _classify_first_send_at (orchestration.py:404)
@@ -794,6 +795,189 @@ fn detect_dangerous_approval_clean_process_is_disabled() {
     assert!(!got.inherited);
 }
 
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_absent_pane_fails_fast() {
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "%9999");
+    let transport =
+        crate::transport::test_support::OfflineTransport::new().with_pane_presence("%9999", false);
+    let err = validate_active_leader_pane_env(&transport).expect_err("absent pane must fail");
+    let msg = err.to_string();
+    assert!(msg.contains("TEAM_AGENT_LEADER_PANE_ID"), "got: {msg}");
+    assert!(msg.contains("absent"), "got: {msg}");
+    assert!(msg.contains("%9999"), "got: {msg}");
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_dead_pane_fails_fast() {
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "%404");
+    let transport = crate::transport::test_support::OfflineTransport::new()
+        .with_liveness("%404", PaneLiveness::Dead);
+    let err = validate_active_leader_pane_env(&transport).expect_err("dead pane must fail");
+    let msg = err.to_string();
+    assert!(msg.contains("TEAM_AGENT_LEADER_PANE_ID"), "got: {msg}");
+    assert!(msg.contains("dead"), "got: {msg}");
+    assert!(msg.contains("%404"), "got: {msg}");
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_unset_passes_without_probe() {
+    let _leader_pane = EnvVarGuard::remove("TEAM_AGENT_LEADER_PANE_ID");
+    let transport = crate::transport::test_support::OfflineTransport::new();
+    validate_active_leader_pane_env(&transport).expect("unset env must pass");
+    assert!(
+        transport.calls().is_empty(),
+        "unset env must not probe transport: {:?}",
+        transport.calls()
+    );
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_unknown_when_unprovable_does_not_fail_fast() {
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "%8888");
+    let transport = crate::transport::test_support::OfflineTransport::new()
+        .with_default_liveness(PaneLiveness::Unknown);
+    validate_active_leader_pane_env(&transport).expect("unknown/unprovable pane must not fail");
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_non_numeric_pane_id_is_unknown_not_absent() {
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "abc-notapane");
+    let transport = crate::transport::test_support::OfflineTransport::new()
+        .with_pane_presence("abc-notapane", false)
+        .with_liveness("abc-notapane", PaneLiveness::Dead);
+    validate_active_leader_pane_env(&transport)
+        .expect("non `%<digits>` env values are unprovable, not absent");
+    assert!(
+        transport.calls().is_empty(),
+        "invalid pane id format must not hit tmux probe: {:?}",
+        transport.calls()
+    );
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_invalid_format_writes_warning_event() {
+    let ws = temp_ws();
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "abc-notapane");
+    let transport = crate::transport::test_support::OfflineTransport::new()
+        .with_pane_presence("abc-notapane", false);
+
+    validate_active_leader_pane_env_with_workspace(&transport, Some(&ws))
+        .expect("invalid format is warning-only");
+
+    let events = crate::event_log::EventLog::new(&ws).tail(0).expect("events");
+    let event = events
+        .iter()
+        .find(|event| {
+            event.get("event").and_then(serde_json::Value::as_str)
+                == Some("leader_pane_env.validation_warning")
+        })
+        .expect("warning event");
+    assert_eq!(
+        event.get("value").and_then(serde_json::Value::as_str),
+        Some("abc-notapane")
+    );
+    assert_eq!(
+        event.get("warning").and_then(serde_json::Value::as_str),
+        Some("invalid pane id format, skipping validation")
+    );
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn leader_pane_env_invalid_format_writes_warning_to_all_candidate_workspaces() {
+    let cli_ws = temp_ws();
+    let team_ws = temp_ws();
+    let _leader_pane = EnvVarGuard::set("TEAM_AGENT_LEADER_PANE_ID", "abc-notapane");
+    let transport = crate::transport::test_support::OfflineTransport::new();
+
+    validate_active_leader_pane_env_with_workspaces(&transport, &[&cli_ws, &team_ws])
+        .expect("invalid format is warning-only");
+
+    for ws in [&cli_ws, &team_ws] {
+        let events = crate::event_log::EventLog::new(ws).tail(0).expect("events");
+        assert!(
+            events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("leader_pane_env.validation_warning")
+                    && event.get("value").and_then(serde_json::Value::as_str)
+                        == Some("abc-notapane")
+            }),
+            "warning event missing in {}: {events:?}",
+            ws.display()
+        );
+    }
+}
+
+#[test]
+fn leader_pane_env_cross_socket_live_wins() {
+    let pane = crate::transport::PaneId::new("%7");
+    let absent =
+        crate::transport::test_support::OfflineTransport::new().with_pane_presence("%7", false);
+    let live =
+        crate::transport::test_support::OfflineTransport::new().with_pane_presence("%7", true);
+
+    let state = active_leader_pane_state_across_transports(
+        [&absent as &dyn crate::transport::Transport, &live],
+        &pane,
+    );
+
+    assert_eq!(state, LeaderPaneEnvState::Live);
+}
+
+#[test]
+fn leader_pane_env_cross_socket_dead_rejects_without_live() {
+    let pane = crate::transport::PaneId::new("%404");
+    let absent = crate::transport::test_support::OfflineTransport::new()
+        .with_pane_presence("%404", false);
+    let dead = crate::transport::test_support::OfflineTransport::new()
+        .with_liveness("%404", PaneLiveness::Dead);
+
+    let state = active_leader_pane_state_across_transports(
+        [&absent as &dyn crate::transport::Transport, &dead],
+        &pane,
+    );
+
+    assert_eq!(state, LeaderPaneEnvState::Dead);
+}
+
+#[test]
+fn leader_pane_env_cross_socket_absent_when_reachable_servers_confirm_missing() {
+    let pane = crate::transport::PaneId::new("%9999");
+    let absent = crate::transport::test_support::OfflineTransport::new()
+        .with_pane_presence("%9999", false);
+    let unknown = crate::transport::test_support::OfflineTransport::new()
+        .with_default_liveness(PaneLiveness::Unknown);
+
+    let state = active_leader_pane_state_across_transports(
+        [&absent as &dyn crate::transport::Transport, &unknown],
+        &pane,
+    );
+
+    assert_eq!(state, LeaderPaneEnvState::Absent);
+}
+
+#[test]
+fn leader_pane_env_cross_socket_all_probe_errors_stays_unknown() {
+    let pane = crate::transport::PaneId::new("%maybe");
+    let unknown_a = crate::transport::test_support::OfflineTransport::new()
+        .with_default_liveness(PaneLiveness::Unknown);
+    let unknown_b = crate::transport::test_support::OfflineTransport::new()
+        .with_default_liveness(PaneLiveness::Unknown);
+
+    let state = active_leader_pane_state_across_transports(
+        [&unknown_a as &dyn crate::transport::Transport, &unknown_b],
+        &pane,
+    );
+
+    assert_eq!(state, LeaderPaneEnvState::Unknown);
+}
+
 struct EnvVarGuard {
     key: &'static str,
     previous: Option<String>,
@@ -807,6 +991,14 @@ impl EnvVarGuard {
         }
         Self { key, previous }
     }
+
+    fn remove(key: &'static str) -> Self {
+        let previous = std::env::var(key).ok();
+        unsafe {
+            std::env::remove_var(key);
+        }
+        Self { key, previous }
+    }
 }
 
 impl Drop for EnvVarGuard {

package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs

@@ -545,6 +545,118 @@ fn e5_restart_rebuilds_runtime_spec_from_role_docs() {
     );
 }
 
+// RED-2 (P0) — restart existence gate must use selected.spec_path (read-order B: runtime spec),
+// NOT the user-dir team.spec.yaml. spec-demote put spec under .team/runtime/<key>/, so the old
+// pre-resolve gate (`!workspace.join("team.spec.yaml").exists()`) falsely reported "missing spec".
+#[test]
+fn red2_restart_finds_runtime_spec_not_missing_when_user_dir_has_no_spec() {
+    let ws = restart_ws_two_resumable_workers(); // has TEAM.md + agents + state
+    // Simulate spec-demote: remove any user-dir spec the fixture wrote; restart must still find
+    // the runtime spec (rebuilt from role docs / read-order B), NOT report "missing spec".
+    let _ = std::fs::remove_file(ws.join("team.spec.yaml"));
+    assert!(!ws.join("team.spec.yaml").exists(), "user-dir spec removed (spec-demote condition)");
+    let transport = OfflineTransport::new();
+    let result = restart_with_transport(&ws, false, None, &transport);
+    // The gate must NOT short-circuit with "missing spec for restart" — restart must proceed
+    // (any later resume/rebuild outcome is fine; we only assert the spec-missing gate is gone).
+    let text = format!("{result:?}");
+    assert!(
+        !text.contains("missing spec for restart"),
+        "RED-2: restart must locate the runtime spec via read-order B, not report missing; got {text}"
+    );
+}
+
+// RED-2 negative — a truly empty workspace (no role docs, no spec, no state) must STILL report
+// missing spec (gate moved, not removed).
+#[test]
+fn red2_restart_empty_workspace_still_reports_missing() {
+    let ws = temp_ws(); // empty, no TEAM.md/agents/spec/state
+    let transport = OfflineTransport::new();
+    let result = restart_with_transport(&ws, false, None, &transport);
+    let text = format!("{result:?}");
+    assert!(
+        text.contains("missing spec") || text.to_lowercase().contains("not found") || text.contains("no_local_team_context") || text.to_lowercase().contains("invalid workspace"),
+        "RED-2 negative: empty workspace restart must still error (missing/not-found); got {text}"
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+// RED-2-STILL (P0) — the ENTRY gate (input_has_no_local_team_context) must judge on the
+// canonical_run_workspace-resolved path, not raw. quick-start <team_dir> lands .team under the
+// resolved workspace (team_dir's parent when invoked from there); restart <team_dir> with raw gate
+// checks team_dir's own (empty) .team → false "no context" early-exit before the down-moved gate.
+//
+// Two forms (leader hard requirement — must lock BOTH, not the coincidental same-dir form):
+//   Form A: .team in the team_dir's PARENT (standard quick-start <dir> from parent cwd).
+//   Form B: .team in the team_dir itself (cwd == team_dir).
+#[test]
+fn red2still_entry_gate_resolves_parent_dot_team_form_a() {
+    // Build: base/  (has .team)  + base/teamdir/{TEAM.md, agents/} (role docs, NO own .team).
+    let base = temp_ws();
+    let team_dir = base.join("teamdir");
+    std::fs::create_dir_all(team_dir.join("agents")).unwrap();
+    std::fs::write(team_dir.join("TEAM.md"), "---\nname: teamdir\nobjective: o\nprovider: codex\n---\nt.\n").unwrap();
+    std::fs::write(team_dir.join("agents").join("w1.md"), QS_VALID_ROLE).unwrap();
+    // .team lives in the PARENT (base), with a runtime spec — mirrors quick-start <dir> from base cwd.
+    let spec = crate::compiler::compile_team(&team_dir).unwrap();
+    let runtime_spec = crate::model::paths::runtime_spec_path(&base, "teamdir");
+    std::fs::create_dir_all(runtime_spec.parent().unwrap()).unwrap();
+    std::fs::write(&runtime_spec, crate::model::yaml::dumps(&spec)).unwrap();
+    // Seed minimal team state under base so resolve finds it.
+    crate::state::persist::save_runtime_state(
+        &base,
+        &json!({"session_name": "team-teamdir", "team_dir": team_dir.to_string_lossy(),
+                "spec_path": runtime_spec.to_string_lossy(),
+                "agents": {"w1": {"status": "running", "provider": "codex"}}}),
+    )
+    .unwrap();
+    // Entry gate on team_dir: raw team_dir has NO .team (it's in parent), but resolved → base has it.
+    assert!(
+        crate::lifecycle::restart::input_has_no_local_team_context(&team_dir),
+        "precondition: raw team_dir has no local .team (it's in the parent)"
+    );
+    let resolved = crate::model::paths::canonical_run_workspace(&team_dir).unwrap();
+    assert!(
+        !crate::lifecycle::restart::input_has_no_local_team_context(&resolved),
+        "RED-2-STILL: gate on canonical_run_workspace-resolved path must see parent .team (false)"
+    );
+    // Full restart on team_dir must NOT early-exit with missing spec.
+    let transport = OfflineTransport::new();
+    let text = format!("{:?}", restart_with_transport(&team_dir, false, None, &transport));
+    assert!(
+        !text.contains("missing spec for restart") && !text.contains("active team spec not found"),
+        "RED-2-STILL Form A: restart <team_dir> (.team in parent) must not report missing; got {text}"
+    );
+    let _ = std::fs::remove_dir_all(&base);
+}
+
+#[test]
+fn red2still_entry_gate_same_dir_dot_team_form_b() {
+    // Form B: .team in team_dir itself (cwd == team_dir at quick-start time).
+    let team_dir = temp_ws();
+    std::fs::create_dir_all(team_dir.join("agents")).unwrap();
+    std::fs::write(team_dir.join("TEAM.md"), "---\nname: tb\nobjective: o\nprovider: codex\n---\nt.\n").unwrap();
+    std::fs::write(team_dir.join("agents").join("w1.md"), QS_VALID_ROLE).unwrap();
+    let spec = crate::compiler::compile_team(&team_dir).unwrap();
+    let runtime_spec = crate::model::paths::runtime_spec_path(&team_dir, "tb");
+    std::fs::create_dir_all(runtime_spec.parent().unwrap()).unwrap();
+    std::fs::write(&runtime_spec, crate::model::yaml::dumps(&spec)).unwrap();
+    crate::state::persist::save_runtime_state(
+        &team_dir,
+        &json!({"session_name": "team-tb", "team_dir": team_dir.to_string_lossy(),
+                "spec_path": runtime_spec.to_string_lossy(),
+                "agents": {"w1": {"status": "running", "provider": "codex"}}}),
+    )
+    .unwrap();
+    let transport = OfflineTransport::new();
+    let text = format!("{:?}", restart_with_transport(&team_dir, false, None, &transport));
+    assert!(
+        !text.contains("missing spec for restart") && !text.contains("active team spec not found"),
+        "RED-2-STILL Form B: restart <team_dir> (.team in team_dir) must not report missing; got {text}"
+    );
+    let _ = std::fs::remove_dir_all(&team_dir);
+}
+
 // E5 task#3 / RC-A6b — restart with role definitions MISSING explicitly refuses (lists what's
 // missing) and leaves the previous runtime spec in place (no silent path, no data destruction).
 #[test]