@team-agent/installer 0.5.120 → 0.5.121

package/crates/team-agent/src/mcp_server/readiness_tests.rs

@@ -0,0 +1,242 @@
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use super::*;
+use crate::model::enums::Provider;
+use crate::transport::{PaneId, SessionName};
+use serde_json::json;
+use std::collections::BTreeMap;
+use std::os::unix::fs::PermissionsExt;
+
+struct Case {
+    ws: PathBuf,
+    state: Value,
+    target: Target,
+    panes: Vec<PaneInfo>,
+    started: DateTime<Utc>,
+}
+
+impl Case {
+    fn new() -> Self {
+        let ws = std::env::temp_dir().join(format!(
+            "ta-mcp-handshake-{}-{}",
+            std::process::id(),
+            crate::provider::adapter::next_session_token()
+        ));
+        std::fs::create_dir(&ws).unwrap();
+        let ws = ws.canonicalize().unwrap();
+        let config = ws.join(".team/runtime/mcp/worker.json");
+        std::fs::create_dir_all(config.parent().unwrap()).unwrap();
+        let executable = std::env::current_exe().unwrap().canonicalize().unwrap();
+        std::fs::write(&config, serde_json::to_vec(&json!({
+            "mcpServers": {"team_orchestrator": {
+                "command": executable,
+                "env": {"TEAM_AGENT_WORKSPACE": ws, "TEAM_AGENT_ID": "worker", "TEAM_AGENT_OWNER_TEAM_ID": "owner"}
+            }}
+        })).unwrap()).unwrap();
+        // Existing managed configurations are 0644, unlike private receipts.
+        std::fs::set_permissions(&config, std::fs::Permissions::from_mode(0o644)).unwrap();
+        let carrier = crate::platform::process::current_parent_pid().unwrap();
+        assert!(carrier > 1);
+        let started = Utc::now();
+        let state = json!({"agents": {"worker": {
+            "provider": "cursor_agent", "mcp_config": config,
+            "spawned_at": (started - chrono::Duration::seconds(10)).to_rfc3339(),
+            "pane_id": "%1", "pane_pid": carrier
+        }}});
+        let panes = vec![PaneInfo {
+            pane_id: PaneId::new("%1"),
+            session: SessionName::new("owned"),
+            window_index: None,
+            window_name: None,
+            pane_index: None,
+            tty: None,
+            current_command: None,
+            current_path: None,
+            active: true,
+            pane_pid: Some(carrier),
+            leader_env: BTreeMap::new(),
+        }];
+        Self {
+            ws,
+            state,
+            target: Target::Pane(PaneId::new("%1")),
+            panes,
+            started,
+        }
+    }
+
+    fn path(&self) -> PathBuf {
+        self.ws
+            .join(".team/runtime/mcp-handshakes")
+            .join(format!("{}.json", key("owner", "worker")))
+    }
+
+    fn publish(&self) {
+        let outcome = publish(&self.ws, "owner", "worker", self.started);
+        if outcome.is_err() {
+            for event in crate::event_log::EventLog::new(&self.ws).tail(0).unwrap() {
+                if event["event"] == "mcp.handshake_evidence_failed" {
+                    eprintln!("CONTROLLED_MCP_HANDSHAKE_FAILURE {event}");
+                }
+            }
+        }
+        outcome.unwrap();
+    }
+
+    fn admission(&self) -> Result<Option<Admission>> {
+        preflight(&self.ws, Some("owner"), "worker", &self.state)
+    }
+}
+
+impl Drop for Case {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.ws);
+    }
+}
+
+#[test]
+fn missing_handshake_defers_then_a_live_scoped_receipt_admits() {
+    let case = Case::new();
+    assert!(case.admission().is_err());
+    case.publish();
+    let admission = case
+        .admission()
+        .unwrap()
+        .expect("eager client must require a receipt");
+    revalidate(&admission, &case.target, &case.panes).unwrap();
+}
+
+#[test]
+fn receipt_cannot_cross_workspace_owner_or_seat() {
+    let case = Case::new();
+    case.publish();
+    assert!(preflight(&case.ws, None, "worker", &case.state).is_err());
+    assert!(preflight(&case.ws, Some("other"), "worker", &case.state).is_err());
+    let original = std::fs::read(case.path()).unwrap();
+    for field in ["workspace", "owner", "agent"] {
+        let mut value: Value = serde_json::from_slice(&original).unwrap();
+        value[field] = json!("foreign");
+        std::fs::write(case.path(), serde_json::to_vec(&value).unwrap()).unwrap();
+        assert!(case.admission().is_err(), "foreign {field} cannot admit");
+    }
+}
+
+#[test]
+fn malformed_stale_birth_ancestry_and_image_receipts_refuse() {
+    let case = Case::new();
+    case.publish();
+    let original: Value = serde_json::from_slice(&std::fs::read(case.path()).unwrap()).unwrap();
+    let mut changed = Vec::new();
+    let mut v = original.clone();
+    v["schema"] = json!(2);
+    changed.push(v);
+    let mut v = original.clone();
+    v["server"]["identity"]["birth_identity"] = json!("wrong-birth");
+    changed.push(v);
+    let mut v = original.clone();
+    v["server"]["identity"]["executable"] = json!("/not-authorized");
+    changed.push(v);
+    let mut v = original.clone();
+    v["server"]["image"]["inode"] = json!(0);
+    changed.push(v);
+    let mut v = original.clone();
+    v["ancestors"][0]["birth"] = json!("reused-parent");
+    changed.push(v);
+    let mut v = original.clone();
+    v["server"]["parent"] = json!(1);
+    changed.push(v);
+    let mut v = original.clone();
+    v["started_at"] = json!("2000-01-01T00:00:00Z");
+    changed.push(v);
+    for value in changed {
+        std::fs::write(case.path(), serde_json::to_vec(&value).unwrap()).unwrap();
+        assert!(case.admission().is_err());
+    }
+    std::fs::write(case.path(), b"{incomplete").unwrap();
+    assert!(case.admission().is_err());
+}
+
+#[test]
+fn changed_current_target_and_new_spawn_do_not_reuse_a_handshake() {
+    let mut case = Case::new();
+    case.publish();
+    let admission = case.admission().unwrap().unwrap();
+    let mut other = case.panes.clone();
+    other[0].pane_pid = Some(std::process::id());
+    assert!(revalidate(&admission, &case.target, &other).is_err());
+    assert!(revalidate(&admission, &Target::Pane(PaneId::new("%2")), &case.panes).is_err());
+    case.state["agents"]["worker"]["spawned_at"] =
+        json!((Utc::now() + chrono::Duration::seconds(1)).to_rfc3339());
+    assert!(case.admission().is_err());
+}
+
+#[test]
+fn older_helper_cannot_overwrite_a_newer_handshake() {
+    let case = Case::new();
+    case.publish();
+    let original = std::fs::read(case.path()).unwrap();
+    publish(
+        &case.ws,
+        "owner",
+        "worker",
+        case.started - chrono::Duration::seconds(1),
+    )
+    .unwrap();
+    assert_eq!(std::fs::read(case.path()).unwrap(), original);
+}
+
+#[test]
+fn symlink_and_writable_evidence_are_not_adopted_or_overwritten() {
+    let case = Case::new();
+    case.publish();
+    std::fs::set_permissions(case.path(), std::fs::Permissions::from_mode(0o666)).unwrap();
+    assert!(case.admission().is_err());
+    std::fs::remove_file(case.path()).unwrap();
+    let outside = case.ws.join("outside");
+    std::fs::write(&outside, b"untouched").unwrap();
+    std::os::unix::fs::symlink(&outside, case.path()).unwrap();
+    assert!(case.admission().is_err());
+    assert!(publish(&case.ws, "owner", "worker", case.started).is_err());
+    assert_eq!(std::fs::read(outside).unwrap(), b"untouched");
+    assert!(std::fs::symlink_metadata(case.path())
+        .unwrap()
+        .file_type()
+        .is_symlink());
+}
+
+#[test]
+fn config_scope_and_authorized_executable_cannot_be_substituted() {
+    let case = Case::new();
+    case.publish();
+    let path = case.ws.join(".team/runtime/mcp/worker.json");
+    let original: Value = serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
+    for field in [
+        "TEAM_AGENT_ID",
+        "TEAM_AGENT_OWNER_TEAM_ID",
+        "TEAM_AGENT_WORKSPACE",
+    ] {
+        let mut value = original.clone();
+        value["mcpServers"]["team_orchestrator"]["env"][field] = json!("foreign");
+        std::fs::write(&path, serde_json::to_vec(&value).unwrap()).unwrap();
+        assert!(case.admission().is_err());
+    }
+    let mut value = original;
+    value["mcpServers"]["team_orchestrator"]["command"] = json!("/bin/sh");
+    std::fs::write(&path, serde_json::to_vec(&value).unwrap()).unwrap();
+    assert!(case.admission().is_err());
+}
+
+#[test]
+fn fake_and_pi_keep_their_existing_non_eager_or_runtime_registry_admission() {
+    assert!(!crate::provider::get_adapter(Provider::Fake).requires_worker_mcp_handshake());
+    assert!(!crate::provider::get_adapter(Provider::Pi).requires_worker_mcp_handshake());
+    assert!(crate::provider::get_adapter(Provider::CursorAgent).requires_worker_mcp_handshake());
+    let case = Case::new();
+    for provider in ["fake", "pi"] {
+        let mut state = case.state.clone();
+        state["agents"]["worker"]["provider"] = json!(provider);
+        assert!(preflight(&case.ws, Some("owner"), "worker", &state)
+            .unwrap()
+            .is_none());
+    }
+}

