@team-agent/installer 0.5.112 → 0.5.113

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

@@ -397,6 +397,25 @@ fn same_workspace(left: &Path, right: &Path) -> bool {
         == std::fs::canonicalize(right).unwrap_or_else(|_| right.to_path_buf())
 }
 
+fn quick_start_tmux_endpoints_match(bound: &str, endpoint: &str) -> bool {
+    if bound == endpoint {
+        return true;
+    }
+    // A workspace transport uses a short `-L` name, while the native launcher
+    // persists an absolute `-S` path. Compare full resolved paths, never basenames.
+    let socket_path = |value: &str| {
+        let path = if Path::new(value).is_absolute() {
+            Some(PathBuf::from(value))
+        } else {
+            crate::tmux_backend::socket_path_for_name(value)
+        };
+        path.map(|path| crate::state::owner_gate::realpath_like(&path))
+    };
+    socket_path(bound)
+        .zip(socket_path(endpoint))
+        .is_some_and(|(bound, endpoint)| bound == endpoint)
+}
+
 fn persisted_binding_matches_verified_pane(
     state: &serde_json::Value,
     workspace: &Path,
@@ -455,7 +474,7 @@ fn persisted_binding_matches_verified_pane(
         && receiver
             .get("tmux_socket")
             .and_then(serde_json::Value::as_str)
-            == Some(endpoint)
+            .is_some_and(|bound| quick_start_tmux_endpoints_match(bound, endpoint))
         && receiver
             .get("authorized_team_workspace")
             .and_then(serde_json::Value::as_str)
@@ -1286,6 +1305,7 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
         )));
     }
     let state_path = crate::state::persist::runtime_state_path(&workspace);
+    let mut leader_bootstrap = None;
     if state_path.exists() {
         let state = crate::state::persist::load_runtime_state(&workspace)
             .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
@@ -1363,6 +1383,16 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
                 agent_ids,
             });
         }
+        let entry = state
+            .get("teams")
+            .and_then(serde_json::Value::as_object)
+            .and_then(|teams| teams.get(&canonical_team_key))
+            .unwrap_or(&state);
+        if is_quick_start_leader_bootstrap(entry) {
+            let mut bootstrap = entry.clone();
+            bootstrap["team_key"] = serde_json::json!(canonical_team_key);
+            leader_bootstrap = Some(bootstrap);
+        }
     }
     // CR-040/042: repeated quick-start from one template with distinct --team-id/--name
     // must NOT collide on the template-derived tmux session. Override the compiled
@@ -1384,12 +1414,20 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
             attach_commands: Vec::new(),
         });
     }
+    if let Some(bootstrap) = &leader_bootstrap {
+        // Allow initialization, not takeover of the existing leader binding.
+        ensure_owner_allowed_for_state(bootstrap, None)?;
+    }
     // E5 spec 迁移:spec 写到 .team/runtime/<team_key>/(中间产物,绝不落用户目录 agents_dir)。
     // Bug2:原子写(tmp+rename),避免半截 spec。
     let spec_path = crate::model::paths::runtime_spec_path(&workspace, &state_team_key);
     write_spec_atomic(&spec_path, &spec)?;
-    let _store = crate::message_store::MessageStore::open(&workspace)
-        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    let _store = crate::message_store::MessageStore::open(&workspace).map_err(|error| {
+        LifecycleError::StatePersist(format!(
+            "database initialization failed at {}: {error}; coordinator start was not attempted",
+            workspace.join(".team/team.db").display()
+        ))
+    })?;
     let resolved_spec_path =
         std::fs::canonicalize(&spec_path).unwrap_or_else(|_| spec_path.clone());
     let scoped_endpoint = transport.tmux_endpoint();
@@ -1401,6 +1439,9 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
         &state_team_key,
         scoped_endpoint.as_deref(),
     );
