@team-agent/installer 0.3.39 → 0.4.0

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

@@ -0,0 +1,51 @@
+//! unit-8 (Stage 3) — `lifecycle::launch::spec_state` phase boundary.
+//!
+//! The dedicated home for spec/runtime-path resolution and state-tree
+//! materialization phases of `quick_start`. Lives in the
+//! `lifecycle/launch/` submodule so future commits can migrate the
+//! existing inline phase fns (launch.rs:2781-2906 and 1680-1756 ranges)
+//! here in small, reviewable pieces.
+//!
+//! Established phases (canonical names — keep stable for future
+//! migration):
+//!
+//! * `resolve_spec_paths`   — `.team/runtime/<team>/team.spec.yaml`
+//!                            resolution + workspace canonicalization
+//! * `materialize_state`    — T1 layer state.json initialization including
+//!                            agent capture fields and `spawn_cwd`
+//!
+//! This commit lands the boundary + a marker enum so unit-8's adoption
+//! sites can reference the phases by name. The phase fns themselves
+//! remain in launch.rs until the next batch of relocations.
+
+/// Named launch phases under spec_state. Used in phase labels for logs
+/// and (future) for the orchestrator's step dispatcher.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SpecStatePhase {
+    ResolveSpecPaths,
+    MaterializeState,
+}
+
+impl SpecStatePhase {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ResolveSpecPaths => "launch.spec_state.resolve_spec_paths",
+            Self::MaterializeState => "launch.spec_state.materialize_state",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn phase_labels_are_dotted_paths_under_launch_spec_state() {
+        assert!(SpecStatePhase::ResolveSpecPaths
+            .as_str()
+            .starts_with("launch.spec_state."));
+        assert!(SpecStatePhase::MaterializeState
+            .as_str()
+            .starts_with("launch.spec_state."));
+    }
+}

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

