@team-agent/installer 0.5.77 → 0.5.80

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

@@ -116,12 +116,357 @@ pub(super) fn quick_start_session_capture_incomplete_agents(
 /// ---
 /// Host registry is the deliverability authority. Workspace `state.json`
 /// is only a copy. Detection failure is unbound, never attached.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LeaderBindingClass {
+    Attached,
+    IndexMissing,
+    Unknown,
+    Unbound,
+}
+
+impl LeaderBindingClass {
+    pub fn issue_id(self) -> &'static str {
+        match self {
+            Self::Attached => "leader_receiver_attached",
+            Self::IndexMissing => "leader_registry_index_missing",
+            Self::Unknown => "leader_binding_unknown",
+            Self::Unbound => "leader_receiver_unbound",
+        }
+    }
+
+    pub fn repair(self) -> &'static str {
+        match self {
+            Self::Attached => "",
+            Self::IndexMissing => {
+                "publish the leader registry index for the selected team; do not claim-leader"
+            }
+            Self::Unknown => {
+                "inspect the selected-team registry file and live leader channel; do not claim-leader"
+            }
+            Self::Unbound => "team-agent claim-leader --confirm --json",
+        }
+    }
+}
+
+pub fn selected_team_leader_receiver<'a>(
+    state: &'a serde_json::Value,
+    team_key: &str,
+) -> Option<&'a serde_json::Value> {
+    if let Some(teams) = state.get("teams").and_then(serde_json::Value::as_object) {
+        if let Some(team) = teams.get(team_key) {
+            return team.get("leader_receiver");
+        }
+    }
+    state.get("leader_receiver")
+}
+
+fn owner_record<'a>(state: &'a serde_json::Value, team_key: &str) -> Option<&'a serde_json::Value> {
+    let owner = if let Some(team) = state
+        .get("teams")
+        .and_then(serde_json::Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+    {
+        team.get("team_owner")
+    } else {
+        state.get("team_owner")
+    }?;
+    owner.as_object().map(|_| owner)
+}
+
+fn canonical_identity_aligned(
+    workspace: &Path,
+    team_key: &str,
+    state: &serde_json::Value,
+    receiver: &serde_json::Value,
+    entry: &crate::leader::registry::LeaderRegistryEntry,
+) -> bool {
+    let Some(owner) = owner_record(state, team_key) else {
+        return false;
+    };
+    let owner_pane = owner.get("pane_id").and_then(serde_json::Value::as_str);
+    let receiver_pane = receiver.get("pane_id").and_then(serde_json::Value::as_str);
+    let owner_epoch = owner.get("owner_epoch").and_then(serde_json::Value::as_u64);
+    let receiver_epoch = receiver
+        .get("owner_epoch")
+        .and_then(serde_json::Value::as_u64);
+    let channel_pane = entry
+        .channel
+        .get("pane_id")
+        .and_then(serde_json::Value::as_str)
+        .or_else(|| entry.channel.get("pane").and_then(serde_json::Value::as_str));
+    entry.team_key == team_key
+        && entry.status == "attached"
+        && receiver.get("status").and_then(serde_json::Value::as_str) == Some("attached")
+        && owner_pane == receiver_pane
+        && owner_pane.is_some()
+        && owner_epoch == receiver_epoch
+        && owner_epoch == Some(entry.owner_epoch)
+        && channel_pane.is_none_or(|pane| Some(pane) == owner_pane)
+        && crate::leader::registry::workspace_hash(workspace) == entry.workspace_hash
+        && {
+            let receiver_socket = receiver
+                .get("tmux_socket")
+                .and_then(serde_json::Value::as_str);
+            let channel_socket = entry
+                .channel
+                .get("tmux_socket")
+                .and_then(serde_json::Value::as_str);
+            channel_socket.is_none_or(|socket| Some(socket) == receiver_socket)
+        }
+}
+
+pub fn classify_leader_binding(workspace: &Path, team_key: &str) -> LeaderBindingClass {
+    let state = match load_runtime_state(workspace) {
+        Ok(state) => state,
+        Err(_) => return LeaderBindingClass::Unknown,
+    };
+    let receiver = selected_team_leader_receiver(&state, team_key);
+    let transport: Box<dyn crate::transport::Transport> = match receiver
+        .and_then(|value| value.get("tmux_socket"))
+        .and_then(serde_json::Value::as_str)
+        .filter(|endpoint| !endpoint.is_empty() && *endpoint != "default")
+    {
+        Some(endpoint) => crate::transport_factory::leader_endpoint_transport(endpoint),
+        None => return classify_leader_binding_at(workspace, team_key, &state, None),
+    };
+    classify_leader_binding_at(workspace, team_key, &state, Some(transport.as_ref()))
+}
+
+pub(crate) fn classify_leader_binding_at(
+    workspace: &Path,
+    team_key: &str,
+    state: &serde_json::Value,
+    transport: Option<&dyn crate::transport::Transport>,
+) -> LeaderBindingClass {
+    let registry = registry_deliverability(workspace, team_key);
+    let receiver = selected_team_leader_receiver(state, team_key);
+    let receiver_attached = receiver
+        .and_then(|value| value.get("status"))
+        .and_then(serde_json::Value::as_str)
+        == Some("attached");
+    let has_owner = owner_record(state, team_key).is_some();
+    match registry {
+        RegistryDeliverability::Undecidable => LeaderBindingClass::Unknown,
+        RegistryDeliverability::Attached => {
+            let Some(receiver) = receiver else {
+                return LeaderBindingClass::Unknown;
+            };
+            let dir = crate::leader::registry::registry_dir();
+            let entry = dir.and_then(|dir| {
+                let path = dir.join(format!(
+                    "{}__{team_key}.json",
+                    crate::leader::registry::workspace_hash(workspace)
+                ));
+                std::fs::read_to_string(path)
+                    .ok()
+                    .and_then(|text| {
+                        serde_json::from_str::<crate::leader::registry::LeaderRegistryEntry>(&text)
+                            .ok()
+                    })
+            });
+            let Some(entry) = entry else {
+                return LeaderBindingClass::Unknown;
+            };
+            if !canonical_identity_aligned(workspace, team_key, state, receiver, &entry) {
+                return LeaderBindingClass::Unknown;
+            }
+            let Some(transport) = transport else {
+                return LeaderBindingClass::Unknown;
+            };
+            match crate::messaging::leader_channel::resolve_live_leader_channel(
+                workspace, receiver, transport,
+            ) {
+                crate::messaging::leader_channel::LeaderChannelResolution::Live(_) => {
+                    LeaderBindingClass::Attached
+                }
+                _ => LeaderBindingClass::Unknown,
+            }
+        }
+        RegistryDeliverability::Unbound if has_owner || receiver_attached => {
+            LeaderBindingClass::IndexMissing
+        }
+        RegistryDeliverability::Unbound => LeaderBindingClass::Unbound,
+    }
+}
+
 pub fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool {
-    match registry_deliverability(workspace, team_key) {
-        RegistryDeliverability::Attached => {}
-        RegistryDeliverability::Unbound | RegistryDeliverability::Undecidable => return false,
+    classify_leader_binding(workspace, team_key) == LeaderBindingClass::Attached
+}
+
+#[cfg(test)]
+mod claim_rework_class_tests {
+    use super::*;
+    use crate::transport::test_support::OfflineTransport;
+    use crate::transport::{PaneId, PaneInfo, SessionName};
+    use serde_json::json;
+
+    fn isolated() -> (std::path::PathBuf, std::path::PathBuf, Option<std::ffi::OsString>) {
+        let root = std::env::temp_dir().join(format!(
+            "ta-class-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        let home = root.join("home");
+        let workspace = root.join("ws");
+        std::fs::create_dir_all(&home).unwrap();
+        std::fs::create_dir_all(&workspace).unwrap();
+        let previous = std::env::var_os("HOME");
+        std::env::set_var("HOME", &home);
+        (root, workspace, previous)
+    }
+
+    fn restore_home(previous: Option<std::ffi::OsString>, root: &Path) {
+        match previous {
+            Some(home) => std::env::set_var("HOME", home),
+            None => std::env::remove_var("HOME"),
+        }
+        let _ = std::fs::remove_dir_all(root);
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn classify_bad_registry_json_is_unknown() {
+        let (root, workspace, previous) = isolated();
+        crate::state::persist::save_runtime_state(
+            &workspace,
+            &json!({"teams": {"alpha": {"team_owner": {"pane_id": "%1", "owner_epoch": 1}}}}),
+        )
+        .unwrap();
+        let dir = crate::leader::registry::registry_dir().unwrap();
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join(format!(
+            "{}__alpha.json",
+            crate::leader::registry::workspace_hash(&workspace)
+        ));
+        std::fs::write(&path, "{not json").unwrap();
+        let class = classify_leader_binding(&workspace, "alpha");
+        restore_home(previous, &root);
+        assert_eq!(class, LeaderBindingClass::Unknown);
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn classify_null_owner_is_not_index_missing() {
+        let (root, workspace, previous) = isolated();
+        crate::state::persist::save_runtime_state(
+            &workspace,
+            &json!({"teams": {"alpha": {"team_owner": null}}}),
+        )
+        .unwrap();
+        let class = classify_leader_binding(&workspace, "alpha");
+        restore_home(previous, &root);
+        assert_eq!(class, LeaderBindingClass::Unbound);
+    }
+
+    fn live_pane(workspace: &Path, pane: &str) -> PaneInfo {
+        PaneInfo {
+            pane_id: PaneId::new(pane),
+            session: SessionName::new("s"),
+            window_index: None,
+            window_name: None,
+            pane_index: None,
+            tty: None,
+            current_command: Some("codex".to_string()),
+            current_path: Some(workspace.to_path_buf()),
+            active: true,
+            pane_pid: None,
+            leader_env: Default::default(),
+        }
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn classify_attached_requires_identity_and_live() {
+        let (root, workspace, previous) = isolated();
+        let endpoint = "/tmp/ta-class-live.sock";
+        let state = json!({
+            "teams": {
+                "alpha": {
+                    "team_owner": {"pane_id": "%1", "owner_epoch": 3, "provider": "codex"},
+                    "leader_receiver": {
+                        "status": "attached",
+                        "pane_id": "%1",
+                        "owner_epoch": 3,
+                        "tmux_socket": endpoint
+                    }
+                }
+            }
+        });
+        crate::state::persist::save_runtime_state(&workspace, &state).unwrap();
+        let outcome = crate::leader::registry::register_binding_from_state_best_effort(
+            &workspace,
+            Some("alpha"),
+            "classify-attached",
+        );
+        assert_eq!(
+            outcome.as_ref().map(|value| value.status),
+            Some("registered")
+        );
+        let transport = OfflineTransport::default()
+            .with_tmux_endpoint(endpoint)
+            .with_targets(vec![live_pane(&workspace, "%1")]);
+        let class = crate::transport_factory::with_leader_endpoint_transport(
+            endpoint,
+            transport,
+            || classify_leader_binding(&workspace, "alpha"),
+        );
+        restore_home(previous, &root);
+        assert_eq!(class, LeaderBindingClass::Attached);
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn classify_registry_socket_mismatch_is_unknown() {
+        let (root, workspace, previous) = isolated();
+        let endpoint = "/tmp/ta-class-live.sock";
+        let state = json!({
+            "teams": {
+                "alpha": {
+                    "team_owner": {"pane_id": "%1", "owner_epoch": 3, "provider": "codex"},
+                    "leader_receiver": {
+                        "status": "attached",
+                        "pane_id": "%1",
+                        "owner_epoch": 3,
+                        "tmux_socket": endpoint
+                    }
+                }
+            }
+        });
+        crate::state::persist::save_runtime_state(&workspace, &state).unwrap();
+        let mut entry = crate::leader::registry::build_entry(
+            &workspace,
+            "alpha",
+            "direct_tmux",
+            json!({
+                "pane_id": "%1",
+                "tmux_socket": "/tmp/other-leader.sock"
+            }),
+            3,
+            "mismatch",
+            "2026-01-01T00:00:00Z".to_string(),
+        );
+        entry.status = "attached".to_string();
+        let dir = crate::leader::registry::registry_dir().unwrap();
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join(format!(
+            "{}__alpha.json",
+            crate::leader::registry::workspace_hash(&workspace)
+        ));
+        std::fs::write(&path, serde_json::to_vec(&entry).unwrap()).unwrap();
+        let transport = OfflineTransport::default()
+            .with_tmux_endpoint(endpoint)
+            .with_targets(vec![live_pane(&workspace, "%1")]);
+        let class = crate::transport_factory::with_leader_endpoint_transport(
+            endpoint,
+            transport,
+            || classify_leader_binding(&workspace, "alpha"),
+        );
+        restore_home(previous, &root);
+        assert_eq!(class, LeaderBindingClass::Unknown);
     }
-    load_runtime_state(workspace).is_ok()
 }
 
 enum RegistryDeliverability {

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

@@ -322,18 +322,18 @@ pub(super) fn spawn_agents(
         if matches!(provider, Provider::CursorAgent) {
             refuse_second_cursor_occupant(workspace, agent_id_raw, Some(spec))?;
             apply_cursor_agent_rules_overlay(workspace, agent_id_raw, system_prompt.as_str())?;
-            apply_cursor_mcp_overlay(workspace, &mcp_config)?;
-            let project = if crate::lifecycle::launch::cursor_mcp_isolation_enabled() {
-                Some(crate::lifecycle::launch::cursor_mcp_project_dir(
-                    workspace,
-                    agent_id_raw,
-                )?)
-            } else {
-                None
-            };
-            enable_cursor_workspace_mcp(workspace, project.as_deref())?;
+            let project = crate::lifecycle::launch::prepare_cursor_seat_mcp(
+                workspace,
+                agent_id_raw,
+                &mcp_config,
+            )?;
+            enable_cursor_workspace_mcp_with_profile(
+                workspace,
+                project.as_deref(),
+                Some(&profile_launch),
+            )?;
             apply_cursor_spawn_workspace_pointers(&mut plan.argv, workspace, agent_id_raw)?;
-            let proxy = apply_cursor_subscription_proxy_env(&mut env);
+            let proxy = apply_cursor_subscription_proxy_env_with_profile(&mut env, &profile_launch);
             let event_log = crate::event_log::EventLog::new(workspace);
             let _ = event_log.write(
                 "provider.cursor.proxy_presence",

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

@@ -203,7 +203,7 @@ pub(super) fn seed_launched_owner_from_env(
 ///   lookup_pane_provider: 由 pane 反查 provider 的函数，便于测试替换
 /// returns: true 表示已写入 owner 记录
 /// ---
-pub(super) fn seed_launched_owner_from_caller_with_provider_lookup(
+pub fn seed_launched_owner_from_caller_with_provider_lookup(
     state: &mut serde_json::Value,
     caller: crate::state::owner_gate::CallerIdentity,
     lookup_pane_provider: impl Fn(&PaneId) -> Option<Provider>,
@@ -227,12 +227,12 @@ pub(super) fn seed_launched_owner_from_caller_with_provider_lookup(
     });
     let mut receiver = serde_json::json!({
         "mode": "direct_tmux",
-        "status": "attached",
+        "status": "pending",
         "pane_id": owner.get("pane_id").cloned().unwrap_or(serde_json::Value::Null),
         "pane": owner.get("pane_id").cloned().unwrap_or(serde_json::Value::Null),
         "leader_session_uuid": owner.get("leader_session_uuid").cloned().unwrap_or(serde_json::Value::Null),
         "owner_epoch": owner_epoch,
-        "discovery": "quick_start",
+        "discovery": "quick_start_seed",
     });
     if let Some(provider) = provider.as_ref() {
         if let Some(owner) = owner.as_object_mut() {
@@ -452,6 +452,38 @@ pub fn worker_session_name_pub(spec: &Value) -> SessionName {
     spec_session_name(spec)
 }
 
+#[cfg(test)]
+mod claim_rework_seed_tests {
+    use super::*;
+    use crate::state::owner_gate::CallerIdentity;
+
+    #[test]
+    fn seed_writes_pending_receiver_not_attached() {
+        let mut state = serde_json::json!({
+            "session_name": "team-seed",
+            "workspace": "/tmp/claim-rework-seed"
+        });
+        let caller = CallerIdentity {
+            pane_id: "%1".to_string(),
+            provider: "codex".to_string(),
+            machine_fingerprint: "fp".to_string(),
+            leader_session_uuid: "uuid".to_string(),
+            leader_session_uuid_source: "env".to_string(),
+        };
+        assert!(seed_launched_owner_from_caller_with_provider_lookup(
+            &mut state,
+            caller,
+            |_| None
+        ));
+        let status = state
+            .pointer("/teams/team-seed/leader_receiver/status")
+            .or_else(|| state.pointer("/leader_receiver/status"))
+            .and_then(serde_json::Value::as_str);
+        assert_eq!(status, Some("pending"));
+        assert_ne!(status, Some("attached"));
+    }
+}
+
 /// ---
 /// purpose: 取出 spec 里全部 agent id
 /// returns: 按 spec 顺序的 agent id，无 id 字段的条目被跳过

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

@@ -505,6 +505,22 @@ pub fn apply_cursor_subscription_proxy_env(
     }
 }
 
+pub(crate) fn apply_cursor_subscription_proxy_env_with_profile(
+    env: &mut BTreeMap<String, String>,
+    profile_launch: &crate::provider::ProviderProfileLaunch,
+) -> CursorProxyPresence {
+    if crate::lifecycle::profile_launch::cursor_subscription_direct_mode(profile_launch) {
+        for key in &profile_launch.env_unset {
+            env.remove(key);
+        }
+        return CursorProxyPresence {
+            https_proxy: false,
+            no_proxy: env.keys().any(|key| key.eq_ignore_ascii_case("NO_PROXY")),
+        };
+    }
+    apply_cursor_subscription_proxy_env(env)
+}
+
 /// ---
 /// purpose: 把 profile 推出的环境清除与覆盖套用到 spawn 环境上
 /// params:

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

@@ -210,6 +210,8 @@ pub fn launch_with_transport_in_workspace(
         routes,
         permissions,
         leader_receiver_attached: false,
+        leader_bind_stage: None,
+        leader_bind_reason: None,
         session_capture_incomplete_agents: Vec::new(),
     })
 }
@@ -309,6 +311,20 @@ pub(crate) use mcp_config::{
 
 pub(crate) mod pi_mcp;
 
+pub(crate) fn run_pi_catalog_preflight(
+    agents_dir: &std::path::Path,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
+) -> Result<(), crate::lifecycle::LifecycleError> {
+    crate::compiler::preflight_pi_models_in_team_with(agents_dir, discover).map_err(|error| {
+        crate::lifecycle::LifecycleError::PiModelPreflight {
+            requested: error.requested,
+            candidates: error.candidates,
+            action: error.action,
+            not_ready: error.not_ready,
+        }
+    })
+}
+
 mod cursor_mcp_iso;
 pub use cursor_mcp_iso::{
     cursor_mcp_isolation_enabled, cursor_mcp_json_path, cursor_mcp_project_dir,
@@ -317,9 +333,11 @@ pub use cursor_mcp_iso::{
 mod cursor_mcp;
 pub use cursor_mcp::{
     apply_cursor_mcp_overlay, apply_cursor_spawn_workspace_pointers,
-    apply_cursor_workspace_physical_path, cursor_mcp_enable_argv, enable_cursor_workspace_mcp,
-    physical_workspace_path, refuse_second_cursor_occupant,
+    apply_cursor_workspace_physical_path, cursor_mcp_enable_argv, cursor_mcp_enable_working_dir,
+    enable_cursor_workspace_mcp, enable_cursor_workspace_mcp_with_profile, physical_workspace_path,
+    prepare_cursor_seat_mcp, refuse_second_cursor_occupant,
 };
+pub(crate) use cursor_mcp::apply_cursor_mcp_enable_profile_env;
 
 mod cursor_create_chat;
 
@@ -327,7 +345,8 @@ mod worker_env;
 pub(super) use worker_env::*;
 pub(crate) use worker_env::{
     apply_copilot_instructions_overlay, apply_cursor_agent_rules_overlay,
-    apply_mcp_auto_approval_env, apply_profile_launch_env, auth_mode_env_value,
+    apply_cursor_subscription_proxy_env_with_profile, apply_mcp_auto_approval_env,
+    apply_profile_launch_env, auth_mode_env_value,
     fill_spawn_placeholders, fill_spawn_placeholders_full, inherited_env_with_team_overrides,
     persist_command_plan_state, spawn_timestamp,
 };
@@ -358,7 +377,10 @@ pub(crate) use quick_start_transport::{
 };
 
 pub mod readiness;
-pub use readiness::launched_team_receiver_is_attached;
+pub use readiness::{
+    classify_leader_binding, launched_team_receiver_is_attached, selected_team_leader_receiver,
+    LeaderBindingClass,
+};
 pub(super) use readiness::*;
 
 mod add_agent;
@@ -388,14 +410,15 @@ pub(super) use ownership::*;
 pub(crate) use ownership::{ensure_owner_allowed, ensure_owner_allowed_for_state, state_path};
 
 pub mod spec_state;
-pub use spec_state::worker_session_name_pub;
+pub use spec_state::{
+    seed_launched_owner_from_caller_with_provider_lookup, worker_session_name_pub,
+};
 pub(crate) use spec_state::{
     effective_runtime_config_for_worker_spawn, effective_runtime_config_for_worker_spawn_json,
 };
 use spec_state::{
     env_nonempty, has_positive_caller_leader_env, initial_runtime_state,
-    override_spec_display_backend, override_spec_runtime_str,
-    seed_launched_owner_from_caller_with_provider_lookup, seed_launched_owner_from_env,
+    override_spec_display_backend, override_spec_runtime_str, seed_launched_owner_from_env,
     spec_agent_values, spec_agents, spec_default_assignee, spec_routes, spec_session_name,
     spec_tasks_json, team_workspace, yaml_value_to_json,
 };

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

@@ -46,6 +46,26 @@ const COMPATIBLE_NETWORK_ENV_KEYS: &[&str] = &[
     "REQUESTS_CA_BUNDLE",
 ];
 
+// Cursor subscription direct mode removes only proxy URL inputs. NO_PROXY is
+// deliberately retained: it is a bypass list, not a proxy endpoint, and the
+// observed catalog failure came from the GLOBAL_AGENT proxy URL settings.
+const CURSOR_DIRECT_PROXY_ENV_KEYS: &[&str] = &[
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "ALL_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "all_proxy",
+    "GLOBAL_AGENT_HTTPS_PROXY",
+    "GLOBAL_AGENT_HTTP_PROXY",
+];
+
+pub(crate) fn cursor_subscription_direct_mode(profile_launch: &ProviderProfileLaunch) -> bool {
+    CURSOR_DIRECT_PROXY_ENV_KEYS
+        .iter()
+        .all(|key| profile_launch.env_unset.contains(*key))
+}
+
 #[derive(Debug, Clone)]
 pub(crate) struct ProfileValues {
     pub(crate) path: PathBuf,
@@ -234,6 +254,15 @@ fn prepare_profile_launch(
             env_overlay.remove(*key);
         }
     }
+    if agent.provider == Provider::CursorAgent
+        && agent.auth_mode == AuthMode::Subscription
+        && profile_proxy_mode(&loaded.values) == "direct"
+    {
+        for key in CURSOR_DIRECT_PROXY_ENV_KEYS {
+            env_unset.insert((*key).to_string());
+            env_overlay.remove(*key);
+        }
+    }
 
     let command_overrides = provider_command_overrides(&agent, &loaded.values);
     write_runtime_env_file(workspace, &agent.id, &env_overlay, &env_unset)?;
@@ -353,6 +382,12 @@ fn validate_profile(
     profile: &str,
     loaded: &ProfileValues,
 ) -> Result<(), LifecycleError> {
+    let proxy_mode = profile_proxy_mode(&loaded.values);
+    if !matches!(proxy_mode.as_str(), "direct" | "inherit") {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "profile {profile} has invalid proxy mode {proxy_mode}; expected direct|inherit"
+        )));
+    }
     if loaded
         .values
         .get("AUTH_MODE")
@@ -481,9 +516,8 @@ fn provider_env_exports(
                 }
             }
         }
-        // grok/cursor_agent 一期无 profile exports（subscription 已登录态）。
-        // Cursor 订阅席的代理透传不在这里：profile 只服务 compatible-api。
-        // 订阅路径见 apply_cursor_subscription_proxy_env（只记有无，不记值）。
+        // grok/cursor_agent 一期无 credential/profile exports（subscription 已登录态）。
+        // Cursor 订阅席默认继承代理；PROXY_MODE=direct 的局部清除在上方处理。
         Provider::Grok | Provider::CursorAgent | Provider::Pi => {}
         Provider::Fake => {}
     }