+    if let Some(bootstrap) = &leader_bootstrap {
+        preserve_quick_start_bootstrap_binding(&mut state, bootstrap, &state_team_key);
+    }
     // Keep this attempt-local seed separate from persisted `claimed_via`;
     // historical quick-start rows are never sufficient cleanup authority.
     let seeded_owner = state
@@ -1475,15 +1516,15 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
     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_started = crate::coordinator::start_coordinator(&coordinator_workspace)
-        .map(|report| report.ok)
-        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
-    quick_start_phase_timer.emit(&workspace, "launch.phase", "coordinator_start");
-    let coordinator_action = if coordinator_started {
-        "coordinator started"
-    } else {
-        "coordinator not started"
-    };
+    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)?;
+    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
     //   team is observably Degraded.
@@ -1491,7 +1532,7 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
     //   loaded successfully (provider-side codex/claude schema rejections happen
     //   asynchronously after spawn), so the verdict is PendingToolLoad — never
     //   bare Ready.
-    quick_start_phase_timer.emit(&workspace, "launch.phase", "readiness_wait");
+    quick_start_phase_timer.emit(&workspace, "launch.phase", crate::lifecycle::restart::LifecyclePhase::ReadinessWait);
     let worker_readiness = quick_start_worker_readiness(&workspace, &state_team_key);
     let attach_windows = load_runtime_state(&workspace)
         .ok()
@@ -1531,7 +1572,7 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
         ));
     }
     next_actions.extend(attach_commands.iter().cloned());
-    quick_start_phase_timer.emit(&workspace, "launch.phase", "completed");
+    quick_start_phase_timer.emit(&workspace, "launch.phase", crate::lifecycle::restart::LifecyclePhase::Completed);
     Ok(QuickStartReport::Ready {
         session_name,
         launch: Box::new(launch),
@@ -1542,8 +1583,73 @@ pub(crate) fn quick_start_with_transport_in_workspace_pi_preflight(
     })
 }
 
+fn preserve_quick_start_bootstrap_binding(
+    state: &mut serde_json::Value,
+    bootstrap: &serde_json::Value,
+    team_key: &str,
+) {
+    let mut binding = crate::state::ownership::OwnershipWrite::new();
+    if let Some(owner) = bootstrap.get("team_owner") {
+        binding = binding.with_team_owner(owner.clone());
+    }
+    if let Some(receiver) = bootstrap.get("leader_receiver") {
+        binding = binding.with_leader_receiver(receiver.clone());
+    }
+    if let Some(epoch) = bootstrap.get("owner_epoch").and_then(serde_json::Value::as_u64)
+        .or_else(|| bootstrap.get("team_owner").and_then(|owner| owner.get("owner_epoch")).and_then(serde_json::Value::as_u64))
+    {
+        binding = binding.with_owner_epoch(epoch);
+    }
+    crate::state::ownership::write_owner(state, team_key, binding);
+    // This is the new launch's transient view, not the persisted bootstrap.
+    // The canonical writer intentionally leaves root fields alone; remove the
+    // provisional epoch-1 seed so save_launched_team_state cannot merge it back
+    // over the preserved canonical binding. Reuse its existing view promotion.
+    if let Some(root) = state.as_object_mut() {
+        for key in ["team_owner", "leader_receiver", "owner_epoch"] {
+            root.remove(key);
+        }
+    }
+    super::state_projection::promote_launched_binding_from_team_entry(state, team_key);
+    for key in ["leader_client", "is_external_leader"] {
+        if let Some(value) = bootstrap.get(key) {
+            state[key] = value.clone();
+        }
+    }
+}
+
+fn require_quick_start_coordinator_started(
+    report: &crate::coordinator::StartReport,
+    workspace: &Path,
+) -> Result<(), LifecycleError> {
+    if report.ok {
+        return Ok(());
+    }
+    let details = serde_json::json!({
+        "ok": report.ok,
+        "status": report.status,
+        "pid": report.pid,
+        "previous_pid": report.previous_pid,
+        "binary_path": report.binary_path,
+        "binary_version": report.binary_version,
+        "rotation_reason": report.rotation_reason,
+        "binary_identity_relation": report.binary_identity_relation,
+        "log": report.log,
+        "schema_error": report.schema_error.as_ref().map(|error| format!("{error:?}")),
+        "action": report.action,
+        "workspace": workspace,
+        "coordinator_log_path": crate::coordinator::coordinator_log_path(
+            &crate::coordinator::WorkspacePath::new(workspace.to_path_buf())
+        ),
+    });
+    Err(LifecycleError::StatePersist(format!(
+        "coordinator start refused: {details}; workers may already be started; inspect the report before retrying quick-start"
+    )))
+}
+
 #[cfg(test)]
 mod fresh_quick_start_leader_binding_tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
     use super::*;
     use crate::layout::worker_env::{CALLER_ENDPOINT_ENV, CALLER_PANE_ENV, CALLER_PROVIDER_ENV};
     use crate::transport::test_support::OfflineTransport;
