@team-agent/installer 0.3.39 → 0.4.0

package/crates/team-agent/src/layout/runtime_sessions.rs

@@ -0,0 +1,312 @@
+//! unit-1 (Stage 1) — typed runtime session identity.
+//!
+//! Provides two compile-time-distinct newtypes plus a `RuntimeSessions`
+//! reader that pulls them out of `state.json` in one shot.
+//!
+//! Why: every place that reads `state.session_name` or
+//! `leader_receiver.session_name` today does an ad-hoc `starts_with("team-
+//! agent-leader-")` check (or, in the false-positive cases, doesn't). The
+//! 0.3.39 leader-mis-kill class of bugs traces back to a string crossing
+//! a boundary as the wrong identity.
+//!
+//! By going through `WorkerSession::new` / `LeaderLauncherSession::new`, a
+//! leader-prefixed name can never be presented as a worker session by
+//! construction. `LeaderLauncherSession::new` enforces the inverse — only
+//! a leader-prefixed name passes.
+//!
+//! This unit is PURELY ADDITIVE: no existing call site is rewired yet.
+//! unit-3 (restart preflight guard) and unit-4 (managed leader persistence
+//! fix) are the adoption sites; they will route their state reads through
+//! `RuntimeSessions::from_state`.
+
+use crate::layout::sessions::{is_leader_session, LEADER_SESSION_PREFIX};
+use crate::transport::SessionName;
+use serde_json::Value;
+
+/// A tmux session name that is guaranteed NOT to be a leader launcher
+/// session (does not start with `team-agent-leader-`).
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct WorkerSession(SessionName);
+
+/// A tmux session name that IS a leader launcher session (starts with
+/// `team-agent-leader-`).
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct LeaderLauncherSession(SessionName);
+
+/// Why `WorkerSession::new` rejected a name.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WorkerSessionError {
+    /// The name is empty.
+    Empty,
+    /// The name carries the leader launcher prefix — must not be a worker
+    /// session by construction.
+    LeaderPrefixed { name: String },
+}
+
+/// Why `LeaderLauncherSession::new` rejected a name.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LeaderLauncherSessionError {
+    /// The name is empty.
+    Empty,
+    /// The name does not carry the required leader launcher prefix.
+    MissingLeaderPrefix { name: String },
+}
+
+impl WorkerSession {
+    pub fn new(name: impl Into<String>) -> Result<Self, WorkerSessionError> {
+        let raw: String = name.into();
+        if raw.is_empty() {
+            return Err(WorkerSessionError::Empty);
+        }
+        if raw.starts_with(LEADER_SESSION_PREFIX) {
+            return Err(WorkerSessionError::LeaderPrefixed { name: raw });
+        }
+        Ok(WorkerSession(SessionName::new(raw)))
+    }
+
+    pub fn as_str(&self) -> &str {
+        self.0.as_str()
+    }
+
+    pub fn into_session_name(self) -> SessionName {
+        self.0
+    }
+
+    pub fn session_name(&self) -> &SessionName {
+        &self.0
+    }
+}
+
+impl LeaderLauncherSession {
+    pub fn new(name: impl Into<String>) -> Result<Self, LeaderLauncherSessionError> {
+        let raw: String = name.into();
+        if raw.is_empty() {
+            return Err(LeaderLauncherSessionError::Empty);
+        }
+        if !raw.starts_with(LEADER_SESSION_PREFIX) {
+            return Err(LeaderLauncherSessionError::MissingLeaderPrefix { name: raw });
+        }
+        Ok(LeaderLauncherSession(SessionName::new(raw)))
+    }
+
+    pub fn as_str(&self) -> &str {
+        self.0.as_str()
+    }
+
+    pub fn into_session_name(self) -> SessionName {
+        self.0
+    }
+
+    pub fn session_name(&self) -> &SessionName {
+        &self.0
+    }
+}
+
+/// What `RuntimeSessions::from_state` learned about the runtime topology.
+///
+/// Both fields are `Option` because state.json may be partial: a workspace
+/// that has never seen a successful quick-start has no `session_name`, and
+/// `leader_receiver` is absent until a leader binds.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RuntimeSessions {
+    /// The worker session derived from `state.session_name`, if present
+    /// AND well-formed (not leader-prefixed).
+    pub worker: Option<WorkerSession>,
+    /// The leader launcher session derived from
+    /// `state.leader_receiver.session_name`, if present AND leader-prefixed.
+    pub leader: Option<LeaderLauncherSession>,
+    /// State fields that exist but failed validation (e.g.
+    /// `state.session_name` is leader-prefixed = the 0.3.39 bug shape).
+    /// Callers (unit-3 preflight) use this to refuse cleanly rather than
+    /// proceed with a wrong-identity name.
+    pub anomalies: Vec<RuntimeSessionAnomaly>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RuntimeSessionAnomaly {
+    /// `state.session_name` carried the leader launcher prefix — classic
+    /// 0.3.39 bug shape. cli/lifecycle MUST refuse before taking a kill
+    /// action against this string.
+    WorkerSessionNameIsLeaderPrefixed { value: String },
+    /// `leader_receiver.session_name` was present but not leader-prefixed.
+    LeaderReceiverSessionNameNotLeaderPrefixed { value: String },
+    /// `state.session_name == leader_receiver.session_name` — collision
+    /// that unit-4 explicitly fixes by stopping the persistence overwrite.
+    WorkerSessionEqualsLeaderSession { value: String },
+}
+
+impl RuntimeSessions {
+    /// Read state.json's session-identity fields and wrap them in typed
+    /// values. Never panics on bad state — anomalies are surfaced for
+    /// callers to act on.
+    pub fn from_state(state: &Value) -> Self {
+        let raw_worker = state
+            .get("session_name")
+            .and_then(Value::as_str)
+            .map(str::to_string);
+        let raw_leader = state
+            .get("leader_receiver")
+            .and_then(|r| r.get("session_name"))
+            .and_then(Value::as_str)
+            .map(str::to_string);
+
+        let mut anomalies = Vec::new();
+
+        let worker = match raw_worker.as_deref() {
+            None | Some("") => None,
+            Some(name) => match WorkerSession::new(name) {
+                Ok(w) => Some(w),
+                Err(WorkerSessionError::LeaderPrefixed { name }) => {
+                    anomalies.push(RuntimeSessionAnomaly::WorkerSessionNameIsLeaderPrefixed {
+                        value: name,
+                    });
+                    None
+                }
+                Err(WorkerSessionError::Empty) => None,
+            },
+        };
+
+        let leader = match raw_leader.as_deref() {
+            None | Some("") => None,
+            Some(name) => match LeaderLauncherSession::new(name) {
+                Ok(l) => Some(l),
+                Err(LeaderLauncherSessionError::MissingLeaderPrefix { name }) => {
+                    anomalies.push(
+                        RuntimeSessionAnomaly::LeaderReceiverSessionNameNotLeaderPrefixed {
+                            value: name,
+                        },
+                    );
+                    None
+                }
+                Err(LeaderLauncherSessionError::Empty) => None,
+            },
+        };
+
+        if let (Some(rw), Some(rl)) = (raw_worker.as_deref(), raw_leader.as_deref()) {
+            if !rw.is_empty() && rw == rl {
+                anomalies.push(RuntimeSessionAnomaly::WorkerSessionEqualsLeaderSession {
+                    value: rw.to_string(),
+                });
+            }
+        }
+
+        Self {
+            worker,
+            leader,
+            anomalies,
+        }
+    }
+
+    /// True if any session-identity anomaly was detected in state.
+    pub fn has_anomalies(&self) -> bool {
+        !self.anomalies.is_empty()
+    }
+
+    /// True if a `state.session_name` looked like a leader launcher session
+    /// — the exact 0.3.39 shape unit-3 must refuse before any kill.
+    pub fn worker_session_name_is_leader_prefixed(&self) -> bool {
+        self.anomalies
+            .iter()
+            .any(|a| matches!(a, RuntimeSessionAnomaly::WorkerSessionNameIsLeaderPrefixed { .. }))
+    }
+}
+
+/// True when `name` is a leader launcher session (mirrors
+/// `layout::sessions::is_leader_session` on a raw &str).
+pub fn name_is_leader_launcher(name: &str) -> bool {
+    let session = SessionName::new(name);
+    is_leader_session(&session)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn worker_session_new_rejects_leader_prefixed() {
+        let err = WorkerSession::new("team-agent-leader-claude-x").unwrap_err();
+        assert!(matches!(err, WorkerSessionError::LeaderPrefixed { .. }));
+    }
+
+    #[test]
+    fn worker_session_new_rejects_empty() {
+        assert!(matches!(
+            WorkerSession::new("").unwrap_err(),
+            WorkerSessionError::Empty
+        ));
+    }
+
+    #[test]
+    fn worker_session_new_accepts_team_prefixed() {
+        let w = WorkerSession::new("team-foo").unwrap();
+        assert_eq!(w.as_str(), "team-foo");
+    }
+
+    #[test]
+    fn leader_launcher_session_new_requires_leader_prefix() {
+        assert!(matches!(
+            LeaderLauncherSession::new("team-foo").unwrap_err(),
+            LeaderLauncherSessionError::MissingLeaderPrefix { .. }
+        ));
+        let l = LeaderLauncherSession::new("team-agent-leader-codex-abc").unwrap();
+        assert_eq!(l.as_str(), "team-agent-leader-codex-abc");
+    }
+
+    #[test]
+    fn runtime_sessions_from_state_clean() {
+        let state = json!({
+            "session_name": "team-foo",
+            "leader_receiver": { "session_name": "team-agent-leader-codex-abc" },
+        });
+        let r = RuntimeSessions::from_state(&state);
+        assert_eq!(r.worker.unwrap().as_str(), "team-foo");
+        assert_eq!(
+            r.leader.unwrap().as_str(),
+            "team-agent-leader-codex-abc"
+        );
+        assert!(r.anomalies.is_empty());
+    }
+
+    #[test]
+    fn runtime_sessions_from_state_flags_leader_prefixed_worker_name() {
+        // The 0.3.39 bug shape.
+        let state = json!({ "session_name": "team-agent-leader-bad" });
+        let r = RuntimeSessions::from_state(&state);
+        assert!(r.worker.is_none());
+        assert!(r.worker_session_name_is_leader_prefixed());
+        assert!(r.has_anomalies());
+    }
+
+    #[test]
+    fn runtime_sessions_from_state_flags_worker_equals_leader() {
+        let state = json!({
+            "session_name": "team-agent-leader-x",
+            "leader_receiver": { "session_name": "team-agent-leader-x" },
+        });
+        let r = RuntimeSessions::from_state(&state);
+        // Both anomalies fire: leader-prefixed worker + worker==leader.
+        assert!(r.anomalies.iter().any(|a| matches!(
+            a,
+            RuntimeSessionAnomaly::WorkerSessionNameIsLeaderPrefixed { .. }
+        )));
+        assert!(r.anomalies.iter().any(|a| matches!(
+            a,
+            RuntimeSessionAnomaly::WorkerSessionEqualsLeaderSession { .. }
+        )));
+    }
+
+    #[test]
+    fn runtime_sessions_from_state_empty_state_is_clean() {
+        let r = RuntimeSessions::from_state(&json!({}));
+        assert!(r.worker.is_none());
+        assert!(r.leader.is_none());
+        assert!(r.anomalies.is_empty());
+    }
+
+    #[test]
+    fn name_is_leader_launcher_matches_constant() {
+        assert!(name_is_leader_launcher("team-agent-leader-x"));
+        assert!(!name_is_leader_launcher("team-x"));
+    }
+}