@@ -251,6 +251,11 @@ fn spawn_agents(
                 model: command_model,
                 tools: &resolved_tool_refs,
                 profile_launch: Some(&profile_launch),
+                // Layer 1 self-healing (architect probe 2026-06-22): expose
+                // agent_id as a display-name hint so Claude / Copilot
+                // adapters can pass `--name <agent_id>`. Codex has no
+                // equivalent flag and ignores the hint.
+                agent_id_hint: Some(agent_id_raw),
             })
             .map_err(|e| LifecycleError::Provider(e.to_string()))?;
         if !plan.managed_mcp_config && !profile_launch.managed_mcp_config {
@@ -923,6 +928,26 @@ fn save_launched_team_state_for_key(
         .unwrap_or_else(|| crate::state::projection::team_state_key(launched));
     let mut launched = launched.clone();
     if let Some(obj) = launched.as_object_mut() {
+        // RM-039-STAT-001 second-round fix (architect verdict
+        // 2026-06-22): the canonical runtime team key MUST be written
+        // explicitly to `state.team_key`, not only inferred from
+        // `team_dir` by `team_state_key`'s cascade. The historical
+        // bug: when `team_dir = "./.team/current"` and the runtime team
+        // is `rm039-status-working-891`, `team_state_key` cascades to
+        // the team_dir basename (`current`), but `active_team_key` is
+        // the real team key. Coordinator tick uses `team_state_key`
+        // when saving the team-scoped state, so writes land on
+        // `teams.current` instead of `teams.<active_team_key>`. Status
+        // reads `teams[active_team_key]`, sees stale data.
+        //
+        // Writing `team_key=launched_key` here pins the first branch of
+        // `team_state_key` so the cascade returns the canonical runtime
+        // team key everywhere — coordinator tick, save_team_scoped_state,
+        // and status selector all agree.
+        obj.insert(
+            "team_key".to_string(),
+            serde_json::Value::String(launched_key.clone()),
+        );
         obj.insert(
             "active_team_key".to_string(),
             serde_json::Value::String(launched_key.clone()),
@@ -4030,6 +4055,7 @@ pub fn fork_agent_with_transport(
                 model: command_model,
                 tools: &resolved_tool_refs,
                 profile_launch: Some(&profile_launch),
+                agent_id_hint: Some(as_agent_id.as_str()),
             },
         )
         .map_err(|e| {
@@ -4927,3 +4953,11 @@ fn team_workspace(team_dir: &Path) -> PathBuf {
 
 mod plan;
 pub use plan::{handle_report_result, start_plan};
+
+// unit-8 (Stage 3) phase boundary modules. Established here as named
+// homes for upcoming relocations from the launch.rs monolith. Each
+// child carries a `*Phase` enum naming the canonical phase labels used
+// in event logs and (future) the orchestrator's step dispatcher.
+pub mod readiness;
+pub mod spawn;
+pub mod spec_state;

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

@@ -190,6 +190,11 @@ pub(crate) fn start_agent_at_paths(
         .as_ref()
         .map(|placement| placement.layout_window.as_str().to_string())
         .unwrap_or_else(|| window.clone());
+    // Issue 2 (Round 3b gate review §6): pass the explicit team_key so the
+    // worker MCP env carries it through restart-agent path too. The
+    // `restart_projection_team_key` helper consolidates the same resolution
+    // used for save_restart_projected_state below.
+    let resolved_team_key = restart_projection_team_key(&state, team);
     let spawn = spawn_agent_window(
         workspace,
         &session_name,
@@ -201,6 +206,7 @@ pub(crate) fn start_agent_at_paths(
         Some(&safety),
         layout_placement.as_ref(),
         None,
+        Some(resolved_team_key.as_str()),
     )?;
     mark_agent_started(&mut state, agent_id, &spawn_window, &spawn, transport, &safety)?;
     // **0.3.24 add-agent socket drift fix**: keep `state.tmux_endpoint` /
@@ -625,6 +631,16 @@ fn mark_agent_started(
         "spawn_cwd".to_string(),
         serde_json::json!(spawn.spawn_cwd.to_string_lossy().to_string()),
     );
+    // Issue 2 (Round 3b gate review §6): persist the resolved owner_team_id
+    // so future restart/start cycles read it directly from the agent row.
+    if let Some(ref team_id) = spawn.owner_team_id {
+        if !team_id.is_empty() {
+            agent.insert(
+                "owner_team_id".to_string(),
+                serde_json::json!(team_id),
+            );
+        }
+    }
     crate::lifecycle::launch::persist_command_plan_state(
         agent,
         &spawn.plan,
@@ -889,6 +905,7 @@ fn write_start_agent_start_event(
         model: command_model,
         tools: &resolved_tool_refs,
         profile_launch: Some(&profile_launch),
+        agent_id_hint: Some(agent_id.as_str()),
     };
     let mut plan = match session_id {
         Some(session_id) => adapter

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

@@ -6,8 +6,15 @@ pub(super) struct SpawnedAgentWindow {
     pub profile_launch: crate::provider::ProviderProfileLaunch,
     pub layout_placement: Option<crate::lifecycle::launch::LayoutPlacement>,
     pub spawn_cwd: std::path::PathBuf,
+    /// Issue 2 (Round 3b gate review §6): the resolved `owner_team_id` used
+    /// for this spawn's MCP env / command. Callers (`mark_agent_respawned`,
+    /// `mark_agent_started`) must persist this back into the agent row so
+    /// future restarts read it directly (priority #2 in the resolution
+    /// cascade) instead of relying on top-level `active_team_key`.
+    pub owner_team_id: Option<String>,
 }
 
+#[allow(clippy::too_many_arguments)]
 pub(super) fn spawn_agent_window(
     workspace: &Path,
     session_name: &SessionName,
@@ -19,6 +26,14 @@ pub(super) fn spawn_agent_window(
     safety: Option<&DangerousApproval>,
     layout_placement: Option<&crate::lifecycle::launch::LayoutPlacement>,
     spawn_cwd_override: Option<&Path>,
+    // Issue 2 (Round 3b gate review §6): explicit owner_team_id override.
+    // When `Some`, callers (restart/rebuild.rs, restart/agent.rs) thread the
+    // resolved `selected.team_key` through here so the worker's MCP env /
+    // command argv carries `TEAM_AGENT_OWNER_TEAM_ID=<selected team>` —
+    // even when the persisted agent row OR the top-level `active_team_key`
+    // is stale. When `None`, falls back to the legacy resolution
+    // (agent row → active_team_key) for back-compat with non-restart callers.
+    owner_team_id_override: Option<&str>,
 ) -> Result<SpawnedAgentWindow, LifecycleError> {
     let provider = agent_provider(agent);
     let auth_mode = agent_auth_mode(agent);
@@ -52,15 +67,26 @@ pub(super) fn spawn_agent_window(
         safety,
     )?;
     let resolved_tool_refs: Vec<&str> = tools.iter().map(String::as_str).collect();
-    // owner_team_id resolution: prefer the runtime-state row's `owner_team_id` (set by
-    // launch/restart); fall back to the active team key for paths that don't write the
-    // row first (e.g. add-agent calls spawn before upserting team metadata).
+    // owner_team_id resolution priority (Issue 2 fix):
+    //   1. caller's explicit override (restart paths pass `selected.team_key`)
+    //   2. agent row's persisted `owner_team_id` (set by prior launch/restart)
+    //   3. top-level `active_team_key` (legacy fallback for add-agent etc.)
+    // The override breaks the dependency on top-level state mutation: even if
+    // top-level `active_team_key` is stale (e.g. `ta-probe-ws`), a restart that
+    // resolved `selected.team_key=prerelease-040-round3b` propagates THAT team
+    // into the worker's MCP env.
     let state_for_team =
         crate::state::persist::load_runtime_state(workspace).unwrap_or(serde_json::json!({}));
-    let team_id = agent
-        .get("owner_team_id")
-        .and_then(|v| v.as_str())
+    let team_id = owner_team_id_override
+        .filter(|s| !s.is_empty())
         .map(str::to_string)
+        .or_else(|| {
+            agent
+                .get("owner_team_id")
+                .and_then(|v| v.as_str())
+                .filter(|s| !s.is_empty())
+                .map(str::to_string)
+        })
         .or_else(|| {
             let key =
                 crate::messaging::leader_receiver::active_team_key(workspace, &state_for_team);
@@ -95,6 +121,7 @@ pub(super) fn spawn_agent_window(
         model: command_model,
         tools: &resolved_tool_refs,
         profile_launch: Some(&profile_launch),
+        agent_id_hint: Some(agent_id.as_str()),
     };
     let mut plan = match resume_session_id {
         Some(session_id) => adapter
@@ -240,6 +267,7 @@ pub(super) fn spawn_agent_window(
         profile_launch,
         layout_placement: layout_placement.cloned(),
         spawn_cwd: spawn_cwd.to_path_buf(),
+        owner_team_id: team_id,
     })
 }
 
@@ -468,22 +496,95 @@ pub(super) fn resume_backing_exists_for_agent(
     session_id: &SessionId,
     rollout_path: Option<&RolloutPath>,
 ) -> bool {
-    match provider {
+    resume_backing_probe_for_agent(
+        workspace,
+        agent_id,
+        agent,
+        provider,
+        session_id,
+        rollout_path,
+    )
+    .exists
+}
+
+/// Layer 2 self-healing (leader follow-up 2026-06-22): result of probing
+/// the provider backing store for a resumable session. `checked_paths`
+/// reports every path the runtime probed so the operator can see WHICH
+/// places we looked — surfaced into the
+/// `ResumeRefusalReason::SessionBackingStoreMissing.checked_paths`
+/// field, the CLI JSON `unresumable[].checked_paths` array, and the
+/// `restart.resume_decision` event payload.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct BackingProbeResult {
+    pub exists: bool,
+    pub checked_paths: Vec<PathBuf>,
+}
+
+pub(super) fn resume_backing_probe_for_agent(
+    workspace: &Path,
+    agent_id: &AgentId,
+    agent: &serde_json::Value,
+    provider: Provider,
+    session_id: &SessionId,
+    rollout_path: Option<&RolloutPath>,
+) -> BackingProbeResult {
+    let mut checked_paths: Vec<PathBuf> = Vec::new();
+
+    // Always record the persisted rollout_path even when it does not
+    // exist — that "we looked here" tells the operator that state has a
+    // pointer but the file is gone.
+    if let Some(path) = rollout_path.map(RolloutPath::as_path) {
+        checked_paths.push(path.to_path_buf());
+    }
+
+    let exists = match provider {
         provider if !provider_supports_resume(provider) => {
             let _ = (workspace, agent_id, agent, session_id, rollout_path);
             false
         }
         Provider::Codex => {
-            rollout_path_exists(rollout_path)
-                || codex_session_transcript_exists(agent, session_id.as_str(), rollout_path)
+            let rollout_ok = rollout_path_exists(rollout_path);
+            let scan_roots = codex_session_transcript_scan_roots(agent, rollout_path);
+            for root in &scan_roots {
+                checked_paths.push(root.clone());
+            }
+            rollout_ok
+                || codex_session_transcript_exists_with_roots(
+                    session_id.as_str(),
+                    &scan_roots,
+                )
         }
         Provider::Claude | Provider::ClaudeCode => {
-            rollout_path_exists(rollout_path)
+            let rollout_ok = rollout_path_exists(rollout_path);
+            let projects_root = claude_projects_root_for_agent(agent);
+            if let Some(root) = projects_root.as_ref() {
+                checked_paths.push(root.clone());
+            }
+            let event_log_path = workspace.join(".team/logs/events.jsonl");
+            checked_paths.push(event_log_path);
+            rollout_ok
                 || event_log_transcript_exists(workspace, agent_id.as_str(), session_id.as_str())
-                || claude_project_transcript_exists(agent, session_id.as_str())
+                || projects_root.is_some_and(|root| {
+                    claude_project_transcript_exists_under(&root, session_id.as_str())
+                })
+        }
+        Provider::Copilot => {
+            if let Some(home) = std::env::var_os("HOME").map(PathBuf::from) {
+                checked_paths.push(home.join(".copilot/session-store.db"));
+            }
+            copilot_session_store_has_session(session_id.as_str())
         }
-        Provider::Copilot => copilot_session_store_has_session(session_id.as_str()),
         Provider::GeminiCli | Provider::Fake => false,
+    };
+
+    // Deduplicate while preserving order (HashSet would lose deterministic
+    // ordering needed for stable JSON/event output).
+    let mut seen: std::collections::BTreeSet<PathBuf> = std::collections::BTreeSet::new();
+    checked_paths.retain(|p| seen.insert(p.clone()));
+
+    BackingProbeResult {
+        exists,
+        checked_paths,
     }
 }
 
@@ -535,25 +636,32 @@ fn event_transcript_path(event: &serde_json::Value) -> Option<PathBuf> {
 /// so we avoid recomputing the project-dir slug, which is brittle for non-ASCII
 /// workspace paths).
 fn claude_project_transcript_exists(agent: &serde_json::Value, session_id: &str) -> bool {
-    if session_id.is_empty() {
+    let Some(root) = claude_projects_root_for_agent(agent) else {
         return false;
-    }
-    let projects_root = agent
+    };
+    claude_project_transcript_exists_under(&root, session_id)
+}
+
+fn claude_projects_root_for_agent(agent: &serde_json::Value) -> Option<PathBuf> {
+    agent
         .get("claude_projects_root")
         .and_then(serde_json::Value::as_str)
         .filter(|value| !value.is_empty())
         .map(PathBuf::from)
         .or_else(|| {
             std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".claude").join("projects"))
-        });
-    let Some(projects_root) = projects_root else {
+        })
+}
+
+fn claude_project_transcript_exists_under(projects_root: &Path, session_id: &str) -> bool {
+    if session_id.is_empty() {
         return false;
-    };
+    }
     if !projects_root.is_dir() {
         return false;
     }
     let transcript_name = format!("{session_id}.jsonl");
-    let Ok(project_dirs) = std::fs::read_dir(&projects_root) else {
+    let Ok(project_dirs) = std::fs::read_dir(projects_root) else {
         return false;
     };
     project_dirs
@@ -567,10 +675,15 @@ fn codex_session_transcript_exists(
     session_id: &str,
     rollout_path: Option<&RolloutPath>,
 ) -> bool {
-    if session_id.is_empty() {
-        return false;
-    }
-    let mut roots = Vec::new();
+    let roots = codex_session_transcript_scan_roots(agent, rollout_path);
+    codex_session_transcript_exists_with_roots(session_id, &roots)
+}
+
+fn codex_session_transcript_scan_roots(
+    agent: &serde_json::Value,
+    rollout_path: Option<&RolloutPath>,
+) -> Vec<PathBuf> {
+    let mut roots: Vec<PathBuf> = Vec::new();
     if let Some(parent) = rollout_path
         .map(RolloutPath::as_path)
         .and_then(Path::parent)
@@ -596,6 +709,13 @@ fn codex_session_transcript_exists(
     }
     roots.sort();
     roots.dedup();
+    roots
+}
+
+fn codex_session_transcript_exists_with_roots(session_id: &str, roots: &[PathBuf]) -> bool {
+    if session_id.is_empty() {
+        return false;
+    }
     roots
         .iter()
         .any(|root| session_transcript_exists_under(root, session_id, 4))

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

@@ -0,0 +1,87 @@
+//! unit-3 (Stage 1) — restart preflight session-identity guard.
+//!
+//! Single check that runs BEFORE the worker-session teardown in
+//! `rebuild::restart_inner` (and the parallel check in
+//! `common::session_name_present` callers). The guard's purpose is to
+//! REFUSE the kill when the value in `state.session_name` is actually a
+//! leader launcher session name (the 0.3.39 leader-mis-kill bug shape).
+//!
+//! Typed identity comes from unit-1's `RuntimeSessions::from_state`. This
+//! preflight is the first adoption site of that typed reader inside the
+//! restart code path.
+
+use crate::layout::{RuntimeSessionAnomaly, RuntimeSessions};
+
+/// Outcome of the preflight session-identity check.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SessionPreflight {
+    /// State's session-name fields are well-formed. The caller may proceed
+    /// with the worker-session teardown.
+    Ok,
+    /// `state.session_name` matches the leader launcher prefix. Refuse the
+    /// kill — proceeding would tear down the leader pane (E49 / 0.3.39).
+    WorkerSessionIsLeaderSession {
+        session_name: String,
+        reason: String,
+    },
+}
+
+impl SessionPreflight {
+    /// True when the preflight passed and the caller may proceed.
+    pub fn is_ok(&self) -> bool {
+        matches!(self, SessionPreflight::Ok)
+    }
+}
+
+/// Inspect `state.json` and decide whether the upcoming worker-session
+/// kill is safe. Pure: no I/O, no mutation.
+pub fn check_session_preflight(state: &serde_json::Value) -> SessionPreflight {
+    let sessions = RuntimeSessions::from_state(state);
+    if let Some(anomaly) = sessions
+        .anomalies
+        .iter()
+        .find(|a| matches!(a, RuntimeSessionAnomaly::WorkerSessionNameIsLeaderPrefixed { .. }))
+    {
+        if let RuntimeSessionAnomaly::WorkerSessionNameIsLeaderPrefixed { value } = anomaly {
+            return SessionPreflight::WorkerSessionIsLeaderSession {
+                session_name: value.clone(),
+                reason: "worker_session_is_leader_session".to_string(),
+            };
+        }
+    }
+    SessionPreflight::Ok
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn preflight_passes_clean_state() {
+        let s = json!({ "session_name": "team-foo" });
+        assert!(check_session_preflight(&s).is_ok());
+    }
+
+    #[test]
+    fn preflight_passes_empty_state() {
+        assert!(check_session_preflight(&json!({})).is_ok());
+    }
+
+    #[test]
+    fn preflight_refuses_leader_prefixed_worker_session_name() {
+        let s = json!({ "session_name": "team-agent-leader-claude-abc" });
+        let r = check_session_preflight(&s);
+        assert!(!r.is_ok());
+        match r {
+            SessionPreflight::WorkerSessionIsLeaderSession {
+                session_name,
+                reason,
+            } => {
+                assert_eq!(session_name, "team-agent-leader-claude-abc");
+                assert_eq!(reason, "worker_session_is_leader_session");
+            }
+            _ => panic!("expected WorkerSessionIsLeaderSession refusal"),
+        }
+    }
+}