@team-agent/installer 0.5.118 → 0.5.120

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

@@ -944,52 +944,56 @@ fn preflight_fresh_leader_identity(
         .ok()
         .filter(|pane| !pane.is_empty());
     let current_endpoint = crate::tmux_backend::socket_name_from_tmux_env();
-    match crate::layout::worker_env::caller_provider_resolution(
+    let refusal = |stage: &str, reason: &str, action: &str| {
+        Some((
+            format!("quick-start refused before spawn: {}", reason.replace('_', " ")),
+            vec![format!("stage={stage} reason={reason}")],
+            vec![action.to_string()],
+        ))
+    };
+    let resolution = crate::layout::worker_env::caller_provider_resolution(
         pane.as_deref(),
         current_endpoint.as_deref(),
         transport.tmux_endpoint().as_deref(),
-    ) {
-        crate::layout::worker_env::CallerProviderResolution::Invalid => Some((
-            "quick-start refused before spawn: invalid caller tuple".to_string(),
-            vec!["stage=strict_provider reason=invalid_caller_tuple".to_string()],
-            vec![
-                "fix conflicting CALLER_* / TEAM_AGENT_LEADER_* identity; do not run claim-leader"
-                    .to_string(),
-            ],
-        )),
-        crate::layout::worker_env::CallerProviderResolution::Valid(_) => None,
-        crate::layout::worker_env::CallerProviderResolution::Absent => {
-            let Some(pane) = pane else {
-                return None;
-            };
-            let command =
-                query_caller_pane_command(transport, &PaneId::new(pane)).unwrap_or_default();
-            let explicit = std::env::var("TEAM_AGENT_LEADER_PROVIDER")
-                .ok()
-                .filter(|provider| !provider.is_empty());
-            if command.trim().is_empty() {
-                return Some((
-                    "quick-start refused before spawn: command unobservable".to_string(),
-                    vec!["stage=command_observation reason=command_unobservable".to_string()],
-                    vec!["run from a live provider pane; do not run claim-leader".to_string()],
-                ));
-            }
-            if crate::leader::owner_bind::strict_owner_bind_provider(explicit.as_deref(), &command)
-                .is_some()
-            {
-                None
-            } else {
-                Some((
-                    "quick-start refused before spawn: provider unresolved".to_string(),
-                    vec!["stage=strict_provider reason=provider_unresolved".to_string()],
-                    vec![
-                        "set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader"
-                            .to_string(),
-                    ],
-                ))
-            }
+    );
+    if matches!(resolution, crate::layout::worker_env::CallerProviderResolution::Invalid) {
+        return refusal("strict_provider", "invalid_caller_tuple",
+            "fix conflicting CALLER_* / TEAM_AGENT_LEADER_* identity; do not run claim-leader");
+    }
+    let Some(pane) = pane else {
+        return refusal("caller_pane", "caller_pane_missing",
+            "run start from the intended live Leader provider pane; no workers or coordinator were started");
+    };
+    let pane = PaneId::new(pane);
+    let command = query_caller_pane_command(transport, &pane).unwrap_or_default();
+    if command.trim().is_empty() {
+        return refusal("command_observation", "command_unobservable",
+            "run from a live provider pane; do not run claim-leader");
+    }
+    if matches!(resolution, crate::layout::worker_env::CallerProviderResolution::Absent) {
+        let explicit = std::env::var("TEAM_AGENT_LEADER_PROVIDER")
+            .ok().filter(|provider| !provider.is_empty());
+        if crate::leader::owner_bind::strict_owner_bind_provider(explicit.as_deref(), &command).is_none() {
+            return refusal("strict_provider", "provider_unresolved",
+                "set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader");
         }
     }
+    // A typed caller tuple is identity evidence, not proof that its pane still
+    // exists. Use the caller's endpoint, never the worker server's same %id.
+    let targets = match list_caller_targets(transport) {
+        Ok(targets) => targets,
+        Err(_) => return refusal("caller_pane", "caller_pane_unobservable",
+            "inspect the intended Leader endpoint; no workers or coordinator were started"),
+    };
+    let Some(target) = targets.iter().find(|target| target.pane_id == pane) else {
+        return refusal("caller_pane", "caller_pane_not_live",
+            "run from the intended live Leader pane; no workers or coordinator were started");
+    };
+    if target.current_path.as_ref().is_none_or(|path| path.as_os_str().is_empty()) {
+        return refusal("caller_pane", "caller_cwd_unobservable",
+            "inspect the intended Leader pane workspace before retrying start");
+    }
+    None
 }
 
 fn bind_fresh_quick_start_leader(
@@ -1151,6 +1155,12 @@ pub fn quick_start_in_workspace_with_backend(
         // team_key. When quick-start's downstream code runs, state.json
         // still has whatever it had before (empty on fresh launch), so
         // the spec-compile + worker-spawn path runs normally.
+        let caller_transport = quick_start_tmux_backend(&workspace);
+        if let Some((summary, blockers, next_actions)) = preflight_fresh_leader_identity(&caller_transport) {
+            return Ok(QuickStartReport::PreflightBlocked {
+                summary, blockers, next_actions, attach_commands: Vec::new(),
+            });
+        }
         let run_ws = crate::coordinator::WorkspacePath::new(workspace.clone());
         let start_report =
             crate::coordinator::health::start_coordinator_with_team(&run_ws, Some(team_key_str))
@@ -1508,46 +1518,53 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
     let quick_start_phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     let mut launch =
         launch_with_transport_in_workspace(&workspace, &spec_path, false, yes, true, transport)?;
-    annotate_persisted_team_depth(
-        &workspace,
-        &state_team_key,
-        team_depth.parent_team_key.as_deref(),
-        team_depth.team_depth,
-    )?;
-    // Fresh initialization owns this one fail-closed bind attempt. It is
-    // independent of worker layout, so receiver binding is always attempted
-    // binding. Readiness receives true only after canonical registry readback.
-    let _ = take_fresh_bind_refusal();
-    launch.leader_receiver_attached = bind_fresh_quick_start_leader(
-        &workspace,
-        &state_team_key,
-        seeded_owner.as_ref(),
-        seeded_receiver.as_ref(),
-        transport,
-    )?;
-    if !launch.leader_receiver_attached {
-        if let Some((stage, reason)) = take_fresh_bind_refusal() {
-            launch.leader_bind_stage = Some(stage.to_string());
-            launch.leader_bind_reason = Some(reason.to_string());
+    let mut coordinator_state = "not_attempted";
+    let completion = (|| -> Result<(), LifecycleError> {
+        annotate_persisted_team_depth(
+            &workspace, &state_team_key,
+            team_depth.parent_team_key.as_deref(), team_depth.team_depth,
+        )?;
+        // Recheck at the original bind/commit point: preflight is not a lease
+        // over the caller pane. A lost caller must not start a coordinator.
+        let _ = take_fresh_bind_refusal();
+        launch.leader_receiver_attached = bind_fresh_quick_start_leader(
+            &workspace, &state_team_key, seeded_owner.as_ref(),
+            seeded_receiver.as_ref(), transport,
+        )?;
+        if !launch.leader_receiver_attached {
+            if let Some((stage, reason)) = take_fresh_bind_refusal() {
+                launch.leader_bind_stage = Some(stage.to_string());
+                launch.leader_bind_reason = Some(reason.to_string());
+            }
+            return Err(LifecycleError::RequirementUnmet(format!(
+                "Leader binding failed after worker launch: {}",
+                launch.leader_bind_reason.as_deref().unwrap_or("unknown")
+            )));
         }
-    }
-    launch.session_capture_incomplete_agents =
-        quick_start_session_capture_incomplete_agents(&workspace, &state_team_key);
-    let coordinator_workspace = crate::coordinator::WorkspacePath::new(workspace.clone());
-    let coordinator_report = crate::coordinator::start_coordinator(&coordinator_workspace)
-        .map_err(|error| {
-            LifecycleError::StatePersist(format!(
+        launch.session_capture_incomplete_agents =
+            quick_start_session_capture_incomplete_agents(&workspace, &state_team_key);
+        let coordinator_workspace = crate::coordinator::WorkspacePath::new(workspace.clone());
+        coordinator_state = "attempted_unknown";
+        let coordinator_report = crate::coordinator::start_coordinator(&coordinator_workspace)
+            .map_err(|error| LifecycleError::StatePersist(format!(
                 "coordinator start failed for {}: {error}; inspect {} before retrying",
                 workspace.display(),
                 crate::coordinator::coordinator_log_path(&coordinator_workspace).display()
-            ))
-        })?;
-    quick_start_phase_timer.emit(
-        &workspace,
-        "launch.phase",
-        crate::lifecycle::restart::LifecyclePhase::CoordinatorStart,
-    );
-    require_quick_start_coordinator_started(&coordinator_report, &workspace)?;
+            )))?;
+        quick_start_phase_timer.emit(
+            &workspace, "launch.phase",
+            crate::lifecycle::restart::LifecyclePhase::CoordinatorStart,
+        );
+        require_quick_start_coordinator_started(&coordinator_report, &workspace)?;
+        coordinator_state = "running_confirmed";
+        Ok(())
+    })();
+    if let Err(error) = completion {
+        return Ok(QuickStartReport::Partial {
+            workspace, session_name, launch: Box::new(launch), team: state_team_key,
+            error: error.to_string(), coordinator_state: coordinator_state.to_string(),
+        });
+    }
     let coordinator_action = "coordinator started";
     // BUG-7: build an honest readiness verdict from the post-spawn runtime state.
     // - If persist_spawn_agent_state (BUG-2 fix) marked any agent non-running, the
@@ -1701,6 +1718,78 @@ mod fresh_quick_start_leader_binding_tests {
 
     static SEQUENCE: AtomicU64 = AtomicU64::new(0);
 
+    #[test]
+    #[serial_test::serial(env)]
+    fn issue337_missing_caller_is_refused_before_any_launch_effect() {
+        let env = HermeticTestEnv::enter("issue337-no-caller");
+        env.scrub_tmux();
+        env.assert_no_real_tmux();
+        let transport = OfflineTransport::new();
+        let refusal = preflight_fresh_leader_identity(&transport)
+            .expect("a missing caller must not reach worker/coordinator spawn");
+        assert!(refusal.1.iter().any(|reason| reason.contains("caller_pane_missing")));
+        assert!(!env.home().join(".team").exists());
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn issue337_typed_caller_still_requires_a_current_live_pane_observation() {
+        let env = HermeticTestEnv::enter("issue337-unobservable-caller");
+        env.scrub_tmux();
+        env.assert_no_real_tmux();
+        std::env::set_var("TMUX", "/private/tmp/issue337/default,1,0");
+        std::env::set_var("TMUX_PANE", "%42");
+        std::env::set_var(CALLER_PANE_ENV, "%42");
+        std::env::set_var(CALLER_PROVIDER_ENV, "pi");
+        std::env::set_var(CALLER_ENDPOINT_ENV, "/private/tmp/issue337/default");
+        let transport = OfflineTransport::new().with_tmux_endpoint("/private/tmp/issue337/default");
+        let refusal = preflight_fresh_leader_identity(&transport)
+            .expect("typed identity is not a live pane observation");
+        assert!(refusal.1.iter().any(|reason| reason.contains("unobservable") || reason.contains("not_live")));
+        assert!(!env.home().join(".team").exists());
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn issue337_fresh_start_without_caller_creates_no_runtime_or_worker() {
+        let env = HermeticTestEnv::enter("issue337-zero-effects");
+        env.scrub_tmux();
+        env.assert_no_real_tmux();
+        let workspace = env.workspace("ws");
+        let team = workspace.join("roles");
+        std::fs::create_dir_all(team.join("agents")).unwrap();
+        std::fs::write(team.join("TEAM.md"), "---\nname: fresh\nobjective: test\nprovider: codex\n---\nTeam.\n").unwrap();
+        std::fs::write(team.join("agents/worker.md"), "---\nname: worker\nrole: Worker\nprovider: codex\nmodel: gpt-5.5\nauth_mode: subscription\ndangerously_skip_permissions: false\n---\nTest.\n").unwrap();
+        let transport = OfflineTransport::new();
+        let report = quick_start_with_transport_in_workspace(
+            &workspace, &team, None, true, Some("fresh"), &transport,
+        ).unwrap();
+        assert!(matches!(report, QuickStartReport::PreflightBlocked { .. }));
+        assert!(transport.spawn_records().is_empty());
+        assert!(!workspace.join(".team/team.db").exists());
+        assert!(!crate::state::persist::runtime_state_path(&workspace).exists());
+        assert!(!crate::model::paths::runtime_spec_path(&workspace, "fresh").exists());
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn issue337_exact_live_typed_caller_passes_readonly_preflight() {
+        let env = HermeticTestEnv::enter("issue337-positive");
+        env.scrub_tmux();
+        env.assert_no_real_tmux();
+        let _tmux = env.with_env("TMUX", "/private/tmp/issue337/default,1,0");
+        let _pane = env.with_env("TMUX_PANE", "%1");
+        let _provider = env.with_env(CALLER_PROVIDER_ENV, "pi");
+        let _caller = env.with_env(CALLER_PANE_ENV, "%1");
+        let _endpoint = env.with_env(CALLER_ENDPOINT_ENV, "/private/tmp/issue337/default");
+        let transport = OfflineTransport::new()
+            .with_tmux_endpoint("/private/tmp/issue337/default")
+            .with_pane_current_command("%1", "bash")
+            .with_targets(vec![caller_target(env.workspace("caller"), None)]);
+        assert!(preflight_fresh_leader_identity(&transport).is_none());
+        assert!(transport.spawn_records().is_empty());
+    }
+
     #[test]
     fn bootstrap_binding_is_preserved_without_epoch_reset_or_takeover() {
         let bootstrap = json!({

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

@@ -36,6 +36,26 @@ use super::*;
 
 // ── lifecycle::launch —— 冷启 / quick-start / 危险审批探测 ──────────────────
 
+/// White-box producer/worker-engine fixture, not a public start admission path.
+/// Keep unbound producer assertions separate from public caller admission.
+#[cfg(test)]
+pub(crate) fn materialize_unbound_state_for_test(
+    workspace: &Path, team_dir: &Path, team_key: &str,
+    transport: &crate::transport::test_support::OfflineTransport,
+) -> Result<LaunchReport, LifecycleError> {
+    let spec = crate::compiler::compile_team(team_dir)
+        .map_err(|error| LifecycleError::Compile(error.to_string()))?;
+    let path = crate::model::paths::runtime_spec_path(workspace, team_key);
+    spec_state::write_spec_atomic(&path, &spec)?;
+    let path = path.canonicalize().map_err(|error| LifecycleError::StatePersist(error.to_string()))?;
+    let mut state = spec_state::initial_runtime_state(
+        &spec, &path, workspace, team_dir, team_key, transport.tmux_endpoint().as_deref(),
+    );
+    quick_start_transport::annotate_runtime_transport(&mut state, transport, workspace, None);
+    state_projection::save_launched_team_state_for_key(workspace, &state, Some(team_key), None)?;
+    launch_with_transport_in_workspace(workspace, &path, false, true, true, transport)
+}
+
 /// ---
 /// purpose: 冷启全队的默认入口，按 spec 所在目录绑定 per-team tmux socket 后转 launch_with_transport
 /// params:
@@ -384,6 +404,14 @@ pub use worker_env::{apply_cursor_subscription_proxy_env, CursorProxyPresence};
 mod identity;
 pub(super) use identity::*;
 
+// Read-only CLI surface facades; predicate bodies and launch behavior stay unchanged.
+pub(crate) fn surface_has_runtime_team(state: &serde_json::Value, team: &str) -> bool {
+    identity::runtime_state_has_quick_start_team(state, team)
+}
+pub(crate) fn surface_is_leader_bootstrap(state: &serde_json::Value) -> bool {
+    identity::is_quick_start_leader_bootstrap(state)
+}
+
 // Test-only seam for the real leader producer -> unchanged bootstrap classifier.
 #[cfg(test)]
 pub(crate) fn quick_start_has_runtime_for_test(state: &serde_json::Value, team: &str) -> bool {

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

@@ -110,6 +110,23 @@ pub(crate) use rebuild::{
 pub(crate) use remove::remove_agent_with_transport;
 pub use remove::{remove_agent, remove_agent_flag_requirements};
 pub use selection::decide_start_mode;
+pub(crate) use selection::restart_agent_never_captured;
+
+/// Read-only CLI preflight facade. Reuses the original provider-specific probe;
+/// does not capture a session, write state, or authorize a future spawn.
+pub(crate) fn surface_resume_backing_probe(
+    workspace: &Path,
+    agent_id: &AgentId,
+    agent: &serde_json::Value,
+    provider: Provider,
+    session: &SessionId,
+    rollout: Option<&RolloutPath>,
+) -> (bool, Vec<std::path::PathBuf>) {
+    let probe = common::resume_backing_probe_for_agent(
+        workspace, agent_id, agent, provider, session, rollout,
+    );
+    (probe.exists, probe.checked_paths)
+}
 pub(crate) use selection::{classify_first_send_at, classify_restart_plan, python_type_name};
 // Layer 2 (leader follow-up 2026-06-22): test-visible workspace-aware
 // classification so lifecycle/tests/restart.rs can exercise the

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

@@ -147,9 +147,7 @@ gate — N35/MUST-17); found {hits} occurrence(s)"
 #[test]
 #[serial(env)]
 fn b2_quick_start_ready_has_attach_commands_and_socket_miss_is_observable() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("acceptance-b-b2-quick-start");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("acceptance-b-b2-quick-start");
     let _g = EnvGuard::set(&[(ANCESTRY_KEY, NEUTRAL_ANCESTRY)]);
     let ws = tmp_ws("b2-attach");
     let team_dir = write_min_team(&ws, "b2team");

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

@@ -54,9 +54,7 @@ const NEUTRAL_ANCESTRY: &str = "[\"/bin/zsh\"]";
 #[test]
 #[serial(env)]
 fn d1_d2_d3_codex_argv_matches_python_golden_escape_timeout_profile() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("behavioral-d123-codex");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("behavioral-d123-codex");
     let _ancestry = EnvGuard::set(&[(ANCESTRY_KEY, NEUTRAL_ANCESTRY)]);
     let ws = tmp_dir("d123-codex-argv");
     let team_dir = write_team(
@@ -181,9 +179,7 @@ fn d1_d2_d3_codex_argv_matches_python_golden_escape_timeout_profile() {
 #[test]
 #[serial(env)]
 fn d4_worker_shell_env_sets_team_agent_id_to_worker_self() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("behavioral-d4-shell-env");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("behavioral-d4-shell-env");
     let _guard = EnvGuard::set(&[
         (ANCESTRY_KEY, NEUTRAL_ANCESTRY),
         ("TEAM_AGENT_ID", "stale-mcp-caller"),
@@ -224,9 +220,7 @@ fn d4_worker_shell_env_sets_team_agent_id_to_worker_self() {
 #[test]
 #[serial(env)]
 fn d5_fresh_launch_spawn_cwd_and_state_use_workspace() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("behavioral-d5-spawn-cwd");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("behavioral-d5-spawn-cwd");
     let _ancestry = EnvGuard::set(&[(ANCESTRY_KEY, NEUTRAL_ANCESTRY)]);
     let ws = tmp_dir("d5-spawn-cwd");
     let team_dir = write_team(&ws, &simple_codex_team("d5team", "worker_a", "Cwd Worker"));
@@ -268,9 +262,7 @@ fn d5_fresh_launch_spawn_cwd_and_state_use_workspace() {
 #[test]
 #[serial(env)]
 fn d6_compiled_system_prompt_first_section_is_identity() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("behavioral-d6-prompt");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("behavioral-d6-prompt");
     let _ancestry = EnvGuard::set(&[(ANCESTRY_KEY, NEUTRAL_ANCESTRY)]);
     let ws = tmp_dir("d6-prompt-order");
     let team_dir = write_team(
@@ -323,9 +315,7 @@ chunks=[identity, TEAMMATE_SYSTEM_PROMPT, ...]; live ps confirms identity-first)
 #[test]
 #[serial(env)]
 fn d7_runtime_fast_sends_codex_fast_mode_toggle() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("behavioral-d7-fast-mode");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("behavioral-d7-fast-mode");
     let _ancestry = EnvGuard::set(&[(ANCESTRY_KEY, NEUTRAL_ANCESTRY)]);
     let ws = tmp_dir("d7-fast-mode");
     let mut fixture = simple_codex_team("d7team", "worker_a", "Fast Worker");

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

@@ -32,10 +32,9 @@ use team_agent::transport::{
 #[test]
 #[serial(env)]
 fn compatible_api_profile_writes_claude_settings_and_project_state_with_mcp_servers() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("claude-compatible-config");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("claude-compatible-config");
     let ws = tmp_dir("compatible-config-files");
+    super::launch_spawn::seed_healthy_coordinator(&ws);
     let team = write_claude_profile_team(&ws, "cfgteam", "clauder");
     let transport = RecordingTransport::default();
 

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

@@ -34,12 +34,11 @@ use team_agent::transport::{
 #[test]
 #[serial(env)]
 fn compatible_api_profile_quick_start_spawns_claude_with_profile_env_and_state_metadata() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("claude-profile-quick-start");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("claude-profile-quick-start");
     assert_s0_profile_launch_shape();
 
     let ws = tmp_dir("profile-launch");
+    super::launch_spawn::seed_healthy_coordinator(&ws);
     let team = write_claude_profile_team(&ws, "claudeprof", "clauder");
     let transport = RecordingTransport::default();
 

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

@@ -46,7 +46,7 @@ struct Fixture {
 }
 impl Fixture {
     fn new(tag: &str) -> Self {
-        let env = hermetic::HermeticTestEnv::enter(tag);
+        let env = hermetic::HermeticTestEnv::enter_with_leader(tag);
         let ws = env.workspace("workspace");
         let team = ws.join("roles");
         fs::create_dir_all(team.join("agents")).unwrap();
@@ -68,7 +68,12 @@ impl Fixture {
         let real_pi = env.root().join("pi-real");
         executable(&real_pi, &script);
         std::os::unix::fs::symlink(&real_pi, bin.join("pi")).unwrap();
-        executable(&bin.join("tmux"), "#!/bin/sh\ncase \"$*\" in\n*-V*) echo 'tmux 3.4';;\n*has-session*) exit 1;;\n*list-sessions*|*list-windows*|*list-panes*) exit 0;;\n*) exit 0;;\nesac\n");
+        let caller = std::env::var("TMUX").expect("owned fixture caller").split(',').next().unwrap().to_string();
+        let native_tmux = hermetic::fixture_tmux_binary();
+        executable(&bin.join("tmux"), &format!(
+            "#!/bin/sh\nwant_socket=0\nfor argument in \"$@\"; do\n  if [ \"$want_socket\" = 1 ]; then\n    if [ \"$argument\" = {} ]; then exec {} \"$@\"; fi\n    break\n  fi\n  if [ \"$argument\" = -S ]; then want_socket=1; fi\ndone\ncase \"$*\" in\n*-V*) echo 'tmux 3.4';;\n*has-session*) exit 1;;\n*list-sessions*|*list-windows*|*list-panes*) exit 0;;\n*) exit 0;;\nesac\n",
+            crate::cli::shell_quote(&caller), crate::cli::shell_quote(&native_tmux.to_string_lossy()),
+        ));
         let guards = vec![
             env.with_env("PATH", &format!("{}:/usr/bin:/bin", bin.display())),
             env.with_env(SWITCH, "off"),
@@ -1219,6 +1224,9 @@ fn a13_materializer_version_catalog_and_nonagent_command_builders_are_not_routed
 #[serial(env)]
 fn a07_attach_existing_never_opens_enabled_invalid_route_config() {
     let f = Fixture::new("argv-attach");
+    // This planner-only case explicitly models attach from outside tmux,
+    // not the owned caller used by positive worker-start fixtures.
+    f.env.scrub_tmux();
     f.raw("invalid JSON");
     f.switch(Some("on"));
     let plan = f.leader(Provider::Pi, true, true).unwrap();

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

@@ -54,7 +54,7 @@ struct Case {
 impl Case {
     fn start() -> Self {
         ensure_team_agent_cli();
-        let env = HermeticTestEnv::enter("g1ct");
+        let env = HermeticTestEnv::enter_with_leader("g1ct");
         let workspace = env.workspace("ws");
         write_team_docs(&workspace);
         Self { env, workspace }
@@ -134,6 +134,12 @@ impl Case {
     }
 }
 
+impl Drop for Case {
+    fn drop(&mut self) {
+        self.shutdown();
+    }
+}
+
 /// `cargo test --lib` does not build `bin/team-agent`. Hermetic CLI
 /// lookup then panics and impl_check.sh sees 1 FAILED. Build the bin
 /// into the same CARGO_TARGET_DIR the lib test already uses.
@@ -338,6 +344,7 @@ fn clone_ok(case: &Case, source: &str, dest: &str, phase: &str) {
 
 /// clone 后分身 role 保留源席 tools；编译 spec 不投影 tools。
 #[test]
+#[serial_test::serial(env)]
 fn clone_agent_preserves_source_tools() {
     let case = Case::start();
     let qs = case.run(&[

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

@@ -168,7 +168,7 @@ impl Case {
     /// product's existing test seam so the derived approval policy is a
     /// function of the FIXTURE, never of the host process tree.
     fn start_with_ancestry(tag: &str, ancestry_argv: &[&str]) -> Self {
-        let env = HermeticTestEnv::enter(tag);
+        let env = HermeticTestEnv::enter_with_leader(tag);
         let workspace = env.workspace("ws");
         write_team_docs(&workspace, "claude");
         let shim_dir = write_claude_backing_shim(&workspace);
@@ -500,8 +500,9 @@ fn r8_copilot_fork_is_no_longer_capability_refused() {
         // the capability gate — a CLI-shaped R8 could never be RED. An in-process
         // RecordingTransport stands the team up without a live copilot TUI (no
         // ready-screen hang).
-        let env = HermeticTestEnv::enter("cf-r8");
+        let env = HermeticTestEnv::enter_with_leader("cf-r8");
         let workspace = env.workspace("ws");
+        super::launch_spawn::seed_healthy_coordinator(&workspace);
         let team_dir = write_copilot_team_docs(&workspace);
         // Session ABSENT at quick-start so it can create the team session; spawn_first
         // flips session_present true, so the later fork sees a live session. (Starting

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

@@ -31,10 +31,9 @@ const CONTRACT_HEADING_PREFIX: &str = "# Team Agent communication contract: ";
 #[test]
 #[serial_test::serial(env)]
 fn t06_each_official_mode_selects_one_runtime_contract_in_real_spawn_prompt() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("communication-mode-official");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("communication-mode-official");
     let root = fixture("official", None);
+    super::launch_spawn::seed_healthy_coordinator(&root);
     let transport = RecordingTransport::default();
     quick_start_with_transport_in_workspace(
         &root,
@@ -87,10 +86,9 @@ fn t06_each_official_mode_selects_one_runtime_contract_in_real_spawn_prompt() {
 #[test]
 #[serial_test::serial(env)]
 fn t06_selected_templates_project_the_two_signed_communication_boundaries() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("communication-mode-semantics");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("communication-mode-semantics");
     let root = fixture("semantics", None);
+    super::launch_spawn::seed_healthy_coordinator(&root);
     let transport = RecordingTransport::default();
     quick_start_with_transport_in_workspace(
         &root,
@@ -141,10 +139,9 @@ fn t06_selected_templates_project_the_two_signed_communication_boundaries() {
 #[test]
 #[serial_test::serial(env)]
 fn t07_final_spawn_prompt_does_not_leak_leader_centric_obligations_into_orchestrated() {
-    let hermetic = hermetic_guard::HermeticTestEnv::enter("communication-mode-negative-boundary");
-    hermetic.scrub_tmux();
-    hermetic.assert_no_real_tmux();
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("communication-mode-negative-boundary");
     let root = fixture("negative-boundary", None);
+    super::launch_spawn::seed_healthy_coordinator(&root);
     let transport = RecordingTransport::default();
     quick_start_with_transport_in_workspace(
         &root,

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

@@ -1,4 +1,4 @@
-//! Copilot provider contracts (command-substitution tier, zero real sessions).
+//! Copilot provider contracts (zero model sessions; owned physical caller fixture).
 //!
 //! Basis docs (sole truth sources — where the in-tree implementation deviates, these
 //! contracts stay red):
@@ -32,10 +32,7 @@ mod hermetic_guard;
 fn _hermetic_boundary_marker(_: &hermetic_guard::HermeticTestEnv) {}
 
 fn enter_hermetic(tag: &str) -> hermetic_guard::HermeticTestEnv {
-    let env = hermetic_guard::HermeticTestEnv::enter(tag);
-    env.scrub_tmux();
-    env.assert_no_real_tmux();
-    env
+    hermetic_guard::HermeticTestEnv::enter_with_leader(tag)
 }
 
 use std::collections::{BTreeMap, BTreeSet};
@@ -875,6 +872,8 @@ fn copilot_mcp_residual_scan_unavailable_degrades_honestly_no_false_positive() {
     let home = tmp_ws("residual-unavail-home");
     std::fs::create_dir_all(home.join(".copilot")).unwrap();
     let empty_bin = tmp_ws("no-copilot-bin");
+    #[cfg(unix)]
+    std::os::unix::fs::symlink(hermetic_guard::fixture_tmux_binary(), empty_bin.join("tmux")).unwrap();
     let _guard = EnvGuard::set(&[
         (ANCESTRY_KEY, NEUTRAL_ANCESTRY),
         (
@@ -1942,6 +1941,9 @@ fn copilot_empty_mcp_list_shim(tag: &str) -> TempWorkspace {
     #[cfg(unix)]
     {
         use std::os::unix::fs::PermissionsExt;
+        // Only the explicit owned caller needs tmux; no provider is exposed by
+        // this symlink and the worker transport remains the recording fixture.
+        std::os::unix::fs::symlink(hermetic_guard::fixture_tmux_binary(), bin.join("tmux")).unwrap();
         // coordinator health needs the seeded test PID's real non-zombie status.
         // Keep PATH isolated and refuse any broader process inspection.
         std::fs::write(

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

@@ -291,8 +291,9 @@ fn cursor_mcp_enable_child_env_applies_direct_profile_unsets() {
 #[test]
 #[serial(env)]
 fn cursor_spawn_writes_identity_into_project_mcp_json() {
-    let _hermetic = hermetic_guard::HermeticTestEnv::enter("cursor-mcp-spawn");
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("cursor-mcp-spawn");
     let ws = tmp_dir("cursor-mcp-spawn");
+    super::launch_spawn::seed_healthy_coordinator(&ws);
     let team = write_cursor_team(&ws, "cursortm", "cursor_writer");
     let selected = cursor_mcp_json_path(&ws, "cursor_writer").unwrap();
     assert!(
@@ -331,11 +332,12 @@ fn cursor_spawn_writes_identity_into_project_mcp_json() {
 #[test]
 #[serial(env)]
 fn cursor_spawn_isolation_off_writes_workspace_mcp_json() {
-    let _hermetic = hermetic_guard::HermeticTestEnv::enter("cursor-mcp-spawn-legacy");
+    let _hermetic = hermetic_guard::HermeticTestEnv::enter_with_leader("cursor-mcp-spawn-legacy");
     let key = "TEAM_AGENT_CURSOR_MCP_ISOLATION";
     let prev = std::env::var(key).ok();
     std::env::set_var(key, "0");
     let ws = tmp_dir("cursor-mcp-spawn-legacy");
+    super::launch_spawn::seed_healthy_coordinator(&ws);
     let team = write_cursor_team(&ws, "cursortm", "cursor_writer");
     let result = quick_start_with_transport_in_workspace(
         &ws,