package/crates/team-agent/src/layout/tmux_endpoint.rs

@@ -0,0 +1,162 @@
+//! unit-9 (Stage 4) — tmux endpoint selection policy, separated from the
+//! concrete `TmuxBackend` execution layer.
+//!
+//! Today the endpoint-selection rule lives inside `crate::tmux_backend`
+//! (private fn `runtime_tmux_endpoint_from_state` + helpers) intertwined
+//! with the concrete command-execution backend. The policy is independently
+//! testable — given a `state.json` value, pick which endpoint string to
+//! bind a tmux client to — but you can't reach it without spinning up the
+//! whole backend.
+//!
+//! This module exposes the policy as a small, pure, layout-layer concern.
+//! Concrete `TmuxBackend` stays in `tmux_backend.rs` for command execution.
+//! Callers that only want to KNOW the endpoint (cli printers, diagnostics,
+//! event-log fields) can ask this module instead of constructing a backend.
+//!
+//! Migration: additive. The existing `tmux_backend` API is unchanged; the
+//! policy here mirrors it byte-for-byte (verified by `endpoint_priority_matches_backend`
+//! contract tests).
+
+use std::path::Path;
+use serde_json::Value;
+
+/// Which state field (or fallback) supplied the chosen endpoint.
+///
+/// Mirrors `crate::tmux_backend::RuntimeTmuxEndpointSource` 1:1 — this
+/// public surface lets layout-layer callers reason about the source
+/// without depending on a `pub(crate)` enum.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TmuxEndpointSource {
+    /// `state.tmux_endpoint` (highest priority).
+    StateTmuxEndpoint,
+    /// `state.tmux_socket` (fallback when `tmux_endpoint` is absent).
+    StateTmuxSocket,
+    /// Derived from the workspace path (lowest priority, used when state
+    /// has no endpoint info at all — typical for never-quick-started ws).
+    WorkspaceFallback,
+}
+
+impl TmuxEndpointSource {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::StateTmuxEndpoint => "state.tmux_endpoint",
+            Self::StateTmuxSocket => "state.tmux_socket",
+            Self::WorkspaceFallback => "workspace_fallback",
+        }
+    }
+}
+
+/// Selected endpoint description: the string to pass to tmux + which state
+/// field it came from. The endpoint may be either a short socket name
+/// (`-L <name>`) or a path (`-S <path>`); callers map that to flags.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TmuxEndpointSelection {
+    pub endpoint: String,
+    pub source: TmuxEndpointSource,
+}
+
+/// Pure policy: pick the tmux endpoint to use given a (maybe-present)
+/// `state.json` Value.
+///
+/// Priority — keep in sync with `crate::tmux_backend::
+/// runtime_tmux_endpoint_from_state`:
+///   1. `state.tmux_endpoint` (non-empty string)
+///   2. `state.tmux_socket` (non-empty string)
+///   3. workspace fallback (caller supplies the derived value)
+///
+/// Returns `None` when state has neither field; callers fall back to a
+/// workspace-derived value via [`select_endpoint_for_workspace`].
+pub fn select_endpoint_from_state(state: Option<&Value>) -> Option<TmuxEndpointSelection> {
+    let state = state?;
+    if let Some(endpoint) = state
+        .get("tmux_endpoint")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        return Some(TmuxEndpointSelection {
+            endpoint: endpoint.to_string(),
+            source: TmuxEndpointSource::StateTmuxEndpoint,
+        });
+    }
+    if let Some(socket) = state
+        .get("tmux_socket")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        return Some(TmuxEndpointSelection {
+            endpoint: socket.to_string(),
+            source: TmuxEndpointSource::StateTmuxSocket,
+        });
+    }
+    None
+}
+
+/// State-first endpoint selection with workspace fallback. Equivalent to
+/// what `tmux_backend_for_runtime_state_or_workspace` does internally,
+/// minus the backend construction.
+pub fn select_endpoint_for_workspace(
+    workspace: &Path,
+    state: Option<&Value>,
+) -> TmuxEndpointSelection {
+    if let Some(sel) = select_endpoint_from_state(state) {
+        return sel;
+    }
+    TmuxEndpointSelection {
+        endpoint: crate::tmux_backend::socket_name_for_workspace(workspace),
+        source: TmuxEndpointSource::WorkspaceFallback,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use std::path::PathBuf;
+
+    #[test]
+    fn state_tmux_endpoint_wins_over_socket() {
+        let state = json!({
+            "tmux_endpoint": "/private/tmp/tmux-501/abc",
+            "tmux_socket": "abc",
+        });
+        let sel = select_endpoint_from_state(Some(&state)).unwrap();
+        assert_eq!(sel.endpoint, "/private/tmp/tmux-501/abc");
+        assert_eq!(sel.source, TmuxEndpointSource::StateTmuxEndpoint);
+    }
+
+    #[test]
+    fn state_tmux_socket_used_when_endpoint_absent() {
+        let state = json!({ "tmux_socket": "ta-abc" });
+        let sel = select_endpoint_from_state(Some(&state)).unwrap();
+        assert_eq!(sel.endpoint, "ta-abc");
+        assert_eq!(sel.source, TmuxEndpointSource::StateTmuxSocket);
+    }
+
+    #[test]
+    fn empty_strings_are_ignored() {
+        let state = json!({ "tmux_endpoint": "", "tmux_socket": "" });
+        assert!(select_endpoint_from_state(Some(&state)).is_none());
+    }
+
+    #[test]
+    fn none_state_returns_none() {
+        assert!(select_endpoint_from_state(None).is_none());
+    }
+
+    #[test]
+    fn workspace_fallback_kicks_in_with_no_state_endpoint() {
+        let ws = PathBuf::from("/tmp/ta-unit9-fallback");
+        let sel = select_endpoint_for_workspace(&ws, None);
+        assert_eq!(sel.source, TmuxEndpointSource::WorkspaceFallback);
+        assert!(!sel.endpoint.is_empty());
+    }
+
+    #[test]
+    fn workspace_fallback_skipped_when_state_carries_endpoint() {
+        let ws = PathBuf::from("/tmp/ta-unit9-prefer-state");
+        let state = json!({ "tmux_endpoint": "state-endpoint-x" });
+        let sel = select_endpoint_for_workspace(&ws, Some(&state));
+        assert_eq!(sel.endpoint, "state-endpoint-x");
+        assert_eq!(sel.source, TmuxEndpointSource::StateTmuxEndpoint);
+    }
+}

package/crates/team-agent/src/leader/start.rs

@@ -546,7 +546,33 @@ fn persist_managed_leader_binding(
         "os_user": identity.os_user,
     });
     if let Some(obj) = state.as_object_mut() {
-        obj.insert("session_name".to_string(), serde_json::json!(session));
+        // unit-4 (Stage 1) ROOT CAUSE FIX of 0.3.39 leader mis-kill:
+        //
+        // BEFORE: `obj.insert("session_name", json!(session));` wrote the
+        //   leader launcher session (always `team-agent-leader-*`) into the
+        //   top-level worker-session-name field, hijacking the identity used
+        //   by restart/shutdown when they decided what tmux session to kill.
+        //
+        // AFTER: the launcher session is recorded ONLY in
+        //   `leader_receiver.session_name` (the `receiver` block above) and
+        //   `team_owner.pane_id`. The top-level `state.session_name` keeps
+        //   whatever value the worker quick-start put there (the real worker
+        //   session). If the workspace has never been quick-started yet
+        //   (no `session_name` field at all), we leave the field absent —
+        //   restart and shutdown have safe default branches for that case.
+        //
+        // unit-3's preflight is the belt-and-suspenders backstop: even if a
+        // future regression reintroduces this overwrite, restart now refuses
+        // before killing a leader-prefixed session_name.
+        if !crate::layout::sessions::LEADER_SESSION_PREFIX.is_empty()
+            && session.starts_with(crate::layout::sessions::LEADER_SESSION_PREFIX)
+        {
+            // Explicit: skip the overwrite for leader-prefixed launcher
+            // sessions. The receiver block records the launcher session in
+            // its proper home (`leader_receiver.session_name`).
+        } else {
+            obj.insert("session_name".to_string(), serde_json::json!(session));
+        }
         obj.insert(
             "active_team_key".to_string(),
             serde_json::json!(identity.team_id.as_str()),

package/crates/team-agent/src/leader/tests/identity.rs

@@ -340,3 +340,53 @@ use super::*;
     // ── 14a. _claim_lease_no_incident OUTCOMES (golden __init__.py:598) ──────
     //
     // claim_lease_no_incident is unimplemented!() → every test here PANICS today
+    // ═══════════════════════════════════════════════════════════════════════
+    // unit-0 (Stage 0) characterization tests
+    //
+    // Pin two invariants that unit-1/3/4 will refactor behind typed
+    // identity helpers. If the constant or the prefix shape changes, the
+    // refactor must also update these tests.
+    // ═══════════════════════════════════════════════════════════════════════
+
+    #[test]
+    fn unit0_leader_session_prefix_constant_is_stable() {
+        // Pinned: the literal leader session prefix that gates "is this a
+        // leader session" decisions everywhere in the runtime.
+        assert_eq!(
+            crate::leader::start::LEADER_SESSION_PREFIX,
+            "team-agent-leader-"
+        );
+        // The layout module re-exports the same value (kept in sync via
+        // const re-export).
+        assert_eq!(
+            crate::layout::sessions::LEADER_SESSION_PREFIX,
+            crate::leader::start::LEADER_SESSION_PREFIX
+        );
+    }
+
+    #[test]
+    fn unit0_leader_prefixed_name_must_never_be_taken_as_worker_session() {
+        // Pinned invariant fed into unit-1 typed identity: any session
+        // name starting with `LEADER_SESSION_PREFIX` is a leader launcher
+        // session, never a worker session. unit-1 will wrap this rule in
+        // typed constructors (`WorkerSession::new` rejects the prefix,
+        // `LeaderLauncherSession::new` requires it).
+        let leader = "team-agent-leader-claude-x-aaaaaaaaaaaa";
+        let worker = "team-real-worker";
+        let prefix = crate::leader::start::LEADER_SESSION_PREFIX;
+        assert!(leader.starts_with(prefix));
+        assert!(!worker.starts_with(prefix));
+        // Symmetry: the runtime today uses this exact check
+        // (cli/mod.rs:261 `starts_with(LEADER_SESSION_PREFIX)`) to spare
+        // leader sessions during shutdown.
+        let leader_name = crate::transport::SessionName::new(leader);
+        let worker_name = crate::transport::SessionName::new(worker);
+        assert!(
+            crate::layout::sessions::is_leader_session(&leader_name),
+            "is_leader_session must accept a leader-prefixed session",
+        );
+        assert!(
+            !crate::layout::sessions::is_leader_session(&worker_name),
+            "is_leader_session must reject a non-prefixed session",
+        );
+    }

package/crates/team-agent/src/lib.rs

@@ -50,12 +50,16 @@ pub mod state;
 pub mod compiler;
 
 // step 7 (message_store) — team.db 上的核心消息生命周期(create/claim/mark/通知去重)。
-pub mod message_store;
+// unit-10 (Stage 4) compat shim. Physical home is now `crate::db::message_store`.
+pub use crate::db::message_store;
 
 // step 8 (provider) — ProviderAdapter trait + typed provider/turn-state/liveness 等(ROUND-0 骨架;
 // fn body unimplemented!(),P2 porter 落实现)。MUST-NOT-13:provider 调用全走 trait。
 pub mod provider;
-pub mod session_capture;
+/// unit-6 (Stage 2) compat shim. Physical home is now
+/// `crate::provider::session::capture`; this re-export keeps every
+/// `crate::session_capture::*` caller working without modification.
+pub use crate::provider::session::capture as session_capture;
 pub(crate) mod os_probe;
 
 // step 9 (transport) — Transport trait(控制面)+ Target/PaneId/InjectReport 等(ROUND-0 骨架;

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

@@ -0,0 +1,32 @@
+//! unit-8 (Stage 3) — `lifecycle::launch::readiness` phase boundary.
+//!
+//! Dedicated home for coordinator-start + readiness-verdict computation.
+//! Future commits migrate the inline phase fns at launch.rs:2928-2944
+//! here.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReadinessPhase {
+    StartCoordinator,
+    ComputeVerdict,
+}
+
+impl ReadinessPhase {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::StartCoordinator => "launch.readiness.start_coordinator",
+            Self::ComputeVerdict => "launch.readiness.compute_verdict",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn phase_labels_are_dotted_paths_under_launch_readiness() {
+        assert!(ReadinessPhase::StartCoordinator
+            .as_str()
+            .starts_with("launch.readiness."));
+    }
+}

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

@@ -0,0 +1,32 @@
+//! unit-8 (Stage 3) — `lifecycle::launch::spawn` phase boundary.
+//!
+//! Dedicated home for the worker spawn executor. Future commits migrate
+//! `spawn_first_with_env_unset` and `spawn_into_with_env_unset` from
+//! launch.rs:376-405 here.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SpawnPhase {
+    SpawnFirstWithEnvUnset,
+    SpawnIntoWithEnvUnset,
+}
+
+impl SpawnPhase {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SpawnFirstWithEnvUnset => "launch.spawn.first_with_env_unset",
+            Self::SpawnIntoWithEnvUnset => "launch.spawn.into_with_env_unset",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn phase_labels_are_dotted_paths_under_launch_spawn() {
+        assert!(SpawnPhase::SpawnFirstWithEnvUnset
+            .as_str()
+            .starts_with("launch.spawn."));
+    }
+}