package/crates/team-agent/src/mcp_server/wire.rs

@@ -190,17 +190,20 @@ fn run_stdio_loop_inner<R: BufRead, W: Write>(
     report: &mut ServerRunReport,
     marker: &McpServerLifecycleMarker,
 ) -> Result<ServerRunReport, McpError> {
+    let mut initialized = false;
     for line in reader.lines() {
         let line = line?;
         report.requests_read = report.requests_read.saturating_add(1);
-        let (frame, tools_list_success) = handle_stdin_line(tools, &line, report)?;
+        let (frame, response_kind) = handle_stdin_line(tools, &line, report)?;
         if let Some(value) = frame {
             let value = crate::redaction::redact_external_value(&value);
             serde_json::to_writer(&mut *writer, &value)?;
             writer.write_all(b"\n")?;
             writer.flush()?;
-            if tools_list_success {
-                marker.write_tools_list_response_written();
+            match response_kind {
+                ResponseKind::Initialize => initialized = true,
+                ResponseKind::ToolsList => marker.write_tools_list_response_written(initialized),
+                ResponseKind::Other => {}
             }
             report.responses_written = report.responses_written.saturating_add(1);
         }
@@ -209,11 +212,17 @@ fn run_stdio_loop_inner<R: BufRead, W: Write>(
     Ok(report.clone())
 }
 
+enum ResponseKind {
+    Initialize,
+    ToolsList,
+    Other,
+}
+
 fn handle_stdin_line(
     tools: &TeamOrchestratorTools,
     line: &str,
     report: &mut ServerRunReport,
-) -> Result<(Option<Value>, bool), McpError> {
+) -> Result<(Option<Value>, ResponseKind), McpError> {
     let request: Value = match serde_json::from_str(line) {
         Ok(value) => value,
         Err(err) => {
@@ -224,23 +233,28 @@ fn handle_stdin_line(
                     -32700,
                     format!("parse error: {err}"),
                 )),
-                false,
+                ResponseKind::Other,
             ));
         }
     };
     if request.get("jsonrpc").and_then(Value::as_str) == Some("2.0") {
-        let is_tools_list = request.get("method").and_then(Value::as_str) == Some("tools/list");
+        let method = request.get("method").and_then(Value::as_str);
+        let valid_id = request.get("id").is_some_and(|id| id.is_string() || id.is_number());
         match handle_mcp(tools, &request)? {
             Some(response) => {
-                let tools_list_success = is_tools_list && response.error.is_none();
+                let kind = match (method, valid_id && response.error.is_none()) {
+                    (Some("initialize"), true) => ResponseKind::Initialize,
+                    (Some("tools/list"), true) => ResponseKind::ToolsList,
+                    _ => ResponseKind::Other,
+                };
                 if response.error.is_some() {
                     report.error_frames = report.error_frames.saturating_add(1);
                 }
-                Ok((Some(serde_json::to_value(response)?), tools_list_success))
+                Ok((Some(serde_json::to_value(response)?), kind))
             }
             None => {
                 report.notifications_skipped = report.notifications_skipped.saturating_add(1);
-                Ok((None, false))
+                Ok((None, ResponseKind::Other))
             }
         }
     } else {
@@ -251,7 +265,7 @@ fn handle_stdin_line(
                 err.to_envelope()
             }
         };
-        Ok((Some(value), false))
+        Ok((Some(value), ResponseKind::Other))
     }
 }
 