@@ -1556,6 +1662,103 @@ mod fresh_quick_start_leader_binding_tests {
 
     static SEQUENCE: AtomicU64 = AtomicU64::new(0);
 
+    #[test]
+    fn bootstrap_binding_is_preserved_without_epoch_reset_or_takeover() {
+        let bootstrap = json!({
+            "team_owner": {"pane_id": "%0", "provider": "pi", "owner_epoch": 7, "claimed_via": "claim-leader"},
+            "leader_receiver": {"pane_id": "%0", "status": "attached", "owner_epoch": 7},
+            "owner_epoch": 7,
+            "leader_client": {"diagnostic_only": true},
+            "is_external_leader": true
+        });
+        let mut launched = json!({
+            "team_key": "current", "agents": {"worker": {}},
+            "team_owner": {"owner_epoch": 1, "claimed_via": "quick-start"},
+            "leader_receiver": {"status": "pending"}, "owner_epoch": 1,
+            "is_external_leader": false
+        });
+        preserve_quick_start_bootstrap_binding(&mut launched, &bootstrap, "current");
+        for key in ["team_owner", "leader_receiver", "owner_epoch"] {
+            assert_eq!(launched.get(key), bootstrap.get(key));
+            assert_eq!(launched["teams"]["current"].get(key), bootstrap.get(key));
+        }
+        assert_eq!(launched.get("leader_client"), bootstrap.get("leader_client"));
+        assert_eq!(launched.get("is_external_leader"), Some(&json!(true)));
+        assert_eq!(launched["agents"], json!({"worker": {}}));
+        let merged = super::super::state_projection::merge_workspace_team_state_with_key(
+            &bootstrap, &launched, "current",
+        );
+        assert_eq!(merged["teams"]["current"]["team_owner"], bootstrap["team_owner"]);
+        assert_eq!(merged["teams"]["current"]["owner_epoch"], json!(7));
+    }
+
+    #[test]
+    fn coordinator_negative_report_retains_actual_details_and_does_not_become_ready() {
+        let mut report = crate::coordinator::StartReport {
+            ok: false,
+            pid: None,
+            status: crate::coordinator::StartOutcome::SchemaIncompatible,
+            previous_pid: Some(crate::coordinator::Pid(17)),
+            binary_path: Some("/tmp/candidate/team-agent".to_string()),
+            binary_version: Some("0.5.112".to_string()),
+            rotation_reason: Some("original rotation reason".to_string()),
+            binary_identity_relation: crate::coordinator::CoordinatorBinaryIdentityRelation::Unknown,
+            log: Some(PathBuf::from("/tmp/current/.team/runtime/coordinator.log")),
+            schema_error: Some(crate::coordinator::SchemaError::InitFailed { message: "original database permission denied".to_string() }),
+            action: Some("repair the exact database permissions".to_string()),
+        };
+        let error = require_quick_start_coordinator_started(&report, Path::new("/tmp/current"))
+            .unwrap_err().to_string();
+        for detail in ["schema_incompatible", "original database permission denied", "repair the exact database permissions", "/tmp/candidate/team-agent", "/tmp/current/.team/runtime/coordinator.log", "workers may already be started"] {
+            assert!(error.contains(detail), "lost {detail}: {error}");
+        }
+        report.ok = true;
+        report.status = crate::coordinator::StartOutcome::AlreadyRunning;
+        report.binary_identity_relation = crate::coordinator::CoordinatorBinaryIdentityRelation::DaemonNewerThanCaller;
+        assert!(require_quick_start_coordinator_started(&report, Path::new("/tmp/current")).is_ok());
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn same_current_leader_bootstrap_reaches_fresh_preflight_without_mutating_seed() {
+        let env = HermeticTestEnv::enter("current-bootstrap-preflight");
+        env.scrub_tmux();
+        env.assert_no_real_tmux();
+        let workspace = std::env::temp_dir().join(format!(
+            "ta-current-bootstrap-{}-{}", std::process::id(), SEQUENCE.fetch_add(1, Ordering::Relaxed)
+        ));
+        let team = workspace.join(".team/current");
+        std::fs::create_dir_all(team.join("agents")).unwrap();
+        std::fs::write(team.join("TEAM.md"), "---\nname: current\nobjective: Bootstrap fixture.\n---\n").unwrap();
+        std::fs::write(team.join("agents/worker.md"), "---\nname: worker\nrole: Worker\nprovider: codex\nauth_mode: subscription\ndangerously_skip_permissions: false\n---\nBounded fixture.\n").unwrap();
+        let state_path = crate::state::persist::runtime_state_path(&workspace);
+        std::fs::create_dir_all(state_path.parent().unwrap()).unwrap();
+        let state = json!({
+            "active_team_key": "current", "team_key": "current", "tasks": [],
+            "teams": {"current": {
+                "agents": {}, "tasks": [], "session_name": null,
+                "team_owner": {"pane_id": "%0", "provider": "pi", "owner_epoch": 1},
+                "leader_receiver": {"pane_id": "%0", "status": "attached"}
+            }}
+        });
+        std::fs::write(&state_path, serde_json::to_vec(&state).unwrap()).unwrap();
+        let before = std::fs::read(&state_path).unwrap();
+        // The real entrypoint must reach its existing strict identity preflight,
+        // not return ExistingRuntime merely because the launcher registered current.
+        std::env::set_var("TMUX", "/private/tmp/bootstrap-test/default,1,0");
+        std::env::set_var("TMUX_PANE", "%0");
+        std::env::set_var(CALLER_PANE_ENV, "%0");
+        std::env::set_var(CALLER_PROVIDER_ENV, "pi");
+        std::env::set_var(CALLER_ENDPOINT_ENV, "/private/tmp/different-bootstrap/default");
+        let transport = OfflineTransport::new().with_tmux_endpoint("/private/tmp/bootstrap-test/default");
+        let result = quick_start_with_transport_in_workspace(&workspace, &team, None, true, None, &transport).unwrap();
+        assert!(matches!(result, QuickStartReport::PreflightBlocked { .. }), "unexpected outcome: {result:?}");
+        assert_eq!(std::fs::read(&state_path).unwrap(), before);
+        assert!(!workspace.join(".team/team.db").exists());
+        assert!(!crate::model::paths::runtime_spec_path(&workspace, "current").exists());
+        std::fs::remove_dir_all(&workspace).unwrap();
+    }
+
     fn workspace_with_provider(tag: &str, provider: &str) -> PathBuf {
         let path = std::env::temp_dir().join(format!(
             "ta-quick-start-bind-{tag}-{}-{}",
@@ -2863,6 +3066,114 @@ mod fresh_quick_start_leader_binding_tests {
         })
     }
 
+    fn native_persisted_binding(workspace: &Path, socket: &str) -> serde_json::Value {
+        let uuid = "9e1ceba443966bc206a776a7c621e808";
+        json!({
+            "workspace": workspace,
+            "agents": {}, "tasks": [], "session_name": null,
+            "team_owner": complete_owner("%0", "pi", uuid, 1),
+            "leader_receiver": complete_receiver("%0", "pi", uuid, 1, socket)
+        })
+    }
+
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(env)]
+    fn native_persisted_binding_matches_workspace_short_socket_without_weakening_identity() {
+        let hermetic = HermeticTestEnv::enter("native-persisted-socket");
+        let workspace = hermetic.root();
+        let transport = crate::tmux_backend::TmuxBackend::for_workspace(workspace);
+        let endpoint = transport.tmux_endpoint().unwrap();
+        let socket = crate::tmux_backend::socket_path_for_workspace(workspace).unwrap();
+        let state = native_persisted_binding(workspace, socket.to_str().unwrap());
+        let before = state.clone();
+        let pane = PaneId::new("%0");
+        assert_ne!(socket.to_str(), Some(endpoint.as_str()));
+        assert!(persisted_binding_matches_verified_pane(
+            &state, workspace, &pane, Provider::Pi, Some(&endpoint),
+        ));
+        assert_eq!(state, before);
+        assert!(!persisted_binding_matches_verified_pane(
+            &state, workspace, &PaneId::new("%1"), Provider::Pi, Some(&endpoint),
+        ));
+        assert!(!persisted_binding_matches_verified_pane(
+            &state, workspace, &pane, Provider::Codex, Some(&endpoint),
+        ));
+        for endpoint in [None, Some("")] {
+            assert!(!persisted_binding_matches_verified_pane(
+                &state, workspace, &pane, Provider::Pi, endpoint,
+            ));
+        }
+        for (field, value) in [
+            ("/team_owner/pane_id", json!("%1")),
+            ("/leader_receiver/pane_id", json!("%1")),
+            ("/team_owner/provider", json!("codex")),
+            ("/leader_receiver/provider", json!("codex")),
+            ("/team_owner/owner_epoch", json!(0)),
+            ("/leader_receiver/owner_epoch", json!(2)),
+            ("/team_owner/leader_session_uuid", json!("")),
+            ("/leader_receiver/leader_session_uuid", json!("foreign")),
+            ("/leader_receiver/status", json!("pending")),
+            ("/leader_receiver/mode", json!("external")),
+            ("/leader_receiver/tmux_socket", json!(null)),
+            ("/leader_receiver/tmux_socket", json!("")),
+            ("/workspace", json!(workspace.join("foreign"))),
+        ] {
+            let mut conflict = state.clone();
+            *conflict.pointer_mut(field).unwrap() = value;
+            assert!(!persisted_binding_matches_verified_pane(
+                &conflict, workspace, &pane, Provider::Pi, Some(&endpoint),
+            ), "conflicting {field} must refuse");
+        }
+        let mut unauthorized = state.clone();
+        unauthorized["leader_receiver"]["authorized_team_workspace"] =
+            json!(workspace.join("foreign"));
+        assert!(!persisted_binding_matches_verified_pane(
+            &unauthorized, workspace, &pane, Provider::Pi, Some(&endpoint),
+        ));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(env)]
+    fn native_persisted_binding_rejects_same_socket_basename_in_foreign_root() {
+        let hermetic = HermeticTestEnv::enter("native-persisted-foreign-root");
+        let workspace = hermetic.root();
+        let transport = crate::tmux_backend::TmuxBackend::for_workspace(workspace);
+        let endpoint = transport.tmux_endpoint().unwrap();
+        let foreign_socket = workspace.join("foreign-socket-root").join(&endpoint);
+        let state = native_persisted_binding(workspace, foreign_socket.to_str().unwrap());
+        assert_eq!(foreign_socket.file_name().unwrap().to_str(), Some(endpoint.as_str()));
+        assert!(!persisted_binding_matches_verified_pane(
+            &state, workspace, &PaneId::new("%0"), Provider::Pi, Some(&endpoint),
+        ));
+        assert!(!quick_start_tmux_endpoints_match(
+            foreign_socket.to_str().unwrap(), "default",
+        ));
+        assert!(!quick_start_tmux_endpoints_match(
+            foreign_socket.to_str().unwrap(), "",
+        ));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(env)]
+    fn native_persisted_binding_matches_full_socket_path_symlink_alias() {
+        let hermetic = HermeticTestEnv::enter("native-persisted-path-alias");
+        let workspace = hermetic.root();
+        let root = workspace.join("socket-root");
+        std::fs::create_dir_all(&root).unwrap();
+        let alias = workspace.join("socket-alias");
+        std::os::unix::fs::symlink(&root, &alias).unwrap();
+        let socket = root.join("ta-native.sock");
+        std::fs::write(&socket, "fixture endpoint; no tmux server").unwrap();
+        let state = native_persisted_binding(workspace, socket.to_str().unwrap());
+        assert!(persisted_binding_matches_verified_pane(
+            &state, workspace, &PaneId::new("%0"), Provider::Pi,
+            alias.join("ta-native.sock").to_str(),
+        ));
+    }
+
     fn commit_fresh_binding(
         workspace: &Path,
         owner: &serde_json::Value,

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

@@ -133,7 +133,7 @@ pub fn launch_with_transport_in_workspace(
     // 所有角色都未声明 dangerously_skip_permissions=true → 写 warning 事件不阻塞。
     // TODO(0.6.0): remove(0.6.0 彻底删源头 A 后此警示无意义)。
     emit_dangerous_flag_no_role_declared_warning(workspace, &spec);
-    phase_timer.emit(workspace, "launch.phase", "compile_spec");
+    phase_timer.emit(workspace, "launch.phase", super::restart::LifecyclePhase::CompileSpec);
     let session_name = spec_session_name(&spec);
     if !dry_run && transport_has_session(transport, &session_name) {
         return Err(LifecycleError::SessionConflict(format!(
@@ -145,7 +145,7 @@ pub fn launch_with_transport_in_workspace(
     let started = if dry_run {
         Vec::new()
     } else {
-        phase_timer.emit(workspace, "launch.phase", "spawn_all");
+        phase_timer.emit(workspace, "launch.phase", super::restart::LifecyclePhase::SpawnAll);
         let started = spawn_agents(workspace, spec_path, &spec, &session_name, transport)?;
         persist_spawn_agent_state(
             workspace,

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

@@ -31,6 +31,7 @@ use crate::lifecycle::LifecycleError;
 use crate::model::enums::{AuthMode, Provider};
 use crate::model::yaml::Value as YamlValue;
 use crate::provider::{McpConfig, ProviderCommandOverrides, ProviderProfileLaunch};
+use crate::provider::command_helpers::append_env_pair;
 
 const COMPATIBLE_NETWORK_ENV_KEYS: &[&str] = &[
     "HTTPS_PROXY",
@@ -463,40 +464,26 @@ fn provider_env_exports(
     }
     match provider {
         Provider::Claude | Provider::ClaudeCode => {
-            if let Some(value) = value_or_alternate(values, "ANTHROPIC_BASE_URL", "BASE_URL") {
-                exports.insert("ANTHROPIC_BASE_URL".to_string(), value.to_string());
-            }
+            append_env_pair(&mut exports, "ANTHROPIC_BASE_URL", value_or_alternate(values, "ANTHROPIC_BASE_URL", "BASE_URL"));
             if auth_mode == AuthMode::OfficialApi {
-                if let Some(value) = value_or_alternate(values, "ANTHROPIC_API_KEY", "API_KEY") {
-                    exports.insert("ANTHROPIC_API_KEY".to_string(), value.to_string());
-                }
+                append_env_pair(&mut exports, "ANTHROPIC_API_KEY", value_or_alternate(values, "ANTHROPIC_API_KEY", "API_KEY"));
             }
-            if let Some(value) = value_or_alternate(values, "ANTHROPIC_AUTH_TOKEN", "AUTH_TOKEN")
+            append_env_pair(&mut exports, "ANTHROPIC_AUTH_TOKEN", value_or_alternate(values, "ANTHROPIC_AUTH_TOKEN", "AUTH_TOKEN")
                 .or_else(|| {
                     (auth_mode == AuthMode::CompatibleApi)
                         .then(|| value_or_alternate(values, "ANTHROPIC_API_KEY", "API_KEY"))
                         .flatten()
-                })
-            {
-                exports.insert("ANTHROPIC_AUTH_TOKEN".to_string(), value.to_string());
-            }
-            if let Some(value) = profile_model(values) {
-                exports.insert("ANTHROPIC_MODEL".to_string(), value.to_string());
-            }
+                }));
+            append_env_pair(&mut exports, "ANTHROPIC_MODEL", profile_model(values));
         }
         Provider::Codex => {
-            if let Some(value) = value_or_alternate(values, "OPENAI_API_KEY", "API_KEY") {
-                exports.insert("TEAM_AGENT_PROVIDER_API_KEY".to_string(), value.to_string());
-                exports.insert("OPENAI_API_KEY".to_string(), value.to_string());
-            }
-            if let Some(value) = values.get("BASE_URL").filter(|value| !value.is_empty()) {
-                exports.insert("OPENAI_BASE_URL".to_string(), value.to_string());
-            }
+            let key = value_or_alternate(values, "OPENAI_API_KEY", "API_KEY");
+            append_env_pair(&mut exports, "TEAM_AGENT_PROVIDER_API_KEY", key);
+            append_env_pair(&mut exports, "OPENAI_API_KEY", key);
+            append_env_pair(&mut exports, "OPENAI_BASE_URL", values.get("BASE_URL").filter(|value| !value.is_empty()).map(String::as_str));
         }
         Provider::GeminiCli => {
-            if let Some(value) = value_or_alternate(values, "GEMINI_API_KEY", "API_KEY") {
-                exports.insert("GEMINI_API_KEY".to_string(), value.to_string());
-            }
+            append_env_pair(&mut exports, "GEMINI_API_KEY", value_or_alternate(values, "GEMINI_API_KEY", "API_KEY"));
         }
         // C-A-4 cr verdict v2 — copilot BYOK(== compatible_api 档,help-providers 原文
         // "GitHub authentication is not required" when COPILOT_PROVIDER_BASE_URL set):
@@ -506,28 +493,14 @@ fn provider_env_exports(
         // Subscription/OfficialApi 不导出 COPILOT_PROVIDER_*(避免误改 auth 通道)。
         Provider::Copilot => {
             if auth_mode == AuthMode::CompatibleApi {
-                if let Some(value) =
-                    value_or_alternate(values, "COPILOT_PROVIDER_BASE_URL", "BASE_URL")
-                {
-                    exports.insert("COPILOT_PROVIDER_BASE_URL".to_string(), value.to_string());
-                }
-                if let Some(value) =
-                    value_or_alternate(values, "COPILOT_PROVIDER_TYPE", "PROVIDER_TYPE")
-                {
-                    exports.insert("COPILOT_PROVIDER_TYPE".to_string(), value.to_string());
-                }
-                if let Some(value) =
-                    value_or_alternate(values, "COPILOT_PROVIDER_API_KEY", "API_KEY")
-                {
-                    exports.insert("COPILOT_PROVIDER_API_KEY".to_string(), value.to_string());
-                }
-                if let Some(value) =
-                    value_or_alternate(values, "COPILOT_PROVIDER_WIRE_API", "WIRE_API")
-                {
-                    exports.insert("COPILOT_PROVIDER_WIRE_API".to_string(), value.to_string());
-                }
-                if let Some(value) = value_or_alternate(values, "COPILOT_MODEL", "MODEL") {
-                    exports.insert("COPILOT_MODEL".to_string(), value.to_string());
+                for (key, alternate) in [
+                    ("COPILOT_PROVIDER_BASE_URL", "BASE_URL"),
+                    ("COPILOT_PROVIDER_TYPE", "PROVIDER_TYPE"),
+                    ("COPILOT_PROVIDER_API_KEY", "API_KEY"),
+                    ("COPILOT_PROVIDER_WIRE_API", "WIRE_API"),
+                    ("COPILOT_MODEL", "MODEL"),
+                ] {
+                    append_env_pair(&mut exports, key, value_or_alternate(values, key, alternate));
                 }
             }
         }
@@ -539,6 +512,45 @@ fn provider_env_exports(
     exports
 }
 
+#[cfg(test)]
+mod append_env_contract {
+    use super::*;
+
+    #[test]
+    fn profile_append_keeps_native_keys_alternates_and_auth_gates() {
+        let values: BTreeMap<String, String> = [
+            ("API_KEY", "dummy"), ("BASE_URL", " raw\nbase "),
+            ("AUTH_TOKEN", "dummy-token"), ("MODEL", " raw model "),
+            ("PROVIDER_TYPE", "custom"), ("WIRE_API", "responses"),
+            ("OPENAI_API_KEY", "native-dummy"),
+        ].into_iter().map(|(k, v)| (k.to_string(), v.to_string())).collect();
+        let map = |pairs: &[(&str, &str)]| -> BTreeMap<String, String> {
+            pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect()
+        };
+        for provider in [Provider::Claude, Provider::ClaudeCode] {
+            assert_eq!(provider_env_exports(provider, AuthMode::OfficialApi, &values), map(&[
+                ("ANTHROPIC_BASE_URL", " raw\nbase "), ("ANTHROPIC_API_KEY", "dummy"),
+                ("ANTHROPIC_AUTH_TOKEN", "dummy-token"), ("ANTHROPIC_MODEL", " raw model "),
+            ]));
+        }
+        assert_eq!(provider_env_exports(Provider::Codex, AuthMode::CompatibleApi, &values), map(&[
+            ("TEAM_AGENT_PROVIDER_API_KEY", "native-dummy"), ("OPENAI_API_KEY", "native-dummy"),
+            ("OPENAI_BASE_URL", " raw\nbase "),
+        ]));
+        assert_eq!(provider_env_exports(Provider::GeminiCli, AuthMode::OfficialApi, &values), map(&[("GEMINI_API_KEY", "dummy")]));
+        assert_eq!(provider_env_exports(Provider::Copilot, AuthMode::CompatibleApi, &values), map(&[
+            ("COPILOT_PROVIDER_BASE_URL", " raw\nbase "), ("COPILOT_PROVIDER_TYPE", "custom"),
+            ("COPILOT_PROVIDER_API_KEY", "dummy"), ("COPILOT_PROVIDER_WIRE_API", "responses"),
+            ("COPILOT_MODEL", " raw model "),
+        ]));
+        assert!(provider_env_exports(Provider::Copilot, AuthMode::OfficialApi, &values).is_empty());
+        for provider in crate::provider::wire::all_providers() {
+            assert!(provider_env_exports(*provider, AuthMode::Subscription, &values).is_empty());
+            assert!(provider_env_exports(*provider, AuthMode::CompatibleApi, &BTreeMap::new()).is_empty());
+        }
+    }
+}
+
 /// ---
 /// purpose: 给出该 provider 与 auth_mode 下必须从子进程环境里清掉的变量名集
 /// returns: 变量名集合；claude 系清掉会让子进程并入父会话的那组标识