@team-agent/installer 0.5.60 → 0.5.62

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

@@ -1,14 +1,21 @@
-//! leader::start — leader_start_plan / start_leader / leader_session_name(派生 tmux session 名)。
+//!
+//! leader::start — leader_start_plan / leader_session_name(派生 tmux session 名)。
 
 use std::collections::BTreeMap;
 use std::io::{IsTerminal, Read, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 
+#[cfg(target_os = "linux")]
+use std::os::fd::AsRawFd;
+#[cfg(unix)]
+use std::os::unix::fs::{FileTypeExt, MetadataExt, OpenOptionsExt};
+
+use crate::model::pane_authority_refusal as pane_refusal;
 use crate::provider::{get_adapter, Provider};
 use crate::tmux_backend::TmuxBackend;
 use crate::transport::{
-    PaneId, PaneLiveness, SessionName, SpawnResult, Target, Transport, WindowName,
+    PaneId, PaneInfo, PaneLiveness, SessionName, SpawnResult, Target, Transport, WindowName,
 };
 
 use super::helpers::{
@@ -20,11 +27,55 @@ use super::{
     LeaderStartMode, LeaderStartPlan,
 };
 
-// ── leader::start — leader_start_plan / start_leader / session 名 ──
+// ── leader::start — leader_start_plan / session 名 ──
+
+pub(crate) struct PreparedLeaderStart {
+    plan: LeaderStartPlan,
+    ambient_authority: Option<VerifiedAmbientPaneAuthority>,
+}
+
+#[derive(Clone, Copy)]
+enum ManagedClientAttachMode {
+    AttachSession,
+    SwitchClient,
+}
+
+const DIFFERENT_TMUX_SERVER_PREFIX: &str =
+    "managed launcher refuses a different ambient tmux server";
+
+impl PreparedLeaderStart {
+    pub(crate) fn plan(&self) -> &LeaderStartPlan {
+        &self.plan
+    }
+}
+
+pub(crate) enum PrepareLeaderStartError {
+    PaneAuthorityRefused(pane_refusal::PaneAuthorityRefusal),
+    Leader(LeaderError),
+}
+
+impl PrepareLeaderStartError {
+    fn into_leader_error(self) -> LeaderError {
+        match self {
+            Self::PaneAuthorityRefused(refusal) => LeaderError::Validation(format!(
+                "{}; open a new terminal outside the current tmux/pane or run \
+                 `team-agent attach-leader` from the intended workspace pane",
+                refusal.reason().as_str()
+            )),
+            Self::Leader(error) => error,
+        }
+    }
+}
+
+impl From<LeaderError> for PrepareLeaderStartError {
+    fn from(error: LeaderError) -> Self {
+        Self::Leader(error)
+    }
+}
 
 /// `leader_start_plan`(card §46;`__init__.py:82`)。计算 leader 启动计划
 /// (exec in-TMUX / new tmux session / attach existing)。provider 未安装 → `Err(Start)`。
-pub fn leader_start_plan(
+pub(crate) fn leader_start_plan(
     provider: Provider,
     provider_args: &[String],
     workspace: &Path,
@@ -32,6 +83,122 @@ pub fn leader_start_plan(
     confirm_attach: bool,
     attach_session: Option<&SessionName>,
     external_leader: bool,
+) -> Result<LeaderStartPlan, LeaderError> {
+    prepare_leader_start(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing,
+        confirm_attach,
+        attach_session,
+        external_leader,
+    )
+    .map(|prepared| prepared.plan)
+    .map_err(PrepareLeaderStartError::into_leader_error)
+}
+
+pub(crate) fn prepare_leader_start(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+    external_leader: bool,
+) -> Result<PreparedLeaderStart, PrepareLeaderStartError> {
+    prepare_leader_start_with_nested_attach(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing,
+        confirm_attach,
+        attach_session,
+        external_leader,
+        false,
+    )
+}
+
+pub(crate) fn prepare_leader_start_with_nested_attach(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+    external_leader: bool,
+    allow_nested_attach: bool,
+) -> Result<PreparedLeaderStart, PrepareLeaderStartError> {
+    let explicit_external_path = external_leader || attach_existing || attach_session.is_some();
+    let state_external_path = workspace_state_uses_external_leader(workspace);
+    let (ambient_authority, managed_client_attach_mode, managed_provider_reentry) =
+        if explicit_external_path || state_external_path {
+            (ambient_pane_authority_preflight(workspace)?, None, false)
+        } else if workspace_state_is_managed_provider_reentry(workspace) {
+            (ambient_pane_authority_preflight(workspace)?, None, true)
+        } else {
+            let (authority, attach_mode) =
+                managed_launcher_ambient_route(workspace, allow_nested_attach)?;
+            (authority, attach_mode, false)
+        };
+    let plan = leader_start_plan_with_ambient_authority(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing,
+        confirm_attach,
+        attach_session,
+        external_leader,
+        std::env::var_os("TMUX").is_some(),
+        managed_client_attach_mode,
+        managed_provider_reentry,
+    )?;
+    Ok(PreparedLeaderStart {
+        plan,
+        ambient_authority,
+    })
+}
+
+pub(crate) fn leader_start_plan_after_ambient_authority_check(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+    external_leader: bool,
+) -> Result<LeaderStartPlan, LeaderError> {
+    let in_tmux = std::env::var_os("TMUX").is_some();
+    let explicit_external_path = external_leader || attach_existing || attach_session.is_some();
+    let managed_client_attach_mode = (!explicit_external_path).then_some(if in_tmux {
+        ManagedClientAttachMode::SwitchClient
+    } else {
+        ManagedClientAttachMode::AttachSession
+    });
+    leader_start_plan_with_ambient_authority(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing,
+        confirm_attach,
+        attach_session,
+        external_leader,
+        in_tmux,
+        managed_client_attach_mode,
+        false,
+    )
+}
+
+fn leader_start_plan_with_ambient_authority(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+    external_leader: bool,
+    in_tmux: bool,
+    managed_client_attach_mode: Option<ManagedClientAttachMode>,
+    managed_provider_reentry: bool,
 ) -> Result<LeaderStartPlan, LeaderError> {
     if attach_session.is_some() && !confirm_attach {
         return Err(LeaderError::Start(
@@ -54,29 +221,29 @@ pub fn leader_start_plan(
     }
     let state = crate::state::persist::load_runtime_state(workspace).ok();
     let identity = leader_identity_context(workspace, None, state.as_ref())?;
-    let external_path = external_leader || attach_existing || attach_session.is_some();
+    let external_path = external_leader
+        || attach_existing
+        || attach_session.is_some()
+        || state
+            .as_ref()
+            .is_some_and(crate::state::projection::state_is_external_leader);
     // 0.3.28 Step 2: managed mode now uses the SAME dedicated leader session
     // as the external path (`team-agent-leader-<provider>-<folder>-<sha1[:8]>`)
     // — Python parity. Pre-0.3.28 the managed branch used
     // `managed_team_session_name(identity) = team-<team_id>` which is the
     // worker session — that co-location is the structural root of
     // E49/E51/E53/E57-3/E60.
-    // 0.4.10+ mirror-session fix v2 (option B): managed-mode session name
-    // gets a per-launch nonce so each `team-agent <provider>` entry in the
-    // same workspace creates its OWN tmux session — matching the user
-    // expectation that `tmux new-session + claude` is independent every
-    // time. Pre-fix the managed path used the workspace-keyed name (same
-    // session for every entry) and silently attached the second client →
-    // UI mirror. The external/attach paths keep the stable workspace-keyed
-    // name (per-launch nonce would break `--attach-session` reattach).
+    // A-22: managed mode reuses a live provider leader session by prefix;
+    // when no candidate exists, it falls back to a per-launch nonce. The
+    // external/attach paths keep the stable workspace-keyed name because a
+    // nonce would break `--attach-session` reattach.
     let session_name = if external_path {
         attach_session
             .cloned()
             .or_else(|| Some(leader_session_name(provider, workspace)))
     } else {
-        Some(managed_leader_session_name(provider, workspace))
+        Some(managed_leader_session_for_launch(provider, workspace))
     };
-    let in_tmux = std::env::var_os("TMUX").is_some();
     if !in_tmux {
         ensure_tmux_installed()?;
     }
@@ -89,7 +256,7 @@ pub fn leader_start_plan(
         } else {
             false
         };
-    let mode = if !external_path && in_tmux {
+    let mode = if managed_provider_reentry {
         LeaderStartMode::ExecProvider
     } else if !external_path {
         LeaderStartMode::ManagedTmuxClient
@@ -108,6 +275,7 @@ pub fn leader_start_plan(
         workspace,
         session_name.as_ref(),
         &leader_env,
+        managed_client_attach_mode,
     )?;
     let plan_session_name = if mode == LeaderStartMode::ExecProvider && !external_path {
         None
@@ -177,44 +345,21 @@ pub(crate) fn leader_env_for_identity(
     leader_env
 }
 
-/// `start_leader`(card §46;`__init__.py:60`)。计算并执行 leader 启动计划(spawn + 信号处理)。
-/// 进程退出后 `Err`/退出码经 caller 处理(此处返 `Result` 替代 Python 的 `SystemExit`)。
-pub fn start_leader(
-    provider: Provider,
-    provider_args: &[String],
+pub(crate) fn execute_prepared_leader_start(
+    prepared: &PreparedLeaderStart,
     workspace: &Path,
-    attach_existing: bool,
-    confirm_attach: bool,
-    attach_session: Option<&SessionName>,
-    external_leader: bool,
-) -> Result<(), LeaderError> {
-    let plan = leader_start_plan(
-        provider,
-        provider_args,
+) -> Result<LeaderLaunchOutcome, LeaderError> {
+    execute_leader_plan_after_ambient_authority(
+        &prepared.plan,
         workspace,
-        attach_existing,
-        confirm_attach,
-        attach_session,
-        external_leader,
-    )?;
-    crate::event_log::EventLog::new(workspace).write(
-        super::LeaderEvent::LeaderStart.name(),
-        serde_json::json!({
-            "provider": super::helpers::provider_wire(plan.provider),
-            "mode": serde_json::to_value(plan.mode)?,
-            "session_name": plan.session_name.as_ref().map(|s| s.as_str().to_string()),
-        }),
-    )?;
-    execute_leader_plan(&plan, workspace).map(|_| ())
+        prepared.ambient_authority.as_ref(),
+    )
 }
 
-/// Execute a precomputed leader launch plan.
-///
-/// S0 exposes the seam and return model only. Lane 2 owns the real provider/tmux
-/// execution and workspace-socket enforcement.
-pub fn execute_leader_plan(
+fn execute_leader_plan_after_ambient_authority(
     plan: &LeaderStartPlan,
     workspace: &Path,
+    ambient_authority: Option<&VerifiedAmbientPaneAuthority>,
 ) -> Result<LeaderLaunchOutcome, LeaderError> {
     if plan.mode == LeaderStartMode::ManagedTmuxClient {
         return execute_managed_leader_plan(plan, workspace);
@@ -223,21 +368,31 @@ pub fn execute_leader_plan(
     let detached = plan.mode == LeaderStartMode::NewTmuxSession
         && !std::io::stdin().is_terminal()
         && insert_detach_flag(&mut argv);
-    if plan.mode == LeaderStartMode::ExecProvider && !plan.is_external_leader {
+    let bind_verified_ambient = plan.mode == LeaderStartMode::ExecProvider
+        && (!plan.is_external_leader || workspace_state_uses_external_leader(workspace));
+    if bind_verified_ambient {
+        let authority = ambient_authority.ok_or_else(|| {
+            LeaderError::Validation("exec provider ambient pane authority missing".to_string())
+        })?;
         // 0.5.35 (`.team/artifacts/managed-leader-provider-reentry-locate.md`
         // §5/§6): three-way classify BEFORE persist. Same physical pane =
         // provider process replacement (refresh only). Different pane with
         // an existing canonical binding = no canonical rewrite (claim /
         // takeover is the recovery path, §7). Unbound = first-time write.
-        match classify_exec_provider_binding(workspace, plan)? {
+        match classify_exec_provider_binding(workspace, plan, authority)? {
             ExecProviderBinding::ManagedReentry => {
-                refresh_managed_leader_provider_binding(plan, workspace)?;
+                refresh_managed_leader_provider_binding(plan, workspace, authority)?;
             }
             ExecProviderBinding::DifferentPaneAlreadyBound => {
                 // No canonical state write. Provider still runs below.
             }
             ExecProviderBinding::Unbound => {
-                persist_exec_provider_leader_binding(plan, workspace)?;
+                persist_exec_provider_leader_binding(
+                    plan,
+                    workspace,
+                    authority,
+                    plan.is_external_leader,
+                )?;
             }
         }
     } else if plan.is_external_leader {
@@ -266,6 +421,402 @@ pub fn execute_leader_plan(
     }
 }
 
+struct VerifiedAmbientPaneAuthority {
+    pane_id: PaneId,
+    observed: PaneInfo,
+    endpoint: String,
+    tmux: String,
+}
+
+fn workspace_state_uses_external_leader(workspace: &Path) -> bool {
+    crate::state::persist::load_runtime_state_without_migrations(workspace)
+        .ok()
+        .as_ref()
+        .is_some_and(crate::state::projection::state_is_external_leader)
+}
+
+fn workspace_state_is_managed_provider_reentry(workspace: &Path) -> bool {
+    let Ok(state) = crate::state::persist::load_runtime_state_without_migrations(workspace) else {
+        return false;
+    };
+    if crate::state::projection::state_is_external_leader(&state) {
+        return false;
+    }
+    let Some(team_key) = state
+        .get("active_team_key")
+        .and_then(serde_json::Value::as_str)
+    else {
+        return false;
+    };
+    let Some(receiver) = state
+        .get("teams")
+        .and_then(serde_json::Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+        .and_then(|team| team.get("leader_receiver"))
+    else {
+        return false;
+    };
+    let Some(pane) = std::env::var_os("TMUX_PANE") else {
+        return false;
+    };
+    let Some(tmux) = std::env::var_os("TMUX") else {
+        return false;
+    };
+    let tmux = tmux.to_string_lossy();
+    let endpoint = tmux.split(',').next().unwrap_or("").trim();
+    receiver.get("status").and_then(serde_json::Value::as_str) == Some("attached")
+        && receiver.get("pane_id").and_then(serde_json::Value::as_str) == pane.to_str()
+        && receiver
+            .get("tmux_socket")
+            .and_then(serde_json::Value::as_str)
+            == Some(endpoint)
+        && receiver
+            .get("session_name")
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|session| session.starts_with(LEADER_SESSION_PREFIX))
+}
+
+fn ambient_pane_authority_preflight(
+    workspace: &Path,
+) -> Result<Option<VerifiedAmbientPaneAuthority>, PrepareLeaderStartError> {
+    let Some(tmux) = std::env::var_os("TMUX") else {
+        return Ok(None);
+    };
+    let tmux = tmux.into_string().map_err(|_| {
+        PrepareLeaderStartError::PaneAuthorityRefused(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::TmuxValueNotUnicode,
+        ))
+    })?;
+    verified_ambient_pane_authority(workspace, &tmux)
+        .map(Some)
+        .map_err(PrepareLeaderStartError::PaneAuthorityRefused)
+}
+
+fn managed_launcher_ambient_route(
+    workspace: &Path,
+    allow_nested_attach: bool,
+) -> Result<
+    (
+        Option<VerifiedAmbientPaneAuthority>,
+        Option<ManagedClientAttachMode>,
+    ),
+    PrepareLeaderStartError,
+> {
+    let Some(tmux) = std::env::var_os("TMUX") else {
+        return Ok((None, Some(ManagedClientAttachMode::AttachSession)));
+    };
+    let tmux = tmux.into_string().map_err(|_| {
+        PrepareLeaderStartError::PaneAuthorityRefused(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::TmuxValueNotUnicode,
+        ))
+    })?;
+    let observed_endpoint = validated_ambient_tmux_endpoint(workspace, &tmux)
+        .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
+    let target_socket_name = TmuxBackend::for_workspace(workspace)
+        .tmux_endpoint()
+        .ok_or_else(|| LeaderError::Start("workspace tmux endpoint missing".to_string()))?;
+    let target_endpoint = crate::tmux_backend::socket_path_for_workspace(workspace);
+    let same_server = target_endpoint.as_ref().is_some_and(|target| {
+        let observed = Path::new(&observed_endpoint)
+            .canonicalize()
+            .unwrap_or_else(|_| PathBuf::from(&observed_endpoint));
+        let target = target.canonicalize().unwrap_or_else(|_| target.clone());
+        observed == target
+    });
+    if same_server {
+        let authority = verified_ambient_pane_authority(workspace, &tmux)
+            .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
+        return Ok((Some(authority), Some(ManagedClientAttachMode::SwitchClient)));
+    }
+    if !allow_nested_attach {
+        return Err(LeaderError::Validation(format!(
+            "{DIFFERENT_TMUX_SERVER_PREFIX}: observed_endpoint={observed_endpoint}; \
+             requested_workspace_socket={target_socket_name}"
+        ))
+        .into());
+    }
+    let authority = verified_ambient_pane_authority(workspace, &tmux)
+        .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
+    Ok((
+        Some(authority),
+        Some(ManagedClientAttachMode::AttachSession),
+    ))
+}
+
+fn validated_ambient_tmux_endpoint(
+    workspace: &Path,
+    tmux: &str,
+) -> Result<String, pane_refusal::PaneAuthorityRefusal> {
+    let tuple = tmux.split(',').map(str::trim).collect::<Vec<_>>();
+    let [endpoint, server_pid, session_index] = tuple.as_slice() else {
+        return Err(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::TmuxTupleFieldCountInvalid,
+        ));
+    };
+    if endpoint.is_empty() {
+        return Err(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::EndpointMissing,
+        ));
+    }
+    if !Path::new(endpoint).is_absolute() {
+        return Err(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::EndpointNotAbsolute,
+        ));
+    }
+    if server_pid.parse::<u32>().is_err() {
+        return Err(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::ServerPidInvalid,
+        ));
+    }
+    if session_index.parse::<u32>().is_err() {
+        return Err(ambient_tmux_endpoint_refusal(
+            workspace,
+            pane_refusal::AmbientTmuxEndpointUnavailableCause::SessionIndexInvalid,
+        ));
+    }
+    Ok((*endpoint).to_string())
+}
+
+fn verified_ambient_pane_authority(
+    workspace: &Path,
+    tmux: &str,
+) -> Result<VerifiedAmbientPaneAuthority, pane_refusal::PaneAuthorityRefusal> {
+    let requested_workspace = resolve_workspace_for_hash(workspace);
+    let endpoint = validated_ambient_tmux_endpoint(workspace, tmux)?;
+    let pane_id = match std::env::var_os("TMUX_PANE") {
+        None => {
+            return Err(pane_refusal::PaneAuthorityRefusal::new(
+                pane_refusal::PaneAuthorityRefusalFacts::AmbientPaneIdUnavailable(
+                    pane_refusal::AmbientPaneIdUnavailableFacts {
+                        requested_workspace,
+                        observed_pane_id: pane_refusal::UnavailablePaneAuthorityFact::new(
+                            pane_refusal::AmbientPaneIdUnavailableCause::EnvironmentValueMissing,
+                        ),
+                        endpoint,
+                    },
+                ),
+            ));
+        }
+        Some(value) => match value.into_string() {
+            Ok(value) if value.trim().is_empty() => {
+                return Err(pane_refusal::PaneAuthorityRefusal::new(
+                    pane_refusal::PaneAuthorityRefusalFacts::AmbientPaneIdUnavailable(
+                        pane_refusal::AmbientPaneIdUnavailableFacts {
+                            requested_workspace,
+                            observed_pane_id: pane_refusal::UnavailablePaneAuthorityFact::new(
+                                pane_refusal::AmbientPaneIdUnavailableCause::EnvironmentValueEmpty,
+                            ),
+                            endpoint,
+                        },
+                    ),
+                ));
+            }
+            Ok(value) => PaneId::new(value.trim().to_string()),
+            Err(_) => {
+                return Err(pane_refusal::PaneAuthorityRefusal::new(
+                    pane_refusal::PaneAuthorityRefusalFacts::AmbientPaneIdUnavailable(
+                        pane_refusal::AmbientPaneIdUnavailableFacts {
+                            requested_workspace,
+                            observed_pane_id: pane_refusal::UnavailablePaneAuthorityFact::new(
+                                pane_refusal::AmbientPaneIdUnavailableCause::EnvironmentValueNotUnicode,
+                            ),
+                            endpoint,
+                        },
+                    ),
+                ));
+            }
+        },
+    };
+    let observed = current_tmux_pane_info(&pane_id, &endpoint).map_err(|error| {
+        let cause = match error {
+            CurrentTmuxPaneInfoError::QueryFailed => {
+                pane_refusal::AmbientPaneWorkspaceUnavailableCause::PaneQueryFailed
+            }
+            CurrentTmuxPaneInfoError::PaneNotFound => {
+                pane_refusal::AmbientPaneWorkspaceUnavailableCause::PaneNotFound
+            }
+        };
+        pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::AmbientPaneWorkspaceUnavailable(
+                pane_refusal::AmbientPaneWorkspaceUnavailableFacts {
+                    requested_workspace: requested_workspace.clone(),
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    observed_pane_workspace: pane_refusal::UnavailablePaneAuthorityFact::new(cause),
+                    endpoint: endpoint.clone(),
+                },
+            ),
+        )
+    })?;
+    let pane_workspace = observed.current_path.clone().ok_or_else(|| {
+        pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::AmbientPaneWorkspaceUnavailable(
+                pane_refusal::AmbientPaneWorkspaceUnavailableFacts {
+                    requested_workspace: requested_workspace.clone(),
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    observed_pane_workspace: pane_refusal::UnavailablePaneAuthorityFact::new(
+                        pane_refusal::AmbientPaneWorkspaceUnavailableCause::CurrentPathMissing,
+                    ),
+                    endpoint: endpoint.clone(),
+                },
+            ),
+        )
+    })?;
+    let caller_tty = caller_controlling_tty().map_err(|cause| {
+        pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::CallerControllingTtyUnavailable(
+                pane_refusal::CallerControllingTtyUnavailableFacts {
+                    requested_workspace: requested_workspace.clone(),
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    endpoint: endpoint.clone(),
+                    caller_controlling_tty: pane_refusal::UnavailablePaneAuthorityFact::new(cause),
+                },
+            ),
+        )
+    })?;
+    let pane_tty_path = observed.tty.as_deref().ok_or_else(|| {
+        pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::ObservedPaneTtyUnavailable(
+                pane_refusal::ObservedPaneTtyUnavailableFacts {
+                    requested_workspace: requested_workspace.clone(),
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    endpoint: endpoint.clone(),
+                    observed_pane_tty: pane_refusal::UnavailablePaneAuthorityFact::new(
+                        pane_refusal::ObservedPaneTtyUnavailableCause::PaneTtyMissing,
+                    ),
+                },
+            ),
+        )
+    })?;
+    let pane_tty = pane_tty_device(pane_tty_path).map_err(|cause| {
+        pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::ObservedPaneTtyUnavailable(
+                pane_refusal::ObservedPaneTtyUnavailableFacts {
+                    requested_workspace: requested_workspace.clone(),
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    endpoint: endpoint.clone(),
+                    observed_pane_tty: pane_refusal::UnavailablePaneAuthorityFact::new(cause),
+                },
+            ),
+        )
+    })?;
+    if caller_tty != pane_tty {
+        return Err(pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::PaneTtyMismatch(
+                pane_refusal::PaneTtyMismatchFacts {
+                    requested_workspace,
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    endpoint,
+                    caller_controlling_tty: caller_tty,
+                    observed_pane_tty: pane_tty,
+                },
+            ),
+        ));
+    }
+    if !crate::messaging::leader_channel::path_is_in_workspace(&pane_workspace, workspace) {
+        return Err(pane_refusal::PaneAuthorityRefusal::new(
+            pane_refusal::PaneAuthorityRefusalFacts::PaneWorkspaceMismatch(
+                pane_refusal::PaneWorkspaceMismatchFacts {
+                    requested_workspace,
+                    observed_pane_id: pane_id.as_str().to_string(),
+                    observed_pane_workspace: pane_workspace,
+                    endpoint,
+                },
+            ),
+        ));
+    }
+    Ok(VerifiedAmbientPaneAuthority {
+        pane_id,
+        observed,
+        endpoint,
+        tmux: tmux.to_string(),
+    })
+}
+
+fn ambient_tmux_endpoint_refusal(
+    workspace: &Path,
+    cause: pane_refusal::AmbientTmuxEndpointUnavailableCause,
+) -> pane_refusal::PaneAuthorityRefusal {
+    pane_refusal::PaneAuthorityRefusal::new(
+        pane_refusal::PaneAuthorityRefusalFacts::AmbientTmuxEndpointUnavailable(
+            pane_refusal::AmbientTmuxEndpointUnavailableFacts {
+                requested_workspace: resolve_workspace_for_hash(workspace),
+                endpoint: pane_refusal::UnavailablePaneAuthorityFact::new(cause),
+            },
+        ),
+    )
+}
+
+#[cfg(target_os = "macos")]
+fn caller_controlling_tty() -> Result<u64, pane_refusal::CallerControllingTtyUnavailableCause> {
+    // `/dev/tty` proves that this process has a controlling terminal, but its
+    // own path and rdev remain the generic alias. Query the process table for
+    // the actual controlling device identity.
+    let _controlling_tty = std::fs::File::open("/dev/tty")
+        .map_err(|_| pane_refusal::CallerControllingTtyUnavailableCause::NoControllingTty)?;
+    let mut info = std::mem::MaybeUninit::<libc::proc_bsdinfo>::zeroed();
+    let info_size = std::mem::size_of::<libc::proc_bsdinfo>();
+    let read = unsafe {
+        libc::proc_pidinfo(
+            libc::getpid(),
+            libc::PROC_PIDTBSDINFO,
+            0,
+            info.as_mut_ptr().cast(),
+            info_size as libc::c_int,
+        )
+    };
+    if read != info_size as libc::c_int {
+        return Err(pane_refusal::CallerControllingTtyUnavailableCause::DeviceIdentityUnresolvable);
+    }
+    Ok(u64::from(unsafe { info.assume_init() }.e_tdev))
+}
+
+#[cfg(target_os = "linux")]
+fn caller_controlling_tty() -> Result<u64, pane_refusal::CallerControllingTtyUnavailableCause> {
+    let controlling_tty = std::fs::OpenOptions::new()
+        .read(true)
+        .custom_flags(libc::O_NOCTTY | libc::O_CLOEXEC)
+        .open("/dev/tty")
+        .map_err(|_| pane_refusal::CallerControllingTtyUnavailableCause::NoControllingTty)?;
+    let mut device = 0 as libc::c_uint;
+    let result = unsafe { libc::ioctl(controlling_tty.as_raw_fd(), libc::TIOCGDEV, &mut device) };
+    if result != 0 {
+        return Err(pane_refusal::CallerControllingTtyUnavailableCause::DeviceIdentityUnresolvable);
+    }
+    Ok(u64::from(device))
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux")))]
+fn caller_controlling_tty() -> Result<u64, pane_refusal::CallerControllingTtyUnavailableCause> {
+    Err(pane_refusal::CallerControllingTtyUnavailableCause::PlatformUnsupported)
+}
+
+#[cfg(unix)]
+fn pane_tty_device(path: &str) -> Result<u64, pane_refusal::ObservedPaneTtyUnavailableCause> {
+    let pane_tty = std::fs::OpenOptions::new()
+        .read(true)
+        .custom_flags(libc::O_NOCTTY | libc::O_CLOEXEC)
+        .open(path)
+        .map_err(|_| pane_refusal::ObservedPaneTtyUnavailableCause::PaneTtyUnresolvable)?;
+    let metadata = pane_tty
+        .metadata()
+        .map_err(|_| pane_refusal::ObservedPaneTtyUnavailableCause::PaneTtyUnresolvable)?;
+    if !metadata.file_type().is_char_device() {
+        return Err(pane_refusal::ObservedPaneTtyUnavailableCause::PaneTtyNotCharacterDevice);
+    }
+    Ok(metadata.rdev())
+}
+
+#[cfg(not(unix))]
+fn pane_tty_device(_path: &str) -> Result<u64, pane_refusal::ObservedPaneTtyUnavailableCause> {
+    Err(pane_refusal::ObservedPaneTtyUnavailableCause::PaneTtyUnresolvable)
+}
+
 /// B5: the deterministic leader-session naming prefix IS the ownership truth source —
 /// shutdown's socket teardown spares sessions carrying it (no separate registry).
 pub const LEADER_SESSION_PREFIX: &str = "team-agent-leader-";
@@ -303,7 +854,7 @@ pub fn leader_session_name(provider: Provider, workspace: &Path) -> SessionName
 /// External / attach paths keep the stable `leader_session_name` —
 /// per-launch nonce would break `--attach-session <name>` reattach
 /// semantics.
-pub fn managed_leader_session_name(provider: Provider, workspace: &Path) -> SessionName {
+fn managed_leader_session_name(provider: Provider, workspace: &Path) -> SessionName {
     let resolved = resolve_workspace_for_hash(workspace);
     let folder_raw = resolved
         .file_name()
@@ -322,6 +873,32 @@ pub fn managed_leader_session_name(provider: Provider, workspace: &Path) -> Sess
     ))
 }
 
+fn managed_leader_session_for_launch(provider: Provider, workspace: &Path) -> SessionName {
+    let candidates = crate::transport_factory::tmux_workspace_transport(workspace)
+        .list_targets()
+        .unwrap_or_default()
+        .into_iter()
+        .map(|target| target.session.as_str().to_string());
+    managed_leader_session_from_candidates(provider, workspace, candidates)
+}
+
+fn managed_leader_session_from_candidates(
+    provider: Provider,
+    workspace: &Path,
+    candidates: impl IntoIterator<Item = String>,
+) -> SessionName {
+    let prefix = format!("{LEADER_SESSION_PREFIX}{}-", provider_wire(provider));
+    let existing = candidates
+        .into_iter()
+        .filter(|name| name.starts_with(&prefix))
+        .collect::<std::collections::BTreeSet<_>>();
+    existing
+        .into_iter()
+        .next()
+        .map(SessionName::new)
+        .unwrap_or_else(|| managed_leader_session_name(provider, workspace))
+}
+
 fn start_argv(
     mode: LeaderStartMode,
     provider: Provider,
@@ -329,6 +906,7 @@ fn start_argv(
     workspace: &Path,
     session_name: Option<&SessionName>,
     leader_env: &BTreeMap<String, String>,
+    managed_client_attach_mode: Option<ManagedClientAttachMode>,
 ) -> Result<Vec<String>, LeaderError> {
     let provider_cmd = provider_command_name(provider).to_string();
     match mode {
@@ -343,7 +921,10 @@ fn start_argv(
                     "managed leader session missing".to_string(),
                 ));
             };
-            managed_client_argv(workspace, session, provider)
+            let attach_mode = managed_client_attach_mode.ok_or_else(|| {
+                LeaderError::Start("managed client attach mode missing".to_string())
+            })?;
+            managed_client_argv(workspace, session, provider, attach_mode)
         }
         LeaderStartMode::AttachExisting => {
             let Some(session) = session_name else {
@@ -407,35 +988,34 @@ fn normalized_provider_args(provider_args: &[String]) -> impl Iterator<Item = St
         .cloned()
 }
 
-// 0.3.28 Step 2: `managed_team_session_name` deleted. Both managed and
-// external paths now compute the dedicated leader session via
-// `leader_session_name(provider, workspace)` directly. The old function
-// returned `team-<team_id>` which is the WORKER session — the structural
-// root of E49/E51/E53/E57-3/E60.
+// 0.3.28 Step 2: `managed_team_session_name` deleted. Both paths use the
+// dedicated leader-session namespace; managed launches select a live prefix
+// candidate before falling back to the nonce helper, while external/attach
+// launches use the stable `leader_session_name`.
 
 fn managed_client_argv(
     workspace: &Path,
     session: &SessionName,
     provider: Provider,
+    attach_mode: ManagedClientAttachMode,
 ) -> Result<Vec<String>, LeaderError> {
     // 0.3.28 Step 2: leader window inside the dedicated leader session is
     // named after `provider_wire(provider)` (e.g. `claude`, `codex`, `fake`),
     // never the literal `leader`. Pre-0.3.28 this hardcoded `:leader`.
     let target = format!("{}:{}", session.as_str(), provider_wire(provider));
-    let argv = if std::env::var_os("TMUX").is_some() {
-        vec![
+    let argv = match attach_mode {
+        ManagedClientAttachMode::SwitchClient => vec![
             "tmux".to_string(),
             "switch-client".to_string(),
             "-t".to_string(),
             target,
-        ]
-    } else {
-        vec![
+        ],
+        ManagedClientAttachMode::AttachSession => vec![
             "tmux".to_string(),
             "attach-session".to_string(),
             "-t".to_string(),
             target,
-        ]
+        ],
     };
     Ok(TmuxBackend::argv_for_workspace(workspace, &argv))
 }
@@ -443,6 +1023,14 @@ fn managed_client_argv(
 fn execute_managed_leader_plan(
     plan: &LeaderStartPlan,
     workspace: &Path,
+) -> Result<LeaderLaunchOutcome, LeaderError> {
+    execute_managed_leader_plan_attempt(plan, workspace, true)
+}
+
+fn execute_managed_leader_plan_attempt(
+    plan: &LeaderStartPlan,
+    workspace: &Path,
+    allow_attach_recovery: bool,
 ) -> Result<LeaderLaunchOutcome, LeaderError> {
     let Some(session) = plan.session_name.as_ref() else {
         return Err(LeaderError::Start(
@@ -460,19 +1048,76 @@ fn execute_managed_leader_plan(
     // site. Semantics unchanged; managed leader hosting stays
     // tmux-only per design §Batch 6.
     let transport = crate::transport_factory::tmux_workspace_transport(workspace);
-    let spawned = ensure_managed_leader_pane(&transport, session, window, plan, workspace)?;
-    persist_managed_leader_binding(plan, workspace, &spawned)?;
+    let session_existed_before = transport.has_session(session).map_err(|error| {
+        LeaderError::Start(format!("managed leader session probe failed: {error}"))
+    })?;
+    let spawned = ensure_managed_leader_pane(
+        &transport,
+        session,
+        window,
+        plan,
+        workspace,
+        session_existed_before,
+    )?;
+    if let Err(error) = persist_managed_leader_binding(plan, workspace, &spawned) {
+        cleanup_managed_leader_resources(
+            &transport,
+            session,
+            &spawned,
+            session_existed_before,
+            workspace,
+            "binding_persist_failed",
+        );
+        return Err(error);
+    }
     spawn_managed_provider_startup_prompt_handler(
         plan.provider,
         workspace.to_path_buf(),
         spawned.pane_id.as_str().to_string(),
     );
-    let process = run_leader_argv(&plan.argv, &BTreeMap::new(), plan, workspace)?;
+    let process = match run_leader_argv(&plan.argv, &BTreeMap::new(), plan, workspace) {
+        Ok(process) => process,
+        Err(error) => {
+            cleanup_managed_leader_resources(
+                &transport,
+                session,
+                &spawned,
+                session_existed_before,
+                workspace,
+                "launcher_spawn_failed",
+            );
+            return Err(error);
+        }
+    };
     let code = process.status.code();
     if !process.status.success() {
-        return Err(LeaderError::Start(leader_launcher_failure(&process)));
+        cleanup_managed_leader_resources(
+            &transport,
+            session,
+            &spawned,
+            session_existed_before,
+            workspace,
+            "launcher_exit_failed",
+        );
+        let failure = LeaderError::Start(leader_launcher_failure(&process));
+        if allow_attach_recovery {
+            if let Ok(retry_plan) = managed_leader_attach_recovery_plan(plan, workspace) {
+                return execute_managed_leader_plan_attempt(&retry_plan, workspace, false);
+            }
+        }
+        return Err(failure);
+    }
+    if let Err(error) = ensure_managed_provider_live_after_attach(&transport, &spawned) {
+        cleanup_managed_leader_resources(
+            &transport,
+            session,
+            &spawned,
+            session_existed_before,
+            workspace,
+            "provider_not_live_after_attach",
+        );
+        return Err(error);
     }
-    ensure_managed_provider_live_after_attach(&transport, &spawned)?;
     Ok(LeaderLaunchOutcome {
         status: LeaderLaunchStatus::Exited,
         exit_code: code,
@@ -481,21 +1126,36 @@ fn execute_managed_leader_plan(
     })
 }
 
+fn managed_leader_attach_recovery_plan(
+    plan: &LeaderStartPlan,
+    workspace: &Path,
+) -> Result<LeaderStartPlan, LeaderError> {
+    let session = managed_leader_session_for_launch(plan.provider, workspace);
+    let attach_mode = if plan.argv.iter().any(|arg| arg == "switch-client") {
+        ManagedClientAttachMode::SwitchClient
+    } else {
+        ManagedClientAttachMode::AttachSession
+    };
+    let argv = managed_client_argv(workspace, &session, plan.provider, attach_mode)?;
+    let mut retry_plan = plan.clone();
+    retry_plan.session_name = Some(session);
+    retry_plan.argv = argv;
+    Ok(retry_plan)
+}
+
 fn ensure_managed_leader_pane(
     transport: &dyn Transport,
     session: &SessionName,
     window: &WindowName,
     plan: &LeaderStartPlan,
     workspace: &Path,
+    session_existed_before: bool,
 ) -> Result<SpawnResult, LeaderError> {
-    // 0.4.10+ mirror-session fix v2 (option B): each managed launch gets
-    // its OWN session name (via `managed_leader_session_name`'s nonce).
-    // The historical "session already exists → reuse pane" branch is
-    // structurally unreachable now (the per-launch session never
-    // preexists). If a caller bypasses the nonce path and reuses a name,
-    // tmux's own duplicate-session error will surface — better than
-    // silently attaching a second client.
-    if transport.has_session(session).unwrap_or(false) {
+    // A-22: a managed launch may reuse an existing provider leader session;
+    // only a newly selected nonce session is absent before this probe.
+    // Reusing the existing session adds one pane; a new session uses the
+    // first-spawn path.
+    if session_existed_before {
         // 0.4.x (CR C-1 + C-2): leader env_unset reuses the worker
         // provider_env_unsets (single source of truth) + spawn through the
         // leader shell wrapper so provider exit returns to a shell, not
@@ -530,6 +1190,45 @@ fn ensure_managed_leader_pane(
     }
 }
 
+fn cleanup_managed_leader_resources(
+    transport: &dyn Transport,
+    session: &SessionName,
+    spawned: &SpawnResult,
+    session_existed_before: bool,
+    workspace: &Path,
+    reason: &str,
+) {
+    let (action, result) = if session_existed_before {
+        (
+            "kill_pane",
+            transport
+                .kill_pane(&spawned.pane_id)
+                .map(|_| "ok".to_string())
+                .unwrap_or_else(|error| error.to_string()),
+        )
+    } else {
+        (
+            "kill_session",
+            transport
+                .kill_session(session)
+                .map(|_| "ok".to_string())
+                .unwrap_or_else(|error| error.to_string()),
+        )
+    };
+    write_leader_startup_prompt_event(
+        workspace,
+        "leader.launcher.rollback",
+        serde_json::json!({
+            "reason": reason,
+            "session": session.as_str(),
+            "pane_id": spawned.pane_id.as_str(),
+            "session_preexisted": session_existed_before,
+            "action": action,
+            "result": result,
+        }),
+    );
+}
+
 /// 0.4.x (CR C-1): leader provider env-unset list — SINGLE SOURCE OF TRUTH
 /// reused from worker spawn (`profile_launch::provider_env_unsets`).
 /// Audit grep guard: this function MUST be the only place in
@@ -538,7 +1237,7 @@ fn ensure_managed_leader_pane(
 /// or the underlying `provider_env_unsets`. Use `AuthMode::Subscription` —
 /// the leader is the user's interactive provider, never CompatibleApi/
 /// OfficialApi which are worker-only auth modes today.
-pub fn leader_env_unset_for_provider(provider: Provider) -> Vec<String> {
+fn leader_env_unset_for_provider(provider: Provider) -> Vec<String> {
     crate::lifecycle::profile_launch::provider_env_unsets(
         provider,
         crate::model::enums::AuthMode::Subscription,
@@ -652,7 +1351,7 @@ pub enum LeaderProviderHealth {
 /// common interactive shells; missing entries here are false negatives
 /// (shell looks like provider absent → health says Alive) which is the
 /// safe default per the CR R6 conservative-Alive rule.
-pub fn is_interactive_shell_basename(name: &str) -> bool {
+fn is_interactive_shell_basename(name: &str) -> bool {
     let trimmed = name.trim().to_ascii_lowercase();
     let basename = std::path::Path::new(&trimmed)
         .file_name()
@@ -721,6 +1420,11 @@ fn persist_managed_leader_binding(
     let session = spawned.session.as_str().to_string();
     let window = spawned.window.as_str().to_string();
     let pane = spawned.pane_id.as_str().to_string();
+    let attach_mode = if plan.argv.iter().any(|arg| arg == "switch-client") {
+        "switch-client"
+    } else {
+        "attach-session"
+    };
     let receiver = serde_json::json!({
         "mode": "direct_tmux",
         "status": "attached",
@@ -783,7 +1487,7 @@ fn persist_managed_leader_binding(
             "leader_client".to_string(),
             serde_json::json!({
                 "diagnostic_only": true,
-                "attach_mode": if std::env::var_os("TMUX").is_some() { "switch-client" } else { "attach-session" },
+                "attach_mode": attach_mode,
                 "tmux": std::env::var("TMUX").ok(),
             }),
         );
@@ -821,17 +1525,15 @@ fn persist_managed_leader_binding(
 fn persist_exec_provider_leader_binding(
     plan: &LeaderStartPlan,
     workspace: &Path,
+    authority: &VerifiedAmbientPaneAuthority,
+    is_external_leader: bool,
 ) -> Result<(), LeaderError> {
     let identity = plan
         .identity
         .as_ref()
         .ok_or_else(|| LeaderError::Start("exec provider leader identity missing".to_string()))?;
-    let pane = std::env::var("TMUX_PANE")
-        .ok()
-        .filter(|value| !value.trim().is_empty())
-        .ok_or_else(|| LeaderError::Start("exec provider leader pane missing".to_string()))?;
-    let pane_id = PaneId::new(pane.clone());
-    let target = current_tmux_pane_info(&pane_id);
+    let pane = authority.pane_id.as_str();
+    let target = &authority.observed;
     let mut state = crate::state::persist::load_runtime_state(workspace)
         .unwrap_or_else(|_| serde_json::json!({}));
     let owner_epoch = state
@@ -846,7 +1548,7 @@ fn persist_exec_provider_leader_binding(
         .unwrap_or(0)
         .saturating_add(1);
     let now = chrono::Utc::now().to_rfc3339();
-    let socket = crate::tmux_backend::socket_name_from_tmux_env();
+    let socket = authority.endpoint.as_str();
     let provider = serde_json::to_value(plan.provider)?;
     let mut receiver = serde_json::json!({
         "mode": "direct_tmux",
@@ -859,24 +1561,18 @@ fn persist_exec_provider_leader_binding(
         "attached_at": now,
         "discovery": "current_pane",
     });
-    if let Some(target) = target.as_ref() {
-        if let Some(obj) = receiver.as_object_mut() {
+    if let Some(obj) = receiver.as_object_mut() {
+        obj.insert(
+            "session_name".to_string(),
+            serde_json::json!(target.session.as_str()),
+        );
+        if let Some(window_name) = target.window_name.as_ref() {
             obj.insert(
-                "session_name".to_string(),
-                serde_json::json!(target.session.as_str()),
+                "window_name".to_string(),
+                serde_json::json!(window_name.as_str()),
             );
-            if let Some(window_name) = target.window_name.as_ref() {
-                obj.insert(
-                    "window_name".to_string(),
-                    serde_json::json!(window_name.as_str()),
-                );
-            }
-        }
-    }
-    if let Some(socket) = socket.as_ref() {
-        if let Some(obj) = receiver.as_object_mut() {
-            obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
         }
+        obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
     }
     let owner = serde_json::json!({
         "pane_id": pane,
@@ -893,23 +1589,22 @@ fn persist_exec_provider_leader_binding(
             "active_team_key".to_string(),
             serde_json::json!(identity.team_id.as_str()),
         );
-        if let Some(target) = target.as_ref() {
-            obj.insert(
-                "session_name".to_string(),
-                serde_json::json!(target.session.as_str()),
-            );
-        }
-        if let Some(socket) = socket.as_ref() {
-            obj.insert("tmux_endpoint".to_string(), serde_json::json!(socket));
-            obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
-        }
-        obj.insert("is_external_leader".to_string(), serde_json::json!(false));
+        obj.insert(
+            "session_name".to_string(),
+            serde_json::json!(target.session.as_str()),
+        );
+        obj.insert("tmux_endpoint".to_string(), serde_json::json!(socket));
+        obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
+        obj.insert(
+            "is_external_leader".to_string(),
+            serde_json::json!(is_external_leader),
+        );
         obj.insert(
             "leader_client".to_string(),
             serde_json::json!({
                 "diagnostic_only": true,
                 "attach_mode": "exec-provider",
-                "tmux": std::env::var("TMUX").ok(),
+                "tmux": authority.tmux.as_str(),
             }),
         );
     }
@@ -954,13 +1649,9 @@ enum ExecProviderBinding {
 fn classify_exec_provider_binding(
     workspace: &Path,
     plan: &LeaderStartPlan,
+    authority: &VerifiedAmbientPaneAuthority,
 ) -> Result<ExecProviderBinding, LeaderError> {
-    let Some(pane) = std::env::var("TMUX_PANE")
-        .ok()
-        .filter(|value| !value.trim().is_empty())
-    else {
-        return Ok(ExecProviderBinding::Unbound);
-    };
+    let pane = authority.pane_id.as_str();
     let state = match crate::state::persist::load_runtime_state(workspace) {
         Ok(state) => state,
         Err(_) => return Ok(ExecProviderBinding::Unbound),
@@ -996,12 +1687,11 @@ fn classify_exec_provider_binding(
     if receiver_pane != pane {
         return Ok(ExecProviderBinding::DifferentPaneAlreadyBound);
     }
-    let pane_id = PaneId::new(pane.clone());
-    let target = current_tmux_pane_info(&pane_id);
-    let leader_prefixed_session = target
-        .as_ref()
-        .map(|t| t.session.as_str().starts_with(LEADER_SESSION_PREFIX))
-        .unwrap_or(false);
+    let leader_prefixed_session = authority
+        .observed
+        .session
+        .as_str()
+        .starts_with(LEADER_SESSION_PREFIX);
     if !leader_prefixed_session {
         return Ok(ExecProviderBinding::DifferentPaneAlreadyBound);
     }
@@ -1010,8 +1700,7 @@ fn classify_exec_provider_binding(
         .and_then(serde_json::Value::as_str)
         .filter(|s| !s.is_empty());
     if let Some(recorded_socket) = recorded_socket {
-        let caller_socket = crate::tmux_backend::socket_name_from_tmux_env();
-        if caller_socket.as_deref() != Some(recorded_socket) {
+        if authority.endpoint != recorded_socket {
             return Ok(ExecProviderBinding::DifferentPaneAlreadyBound);
         }
     }
@@ -1027,16 +1716,13 @@ fn classify_exec_provider_binding(
 fn refresh_managed_leader_provider_binding(
     plan: &LeaderStartPlan,
     workspace: &Path,
+    authority: &VerifiedAmbientPaneAuthority,
 ) -> Result<(), LeaderError> {
     let identity = plan.identity.as_ref().ok_or_else(|| {
         LeaderError::Start("managed leader re-entry identity missing".to_string())
     })?;
-    let pane = std::env::var("TMUX_PANE")
-        .ok()
-        .filter(|value| !value.trim().is_empty())
-        .ok_or_else(|| LeaderError::Start("managed leader re-entry pane missing".to_string()))?;
-    let pane_id = PaneId::new(pane.clone());
-    let target = current_tmux_pane_info(&pane_id);
+    let pane = authority.pane_id.as_str();
+    let target = &authority.observed;
     let mut state = crate::state::persist::load_runtime_state(workspace)
         .unwrap_or_else(|_| serde_json::json!({}));
     let team_key = identity.team_id.as_str();
@@ -1078,20 +1764,18 @@ fn refresh_managed_leader_provider_binding(
         obj.insert("owner_epoch".to_string(), serde_json::json!(existing_epoch));
         obj.entry("leader_session_uuid".to_string())
             .or_insert_with(|| serde_json::json!(identity.leader_session_uuid.as_str()));
-        if let Some(target) = target.as_ref() {
+        obj.insert(
+            "session_name".to_string(),
+            serde_json::json!(target.session.as_str()),
+        );
+        if let Some(window_name) = target.window_name.as_ref() {
             obj.insert(
-                "session_name".to_string(),
-                serde_json::json!(target.session.as_str()),
+                "window_name".to_string(),
+                serde_json::json!(window_name.as_str()),
             );
-            if let Some(window_name) = target.window_name.as_ref() {
-                obj.insert(
-                    "window_name".to_string(),
-                    serde_json::json!(window_name.as_str()),
-                );
-            }
-            if let Some(pane_pid) = target.pane_pid {
-                obj.insert("pane_pid".to_string(), serde_json::json!(pane_pid));
-            }
+        }
+        if let Some(pane_pid) = target.pane_pid {
+            obj.insert("pane_pid".to_string(), serde_json::json!(pane_pid));
         }
     }
     let mut owner = match existing_owner.as_object() {
@@ -1118,7 +1802,7 @@ fn refresh_managed_leader_provider_binding(
             serde_json::json!({
                 "diagnostic_only": true,
                 "attach_mode": "exec-provider",
-                "tmux": std::env::var("TMUX").ok(),
+                "tmux": authority.tmux.as_str(),
                 "reentry": true,
             }),
         );
@@ -1138,12 +1822,21 @@ fn refresh_managed_leader_provider_binding(
     Ok(())
 }
 
-fn current_tmux_pane_info(pane_id: &PaneId) -> Option<crate::transport::PaneInfo> {
-    tmux_transport_for_current_pane()
+enum CurrentTmuxPaneInfoError {
+    QueryFailed,
+    PaneNotFound,
+}
+
+fn current_tmux_pane_info(
+    pane_id: &PaneId,
+    endpoint: &str,
+) -> Result<crate::transport::PaneInfo, CurrentTmuxPaneInfoError> {
+    crate::transport_factory::tmux_endpoint_transport(endpoint)
         .list_targets()
-        .ok()?
+        .map_err(|_| CurrentTmuxPaneInfoError::QueryFailed)?
         .into_iter()
         .find(|target| target.pane_id == *pane_id)
+        .ok_or(CurrentTmuxPaneInfoError::PaneNotFound)
 }
 
 fn persist_external_leader_topology_marker(
@@ -1211,6 +1904,13 @@ fn run_leader_argv(
             "leader launch argv is empty".to_string(),
         ));
     };
+    let diagnostics_path = launcher_diagnostics_path(workspace);
+    if let Err(error) = write_launcher_diagnostics_header(&diagnostics_path, plan, argv) {
+        return Err(LeaderError::Start(format!(
+            "leader launcher diagnostics unavailable; startup_stage=diagnostics_create; launcher_diagnostics={}; error={error}",
+            diagnostics_path.display()
+        )));
+    }
     // 0.4.x regression fix (env-leak scenario 1, in-tmux ExecProvider path):
     // the managed-tmux path got the provider env-unset block via the shell
     // wrapper (cb9c217), but the ExecProvider in-tmux path here is a direct
@@ -1223,11 +1923,15 @@ fn run_leader_argv(
     // leader_env_unset_for_provider).
     let env_unset = leader_env_unset_for_provider(plan.provider);
     let mut command = Command::new(program);
-    command
-        .args(argv.iter().skip(1))
-        .stdin(Stdio::inherit())
-        .stdout(Stdio::inherit());
-    let capture_stderr = plan.mode != LeaderStartMode::ExecProvider;
+    command.args(argv.iter().skip(1)).stdin(Stdio::inherit());
+    let capture_stdout = !std::io::stdout().is_terminal();
+    command.stdout(if capture_stdout {
+        Stdio::piped()
+    } else {
+        Stdio::inherit()
+    });
+    let capture_stderr =
+        plan.mode != LeaderStartMode::ExecProvider || !std::io::stderr().is_terminal();
     command.stderr(if capture_stderr {
         Stdio::piped()
     } else {
@@ -1244,7 +1948,41 @@ fn run_leader_argv(
     for key in &env_unset {
         command.env_remove(key);
     }
-    let mut child = command.spawn()?;
+    if plan.mode == LeaderStartMode::ManagedTmuxClient
+        && argv.iter().any(|arg| arg == "attach-session")
+    {
+        command.env_remove("TMUX");
+        command.env_remove("TMUX_PANE");
+    }
+    let mut child = command.spawn().map_err(|error| {
+        LeaderError::Start(format!(
+            "leader launcher spawn failed; startup_stage=spawn; launcher_diagnostics={}; error={error}",
+            diagnostics_path.display()
+        ))
+    })?;
+    append_launcher_diagnostics(&diagnostics_path, "startup_stage=spawned\n").map_err(|error| {
+        LeaderError::Start(format!(
+            "leader launcher diagnostics write failed; startup_stage=spawned; launcher_diagnostics={}; error={error}",
+            diagnostics_path.display()
+        ))
+    })?;
+    let stdout_reader = child.stdout.take().map(|mut child_stdout| {
+        std::thread::spawn(move || {
+            let mut captured = Vec::new();
+            let mut buf = [0_u8; 4096];
+            loop {
+                let Ok(read) = child_stdout.read(&mut buf) else {
+                    break;
+                };
+                if read == 0 {
+                    break;
+                }
+                let _ = std::io::stdout().write_all(&buf[..read]);
+                captured.extend_from_slice(&buf[..read]);
+            }
+            captured
+        })
+    });
     let stderr_reader = child.stderr.take().map(|mut child_stderr| {
         std::thread::spawn(move || {
             let mut captured = Vec::new();
@@ -1257,7 +1995,7 @@ fn run_leader_argv(
                     break;
                 }
                 let _ = std::io::stderr().write_all(&buf[..read]);
-                push_bounded_stderr(&mut captured, &buf[..read]);
+                captured.extend_from_slice(&buf[..read]);
             }
             captured
         })
@@ -1266,6 +2004,13 @@ fn run_leader_argv(
         spawn_exec_provider_startup_prompt_handler(plan.provider, workspace.to_path_buf());
     }
     let status = child.wait().map_err(LeaderError::Io)?;
+    let stdout = match stdout_reader {
+        Some(reader) => match reader.join() {
+            Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
+            Err(_) => String::new(),
+        },
+        None => String::new(),
+    };
     let stderr = match stderr_reader {
         Some(reader) => match reader.join() {
             Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
@@ -1273,7 +2018,62 @@ fn run_leader_argv(
         },
         None => String::new(),
     };
-    Ok(LeaderProcessExit { status, stderr })
+    append_launcher_diagnostics(
+        &diagnostics_path,
+        &format!(
+            "startup_stage=exited\nexit_code={}\nchild_stdout={}\nchild_stderr={}\n",
+            status
+                .code()
+                .map(|code| code.to_string())
+                .unwrap_or_else(|| "signal".to_string()),
+            crate::redaction::redact_external_text(&stdout),
+            crate::redaction::redact_external_text(&stderr),
+        ),
+    )
+    .map_err(|error| {
+        LeaderError::Start(format!(
+            "leader launcher diagnostics write failed; startup_stage=exited; launcher_diagnostics={}; error={error}",
+            diagnostics_path.display()
+        ))
+    })?;
+    Ok(LeaderProcessExit {
+        status,
+        stderr,
+        diagnostics_path,
+    })
+}
+
+fn launcher_diagnostics_path(workspace: &Path) -> PathBuf {
+    let stamp = chrono::Utc::now().format("%Y%m%d-%H%M%S%.6f");
+    workspace.join(".team").join("logs").join(format!(
+        "launcher-diagnostics-{stamp}-{}.log",
+        std::process::id()
+    ))
+}
+
+fn write_launcher_diagnostics_header(
+    path: &Path,
+    plan: &LeaderStartPlan,
+    argv: &[String],
+) -> Result<(), std::io::Error> {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    std::fs::write(
+        path,
+        format!(
+            "startup_stage=prepare\nmode={:?}\nprovider={}\nargv={}\n",
+            plan.mode,
+            provider_wire(plan.provider),
+            crate::redaction::redact_external_text(&argv.join(" ")),
+        ),
+    )
+}
+
+fn append_launcher_diagnostics(path: &Path, text: &str) -> Result<(), std::io::Error> {
+    use std::io::Write as _;
+    let mut file = std::fs::OpenOptions::new().append(true).open(path)?;
+    file.write_all(text.as_bytes())
 }
 
 const LEADER_STDERR_LIMIT: usize = 8192;
@@ -1281,6 +2081,7 @@ const LEADER_STDERR_LIMIT: usize = 8192;
 struct LeaderProcessExit {
     status: std::process::ExitStatus,
     stderr: String,
+    diagnostics_path: PathBuf,
 }
 
 fn push_bounded_stderr(captured: &mut Vec<u8>, chunk: &[u8]) {
@@ -1305,7 +2106,11 @@ fn leader_launcher_failure(process: &LeaderProcessExit) -> String {
         .code()
         .map(|code| code.to_string())
         .unwrap_or_else(|| "signal".to_string());
-    format_launcher_failure(&status, process.status.code().is_none(), &process.stderr)
+    format!(
+        "{}; startup_stage=exited; launcher_diagnostics={}",
+        format_launcher_failure(&status, process.status.code().is_none(), &process.stderr),
+        process.diagnostics_path.display()
+    )
 }
 
 fn format_launcher_failure(status: &str, signaled: bool, raw_stderr: &str) -> String {
@@ -1399,7 +2204,7 @@ fn tmux_transport_for_current_pane() -> TmuxBackend {
         .unwrap_or_else(crate::transport_factory::tmux_default_transport)
 }
 
-pub fn handle_exec_provider_startup_prompts(
+fn handle_exec_provider_startup_prompts(
     provider: Provider,
     workspace: &Path,
     pane_id: &str,
@@ -1543,9 +2348,10 @@ mod tests {
     };
 
     use super::{
-        ensure_managed_provider_live_after_attach, execute_leader_plan, format_launcher_failure,
-        handle_exec_provider_startup_prompts, push_bounded_stderr, shlex_quote,
-        LEADER_STDERR_LIMIT,
+        ensure_managed_provider_live_after_attach, execute_leader_plan_after_ambient_authority,
+        format_launcher_failure, handle_exec_provider_startup_prompts,
+        is_interactive_shell_basename, push_bounded_stderr, shlex_quote,
+        VerifiedAmbientPaneAuthority, LEADER_STDERR_LIMIT,
     };
 
     struct ScriptedTransport {
@@ -1857,7 +2663,7 @@ mod tests {
             detached: false,
         };
 
-        let outcome = execute_leader_plan(&plan, &workspace)
+        let outcome = execute_leader_plan_after_ambient_authority(&plan, &workspace, None)
             .expect("external marker must be present before provider argv runs");
 
         assert_eq!(outcome.status, crate::leader::LeaderLaunchStatus::Exited);
@@ -1914,8 +2720,27 @@ mod tests {
             detached: false,
         };
 
-        let outcome = execute_leader_plan(&plan, &workspace)
-            .expect("current pane binding must be present before provider argv runs");
+        let authority = VerifiedAmbientPaneAuthority {
+            pane_id: PaneId::new("%77"),
+            observed: PaneInfo {
+                pane_id: PaneId::new("%77"),
+                session: SessionName::new("team-agent-leader-current"),
+                window_index: Some(0),
+                window_name: Some(WindowName::new("codex")),
+                pane_index: Some(0),
+                tty: Some("/dev/ttys077".to_string()),
+                current_command: Some("codex".to_string()),
+                current_path: Some(workspace.clone()),
+                active: true,
+                pane_pid: None,
+                leader_env: BTreeMap::new(),
+            },
+            endpoint: "/private/tmp/tmux-501/default".to_string(),
+            tmux: "/private/tmp/tmux-501/default,123,0".to_string(),
+        };
+        let outcome =
+            execute_leader_plan_after_ambient_authority(&plan, &workspace, Some(&authority))
+                .expect("current pane binding must be present before provider argv runs");
 
         assert_eq!(outcome.status, crate::leader::LeaderLaunchStatus::Exited);
         let state = crate::state::persist::load_runtime_state(&workspace).unwrap();
@@ -1968,12 +2793,26 @@ mod tests {
         assert_eq!(sent[0].1, vec![Key::Enter]);
     }
 
+    #[test]
+    fn interactive_shell_basename_recognizes_supported_shells() {
+        let shells = [
+            "zsh", "bash", "sh", "fish", "dash", "ksh", "tcsh", "csh", "ash", "mksh", "yash",
+            "elvish", "nu", "nushell", "xonsh",
+        ];
+        for shell in shells {
+            assert!(is_interactive_shell_basename(shell));
+            assert!(is_interactive_shell_basename(&shell.to_uppercase()));
+        }
+        for provider in ["claude", "codex", "copilot", "gemini"] {
+            assert!(!is_interactive_shell_basename(provider));
+        }
+    }
+
     // ═══════════════════════════════════════════════════════════════════
     // 0.4.10+ mirror-session fix v2 (option B: independent session per launch).
     //
-    // managed_leader_session_name appends a per-launch nonce so each
-    // `team-agent <provider>` entry in the same workspace creates its own
-    // tmux session, matching `tmux new-session + claude` semantics.
+    // The managed selector reuses a live provider leader prefix when present;
+    // its no-candidate fallback appends a per-launch nonce.
     // ═══════════════════════════════════════════════════════════════════
 
     #[test]
@@ -2046,37 +2885,84 @@ mod tests {
         let _ = std::fs::remove_dir_all(&workspace);
     }
 
-    /// CR C-5 source grep guard: managed mode passes the nonce session
-    /// name through `leader_start_plan` so the per-launch independence
-    /// reaches `ensure_managed_leader_pane`. External/attach paths must
-    /// keep `leader_session_name`.
+    // Tombstone for `managed_path_uses_nonce_session_name_grep_guard`: A-22
+    // replaced that implementation-shape assertion with the contract guard
+    // below. Keep the old name here for audit/search provenance.
     #[test]
-    fn managed_path_uses_nonce_session_name_grep_guard() {
+    fn a22_launch_session_reuse_contract() {
         let manifest = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
         let start_rs = manifest.join("src").join("leader").join("start.rs");
         let contents = std::fs::read_to_string(&start_rs).expect("read leader/start.rs");
-        // leader_start_plan must dispatch to managed_leader_session_name
-        // on the managed path.
         let start = contents
-            .find("pub fn leader_start_plan(")
-            .expect("leader_start_plan must exist");
+            .find("fn leader_start_plan_with_ambient_authority(")
+            .expect("leader_start_plan_with_ambient_authority must exist");
         let end = contents[start + 1..]
-            .find("\npub fn ")
-            .or_else(|| contents[start + 1..].find("\nfn "))
-            .map(|p| start + 1 + p)
+            .find("\nfn ")
+            .map(|offset| start + 1 + offset)
             .unwrap_or(contents.len());
         let body = &contents[start..end];
         assert!(
-            body.contains("managed_leader_session_name(provider, workspace)"),
-            "leader_start_plan must call managed_leader_session_name on \
-             the managed path (mirror-session fix v2); body excerpt: {body}"
+            body.contains("managed_leader_session_for_launch(provider, workspace)"),
+            "managed launch must select from the A-22 candidate contract; body excerpt: {body}"
         );
-        // The external_path branch must still use the stable name.
         assert!(
             body.contains("leader_session_name(provider, workspace)"),
             "leader_start_plan must keep leader_session_name on the \
              external/attach paths; body excerpt: {body}"
         );
+        let workspace =
+            std::env::temp_dir().join(format!("ta_rs_a22_contract_{}", std::process::id()));
+        let reused = super::managed_leader_session_from_candidates(
+            Provider::ClaudeCode,
+            &workspace,
+            vec![
+                "team-worker-not-a-leader".to_string(),
+                "team-agent-leader-claude_code-z".to_string(),
+                "team-agent-leader-codex-other".to_string(),
+                "team-agent-leader-claude_code-a".to_string(),
+            ],
+        );
+        assert_eq!(
+            reused.as_str(),
+            "team-agent-leader-claude_code-a",
+            "managed launch must deterministically reuse a matching leader prefix session"
+        );
+        let _ = std::fs::remove_dir_all(workspace);
+    }
+
+    #[test]
+    fn a22_launch_session_without_candidate_gets_nonce() {
+        let workspace =
+            std::env::temp_dir().join(format!("ta_rs_a22_nonce_{}", std::process::id()));
+        let fresh = super::managed_leader_session_from_candidates(
+            Provider::ClaudeCode,
+            &workspace,
+            std::iter::empty(),
+        );
+        assert!(
+            fresh.as_str().starts_with("team-agent-leader-claude_code-"),
+            "no candidate must create a leader-prefixed managed session: {}",
+            fresh.as_str()
+        );
+        assert_ne!(
+            fresh.as_str(),
+            super::leader_session_name(Provider::ClaudeCode, &workspace).as_str(),
+            "managed fallback must carry a per-launch nonce"
+        );
+        let _ = std::fs::remove_dir_all(workspace);
+    }
+
+    #[test]
+    fn a22_external_attach_session_name_remains_stable() {
+        let workspace =
+            std::env::temp_dir().join(format!("ta_rs_a22_external_{}", std::process::id()));
+        let stable = super::leader_session_name(Provider::ClaudeCode, &workspace);
+        assert_eq!(
+            stable.as_str(),
+            super::leader_session_name(Provider::ClaudeCode, &workspace).as_str(),
+            "external/attach paths must keep the stable workspace-keyed session name"
+        );
+        let _ = std::fs::remove_dir_all(workspace);
     }
 
     #[test]