@@ -281,6 +295,7 @@ struct McpServerLifecycleMarker {
     workspace: std::path::PathBuf,
     agent_id: Option<String>,
     owner_team_id: Option<String>,
+    started_at: chrono::DateTime<chrono::Utc>,
     pid: u32,
     ppid: u32,
 }
@@ -291,6 +306,7 @@ impl McpServerLifecycleMarker {
             workspace: workspace.to_path_buf(),
             agent_id: non_empty_env("TEAM_AGENT_ID"),
             owner_team_id: non_empty_env("TEAM_AGENT_OWNER_TEAM_ID"),
+            started_at: chrono::Utc::now(),
             pid: std::process::id(),
             ppid: parent_pid(),
         }
@@ -300,7 +316,7 @@ impl McpServerLifecycleMarker {
         self.write("mcp.server_started", None, None);
     }
 
-    fn write_tools_list_response_written(&self) {
+    fn write_tools_list_response_written(&self, initialized: bool) {
         let _ = EventLog::new(&self.workspace).write(
             "mcp.tools_list_response_written",
             serde_json::json!({
@@ -313,8 +329,17 @@ impl McpServerLifecycleMarker {
                 "ppid": self.ppid,
                 "spawn_epoch": null,
                 "spawn_epoch_source": "unavailable",
+                "initialize_response_flushed": initialized,
             }),
         );
+        #[cfg(unix)]
+        if initialized {
+            if let (Some(owner), Some(agent)) = (&self.owner_team_id, &self.agent_id) {
+                if let Err(reason) = super::readiness::publish(&self.workspace, owner, agent, self.started_at) {
+                    self.write("mcp.handshake_receipt_failed", Some(reason), None);
+                }
+            }
+        }
     }
 
     fn write_exit(&self, reason: &str, error: Option<&str>) {
@@ -725,6 +750,66 @@ mod e23_lifecycle_marker_tests {
         let _ = std::fs::remove_dir_all(&ws);
     }
 
+    #[cfg(unix)]
+    fn run_bound_handshake<W: Write>(ws: &Path, input: &str, writer: &mut W) -> Result<ServerRunReport, McpError> {
+        let marker = McpServerLifecycleMarker {
+            workspace: ws.to_path_buf(), agent_id: Some("worker".into()),
+            owner_team_id: Some("owner".into()), started_at: chrono::Utc::now(),
+            pid: std::process::id(), ppid: parent_pid(),
+        };
+        run_stdio_loop_inner(&TeamOrchestratorTools::new(ws), std::io::Cursor::new(input.as_bytes()),
+            writer, &mut ServerRunReport::default(), &marker)
+    }
+
+    #[cfg(unix)]
+    fn handshake_receipts(ws: &Path) -> usize {
+        std::fs::read_dir(ws.join(".team/runtime/mcp-handshakes"))
+            .map(|files| files.filter_map(Result::ok)
+                .filter(|file| file.path().extension().is_some_and(|ext| ext == "json")).count())
+            .unwrap_or(0)
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn stdio_handshake_receipt_requires_initialize_and_tools_list_flush() {
+        let initialize = r#"{"jsonrpc":"2.0","id":1,"method":"initialize"}"#;
+        let tools = r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#;
+        let invalid_initialize = r#"{"jsonrpc":"2.0","method":"initialize"}"#;
+        let invalid_tools = r#"{"jsonrpc":"2.0","method":"tools/list"}"#;
+        for (tag, requests, expected) in [
+            ("init-only", vec![initialize], 0),
+            ("list-only", vec![tools], 0),
+            ("invalid-init", vec![invalid_initialize, tools], 0),
+            ("invalid-list", vec![initialize, invalid_tools], 0),
+            ("ready", vec![initialize, tools], 1),
+        ] {
+            let ws = marker_ws(tag);
+            let mut output = Vec::new();
+            run_bound_handshake(&ws, &(requests.join("\n") + "\n"), &mut output).unwrap();
+            assert_eq!(handshake_receipts(&ws), expected, "{tag}");
+            let _ = std::fs::remove_dir_all(ws);
+        }
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn stdio_failed_tools_list_flush_cannot_publish_a_handshake() {
+        struct FailSecondFlush(usize);
+        impl Write for FailSecondFlush {
+            fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> { Ok(buf.len()) }
+            fn flush(&mut self) -> std::io::Result<()> {
+                self.0 += 1;
+                if self.0 == 2 { Err(std::io::Error::other("controlled tools/list flush failure")) }
+                else { Ok(()) }
+            }
+        }
+        let ws = marker_ws("handshake-flush-failure");
+        let input = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\"}\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}\n";
+        assert!(run_bound_handshake(&ws, input, &mut FailSecondFlush(0)).is_err());
+        assert_eq!(handshake_receipts(&ws), 0);
+        let _ = std::fs::remove_dir_all(ws);
+    }
+
     #[test]
     fn stdio_loop_writes_started_and_stdin_eof_exit_markers() {
         let ws = marker_ws("eof");

package/crates/team-agent/src/messaging/delivery.rs

@@ -302,6 +302,49 @@ fn prepare_message_state(
     Ok(Ok(prepared))
 }
 
+#[cfg(unix)]
+fn mcp_handshake_pending_outcome(
+    store: &MessageStore,
+    event_log: &EventLog,
+    message_id: &str,
+    attempt: u32,
+    reason: &str,
+) -> Result<DeliveryOutcome, MessagingError> {
+    // No paste/key has occurred. Only this exact claim may be released; a
+    // concurrent cancellation or newer delivery must never be overwritten.
+    if !store.release_delivery_before_input(message_id, attempt, reason)? {
+        return Ok(DeliveryOutcome {
+            ok: false,
+            status: DeliveryStatus::Refused,
+            message_status: MessageStatusShadow("target_resolved".to_string()),
+            message_id: Some(message_id.to_string()),
+            verification: None,
+            stage: None,
+            reason: Some(DeliveryRefusal::MessageAlreadyClaimed),
+            channel: None,
+            ack_forced_off: false,
+            turn_verification: None,
+        });
+    }
+    event_log.write("delivery.deferred_mcp_handshake", serde_json::json!({
+        "message_id": message_id,
+        "reason": reason,
+        "effect": "none",
+    }))?;
+    Ok(DeliveryOutcome {
+        ok: false,
+        status: DeliveryStatus::Degraded,
+        message_status: MessageStatusShadow("target_resolved".to_string()),
+        message_id: Some(message_id.to_string()),
+        verification: Some(reason.to_string()),
+        stage: None,
+        reason: None,
+        channel: None,
+        ack_forced_off: false,
+        turn_verification: None,
+    })
+}
+
 fn deliver_prepared_message(
     workspace: &Path,
     store: &MessageStore,
@@ -642,6 +685,25 @@ fn deliver_prepared_message(
             turn_verification: None,
         });
     }
+    // Startup control must remain reachable before protocol admission: some
+    // clients cannot initialize MCP until their trust prompt is answered.
+    // No business input is allowed before the current tools/list flush. A
+    // readiness-only refusal releases this exact claim without spending an
+    // input attempt; it never holds a pane-input lock or sleeps for startup.
+    #[cfg(unix)]
+    {
+        let admission = crate::mcp_server::readiness::preflight(
+            workspace, canonical_owner_team_id.as_deref(), &message.recipient, state,
+        ).and_then(|admission| {
+            if let Some(admission) = admission.as_ref() {
+                crate::mcp_server::readiness::revalidate(admission, &target, &live_targets)?;
+            }
+            Ok(())
+        });
+        if let Err(reason) = admission {
+            return mcp_handshake_pending_outcome(store, event_log, message_id, attempt, reason);
+        }
+    }
     let rendered = render_message(
         &message.sender,
         message.task_id.as_deref(),

package/crates/team-agent/src/messaging/tests/dup_inject.rs

@@ -28,6 +28,44 @@ use crate::transport::{
     TurnVerification, WindowName,
 };
 
+#[test]
+#[cfg(unix)]
+fn eager_mcp_waits_without_spending_input_attempts_then_delivers_the_same_message() {
+    let mut case = WorkerCase::new("mcp-handshake", "cursor_agent");
+    let carrier = crate::mcp_server::readiness::test_carrier_pid().unwrap();
+    let config = case.workspace.join(".team/runtime/mcp/w1.json");
+    std::fs::create_dir_all(config.parent().unwrap()).unwrap();
+    std::fs::write(&config, serde_json::to_vec(&serde_json::json!({
+        "mcpServers": {"team_orchestrator": {
+            "command": std::env::current_exe().unwrap().canonicalize().unwrap(),
+            "env": {"TEAM_AGENT_WORKSPACE": case.workspace, "TEAM_AGENT_ID": "w1", "TEAM_AGENT_OWNER_TEAM_ID": "dup-team"}
+        }}
+    })).unwrap()).unwrap();
+    case.state["team_key"] = serde_json::json!("dup-team");
+    case.state["agents"]["w1"]["mcp_config"] = serde_json::json!(config);
+    case.state["agents"]["w1"]["pane_pid"] = serde_json::json!(carrier);
+    case.state["agents"]["w1"]["spawned_at"] = serde_json::json!((chrono::Utc::now() - chrono::Duration::seconds(10)).to_rfc3339());
+    case.state["teams"] = serde_json::json!({"dup-team": case.state.clone()});
+    crate::state::persist::save_runtime_state(&case.workspace, &case.state).unwrap();
+    let transport = RecordingTransport { carrier: Some(carrier), ..RecordingTransport::new("") };
+    let message_id = case.store.create_message(None, "leader", "w1", "handshake canary", None, false, Some("dup-team")).unwrap();
+    for _ in 0..3 {
+        let outcome = deliver_pending_message(&case.workspace, &case.store, &transport,
+            &message_id, &case.event_log, &case.state).unwrap();
+        assert!(!outcome.ok);
+        assert!(outcome.verification.as_deref().unwrap().starts_with("mcp_handshake_"));
+        assert_eq!(transport.inject_count(), 0);
+    }
+    let connection = rusqlite::Connection::open(case.store.db_path()).unwrap();
+    let attempts: i64 = connection.query_row("select delivery_attempts from messages where message_id=?1", [&message_id], |row| row.get(0)).unwrap();
+    assert_eq!(attempts, 0, "waiting is not a physical delivery attempt");
+    crate::mcp_server::readiness::publish(&case.workspace, "dup-team", "w1", chrono::Utc::now()).unwrap();
+    let outcome = deliver_pending_message(&case.workspace, &case.store, &transport,
+        &message_id, &case.event_log, &case.state).unwrap();
+    assert_eq!(outcome.message_id.as_deref(), Some(message_id.as_str()));
+    assert_eq!(transport.inject_count(), 1, "same queued row proceeds after the real receipt");
+}
+
 #[test]
 fn error_retry_claim_is_single_winner_across_two_delivers() {
     let case = WorkerCase::new("claim-gate", "fake");
@@ -273,6 +311,7 @@ fn poison_state_file(workspace: &Path) {
 struct RecordingTransport {
     injects: Arc<AtomicUsize>,
     capture: Arc<Mutex<String>>,
+    carrier: Option<u32>,
 }
 
 impl RecordingTransport {
@@ -280,6 +319,7 @@ impl RecordingTransport {
         Self {
             injects: Arc::new(AtomicUsize::new(0)),
             capture: Arc::new(Mutex::new(capture.to_string())),
+            carrier: None,
         }
     }
 
@@ -370,7 +410,7 @@ impl Transport for RecordingTransport {
             current_command: Some("sleep".to_string()),
             current_path: None,
             active: true,
-            pane_pid: None,
+            pane_pid: self.carrier,
             leader_env: BTreeMap::new(),
         }])
     }

package/crates/team-agent/src/provider/adapter.rs

@@ -214,6 +214,13 @@ pub trait ProviderAdapter {
     /// compatible_api 走 `ensure_compatible_claude_mcp_config`)。
     fn mcp_config(&self, auth_mode: AuthMode) -> Result<McpConfig, ProviderError>;
 
+    /// Eager stdio clients must publish their initial MCP handshake before input.
+    /// Pi owns admission in its runtime registry hooks; Fake has no MCP client.
+    /// The process-stamp receipt port is currently POSIX-only, not a Windows claim.
+    fn requires_worker_mcp_handshake(&self) -> bool {
+        cfg!(unix) && !matches!(self.provider(), Provider::Fake | Provider::Pi)
+    }
+
     /// 安装 MCP server。gemini 写全局 `~/.gemini/settings.json` 并备份/还原
     /// (`gemini.py:40-78`)——有副作用 I/O,失败可还原 → Result。
     fn install_mcp(&self, config: &McpConfig) -> Result<(), ProviderError>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.120",
+  "version": "0.5.121",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.120",
-    "@team-agent/cli-darwin-x64": "0.5.120",
-    "@team-agent/cli-linux-x64": "0.5.120"
+    "@team-agent/cli-darwin-arm64": "0.5.121",
+    "@team-agent/cli-darwin-x64": "0.5.121",
+    "@team-agent/cli-linux-x64": "0.5.121"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",