@team-agent/installer 0.5.10 → 0.5.11

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.10"
+version = "0.5.11"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.10"
+version = "0.5.11"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/diagnose.rs

@@ -6,6 +6,12 @@ use crate::transport::Transport;
 pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value, Value) {
     let mut issues = Vec::new();
     let mut repairs = Vec::new();
+    for issue in crate::topology::diagnose_topology_issues(state, backend) {
+        if let Some(id) = crate::topology::issue_id(&issue) {
+            repairs.push(topology_repair_hint(id));
+        }
+        issues.push(issue);
+    }
 
     if let Some(session_name) = state
         .get("session_name")
@@ -159,6 +165,18 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
     (Value::Array(issues), Value::Array(repairs))
 }
 
+fn topology_repair_hint(issue: &str) -> Value {
+    json!({
+        "issue": issue,
+        "action_required": true,
+        "advisory": true,
+        "broken_class": issue,
+        "hint_action": "team-agent diagnose --json",
+        "dedupe_key": issue,
+        "action": "repair the tmux topology mismatch, then rerun team-agent restart",
+    })
+}
+
 /// 0.4.x (CR R2): pull (pane_id, provider_label) from leader_receiver. Used
 /// by `leader_provider_health` reconcile in diagnose. Returns None when the
 /// leader is not attached or any field is missing.

package/crates/team-agent/src/cli/mod.rs

@@ -3309,12 +3309,21 @@ pub mod lifecycle_port {
                 session_name,
                 reason,
                 error,
+                issue_ids,
             } => json!({
                 "ok": false,
                 "status": "refused_dirty_topology",
                 "reason": reason,
                 "session_name": session_name,
                 "error": error,
+                "issues": issue_ids
+                    .iter()
+                    .map(|id| json!({"id": id}))
+                    .collect::<Vec<_>>(),
+                "next_actions": [
+                    "run team-agent diagnose --json from the intended leader socket",
+                    "repair the tmux endpoint/socket split before retrying restart"
+                ],
                 "reminder": crate::cli::QUICK_START_REMINDER,
             }),
         }

package/crates/team-agent/src/cli/named_address.rs

@@ -721,8 +721,20 @@ fn resolve_leader(
     let targets = list_targets(transport)?;
     let matches = targets
         .iter()
-        .filter(|target| target.pane_id.as_str() == pane_id)
+        .filter(|target| {
+            target.pane_id.as_str() == pane_id
+                && session.is_none_or(|expected| target.session.as_str() == expected)
+                && window.is_none_or(|expected| {
+                    target
+                        .window_name
+                        .as_ref()
+                        .is_some_and(|name| name.as_str() == expected)
+                })
+        })
         .collect::<Vec<_>>();
+    let stale_pane_seen = targets
+        .iter()
+        .any(|target| target.pane_id.as_str() == pane_id);
     match matches.len() {
         1 => Ok(ResolvedNamedAddress {
             raw_name: parsed.display_name(),
@@ -751,6 +763,9 @@ fn resolve_leader(
                 window,
                 socket,
             );
+            if stale_pane_seen {
+                err.log = format!("{} stale_tuple_mismatch=true", err.log);
+            }
             err.candidates =
                 leader_advisory_candidates(state, team, transport, "state_recorded_socket");
             Err(err)

package/crates/team-agent/src/lib.rs

@@ -88,6 +88,7 @@ pub mod platform;
 // 0.3.28 — unified adaptive layout manager (single source of truth for tmux
 // topology decisions). See `.team/artifacts/adaptive-layout-full-architecture-locate.md`.
 pub mod layout;
+pub mod topology;
 pub mod mcp_server;
 pub mod cli;
 pub mod packaging;

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

@@ -127,7 +127,12 @@ pub(crate) fn start_agent_at_paths(
     // state — assert_topology_invariants from Step 1 catches the
     // upstream corruption.
     let has_collision = pane_conflicts_with_leader_or_other(&state, agent_id, &raw_agent);
-    if has_collision {
+    let noop_pane = if adaptive_layout {
+        None
+    } else {
+        single_live_pane_for_window(transport, &session_name, &window)
+    };
+    if has_collision && noop_pane.is_none() {
         eprintln!(
             "team_agent::layout e51_collision_post_step2 agent_id=`{agent_id}` \
              action=forcing_fresh_spawn \
@@ -135,9 +140,17 @@ pub(crate) fn start_agent_at_paths(
               investigate upstream state corruption)"
         );
     }
-    let agent_live = agent_live && !has_collision;
+    let agent_live = agent_live && (!has_collision || noop_pane.is_some());
     if !force && agent_live {
-        mark_agent_running_noop(&mut state, agent_id, &session_name, &window)?;
+        let old_binding = pane_binding_snapshot(&raw_agent);
+        let refreshed_binding = noop_pane.as_ref().map(pane_binding_from_live);
+        mark_agent_running_noop(
+            &mut state,
+            agent_id,
+            &session_name,
+            &window,
+            noop_pane.as_ref(),
+        )?;
         let team_key = restart_projection_team_key(&state, team);
         save_restart_projected_state(workspace, &mut state, &team_key, &[agent_id.as_str()])?;
         if let Ok(spec) = load_team_spec(spec_workspace) {
@@ -146,6 +159,18 @@ pub(crate) fn start_agent_at_paths(
         replay_worker_target_missing_messages(workspace, agent_id, &team_key, &state, transport)?;
         let coordinator_started = start_coordinator_for_workspace(workspace)?;
         let target = format!("{}:{window}", session_name.as_str());
+        if let Some(new_binding) = refreshed_binding.as_ref() {
+            if old_binding.as_ref() != Some(new_binding) {
+                write_agent_pane_binding_refreshed_event(
+                    workspace,
+                    agent_id,
+                    &session_name,
+                    &window,
+                    old_binding.as_ref(),
+                    new_binding,
+                )?;
+            }
+        }
         write_start_agent_noop_event(workspace, agent_id, &target, coordinator_started)?;
         return Ok(StartAgentOutcome::Noop {
             env: AgentActionEnvelope {
@@ -373,6 +398,78 @@ fn verify_spawned_pane_matches_target(
     Ok(())
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct PaneBindingSnapshot {
+    pane_id: String,
+    pane_pid: Option<u32>,
+}
+
+fn pane_binding_snapshot(agent: &serde_json::Value) -> Option<PaneBindingSnapshot> {
+    let pane_id = agent
+        .get("pane_id")
+        .and_then(serde_json::Value::as_str)
+        .filter(|pane| !pane.is_empty())?;
+    Some(PaneBindingSnapshot {
+        pane_id: pane_id.to_string(),
+        pane_pid: agent
+            .get("pane_pid")
+            .and_then(serde_json::Value::as_u64)
+            .map(|pid| pid as u32),
+    })
+}
+
+fn pane_binding_from_live(pane: &crate::transport::PaneInfo) -> PaneBindingSnapshot {
+    PaneBindingSnapshot {
+        pane_id: pane.pane_id.as_str().to_string(),
+        pane_pid: pane.pane_pid,
+    }
+}
+
+fn single_live_pane_for_window(
+    transport: &dyn crate::transport::Transport,
+    session: &crate::transport::SessionName,
+    window: &str,
+) -> Option<crate::transport::PaneInfo> {
+    let targets = transport.list_targets().ok()?;
+    let mut matches = targets.into_iter().filter(|target| {
+        target.session.as_str() == session.as_str()
+            && target
+                .window_name
+                .as_ref()
+                .is_some_and(|name| name.as_str() == window)
+    });
+    let pane = matches.next()?;
+    if matches.next().is_some() {
+        return None;
+    }
+    Some(pane)
+}
+
+fn write_agent_pane_binding_refreshed_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    session: &crate::transport::SessionName,
+    window: &str,
+    old: Option<&PaneBindingSnapshot>,
+    new: &PaneBindingSnapshot,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "agent_pane_binding_refreshed",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "session": session.as_str(),
+                "window": window,
+                "old_pane_id": old.map(|binding| binding.pane_id.as_str()),
+                "old_pane_pid": old.and_then(|binding| binding.pane_pid),
+                "pane_id": new.pane_id.as_str(),
+                "pane_pid": new.pane_pid,
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
 /// E51 (0.3.26 P0, restart self-heal): returns `true` when the agent's pane_id
 /// is the same as the leader_receiver/team_owner pane_id OR is owned by a
 /// different agent in the state. In both cases `start_agent` must NOT treat the

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

@@ -1284,6 +1284,7 @@ pub(super) fn mark_agent_running_noop(
     agent_id: &AgentId,
     session_name: &SessionName,
     window: &str,
+    pane: Option<&crate::transport::PaneInfo>,
 ) -> Result<(), LifecycleError> {
     if !state.is_object() {
         *state = serde_json::json!({});
@@ -1322,6 +1323,17 @@ pub(super) fn mark_agent_running_noop(
     obj.insert("status".to_string(), serde_json::json!("running"));
     obj.insert("agent_id".to_string(), serde_json::json!(agent_id.as_str()));
     obj.insert("window".to_string(), serde_json::json!(window));
+    if let Some(pane) = pane {
+        obj.insert(
+            "pane_id".to_string(),
+            serde_json::json!(pane.pane_id.as_str()),
+        );
+        if let Some(pane_pid) = pane.pane_pid {
+            obj.insert("pane_pid".to_string(), serde_json::json!(pane_pid));
+        } else {
+            obj.remove("pane_pid");
+        }
+    }
     Ok(())
 }
 

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

@@ -137,6 +137,32 @@ pub fn restart_with_transport_with_session_convergence_deadline(
     })?;
     let mut state = selected.state;
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, None)?;
+    let topology_issue_ids = crate::topology::restart_dirty_topology_issue_ids(&state);
+    if !topology_issue_ids.is_empty() {
+        let session_name = state
+            .get("session_name")
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or_default()
+            .to_string();
+        crate::event_log::EventLog::new(&selected.run_workspace)
+            .write(
+                "restart.refused_dirty_topology",
+                serde_json::json!({
+                    "session_name": session_name,
+                    "issues": topology_issue_ids.iter().map(|id| serde_json::json!({"id": id})).collect::<Vec<_>>(),
+                }),
+            )
+            .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+        return Ok(RestartReport::RefusedDirtyTopology {
+            session_name,
+            reason: topology_issue_ids
+                .first()
+                .cloned()
+                .unwrap_or_else(|| "dirty_topology".to_string()),
+            error: "restart refused: tmux endpoint/socket topology is inconsistent; run diagnose from the intended leader socket before restarting".to_string(),
+            issue_ids: topology_issue_ids,
+        });
+    }
     // E5 task#3 / RC-A6a + E4(leader 裁定:每次 restart 都从角色定义重建 runtime spec,覆盖):
     // 角色定义=第一真相源。角色齐 → compile_team 重建 + 保留运行期 override(session_name)+
     // 写 runtime spec。角色缺(TEAM.md/agents 不在)→ 显式拒(列缺哪些),旧 spec 原地保留不删不用。
@@ -278,6 +304,7 @@ pub fn restart_with_transport_with_session_convergence_deadline(
                      launcher session ({reason}); aborting before any tmux kill. Repair \
                      state.session_name to the worker session and re-run."
                 ),
+                issue_ids: vec![reason.clone()],
             });
         }
     }

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

@@ -702,6 +702,8 @@ pub enum RestartReport {
         reason: String,
         /// Human-readable error directing the user to a recovery action.
         error: String,
+        /// Stable topology issue ids surfaced by CLI/diagnose.
+        issue_ids: Vec<String>,
     },
 }
 

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

@@ -103,6 +103,42 @@ pub fn tmux_pane_width(transport: &dyn Transport, target: &Target) -> PaneWidthQ
     }
 }
 
+pub(crate) fn worker_target_missing_due_to_stale_binding(
+    state: &serde_json::Value,
+    recipient: &str,
+    transport: &dyn Transport,
+) -> bool {
+    let Some(agent) = state.get("agents").and_then(|agents| agents.get(recipient)) else {
+        return false;
+    };
+    let session = state
+        .get("session_name")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or_default();
+    let window = agent
+        .get("window")
+        .and_then(serde_json::Value::as_str)
+        .filter(|s| !s.is_empty())
+        .unwrap_or(recipient);
+    let Some(cached_pane) = agent
+        .get("pane_id")
+        .and_then(serde_json::Value::as_str)
+        .filter(|s| !s.is_empty())
+    else {
+        return false;
+    };
+    let Ok(live_targets) = transport.list_targets() else {
+        return false;
+    };
+    if live_pane_for_session_window(&live_targets, session, window).is_some() {
+        return false;
+    }
+    live_targets.iter().any(|target| {
+        target.pane_id.as_str() == cached_pane
+            && stale_worker_pane_binding(target, session, window).is_some()
+    })
+}
+
 /// `_deliver_pending_message` (`delivery.py:63`):对一条消息做 tmux 注入投递 (含 trust 提示
 /// 自动应答 + turn-open arm + first_send_at 戳)。daemon-path → Result。
 pub fn deliver_pending_message(
@@ -323,7 +359,11 @@ pub fn deliver_pending_message(
             channel: Some("rebind_required".to_string()),
         });
     }
-    let target = resolve_inject_target(state, &message.recipient, transport, &live_targets);
+    let resolved = resolve_inject_target(state, &message.recipient, transport, &live_targets);
+    if let Some(stale) = resolved.stale_binding.as_ref() {
+        event_log.write("worker_pane_binding_stale", stale.as_event_payload(message_id, &message.recipient))?;
+    }
+    let target = resolved.target.clone();
     if let Some(outcome) = block_missing_worker_target(
         store,
         event_log,
@@ -467,6 +507,7 @@ pub fn deliver_pending_message(
         message_id,
         event_log,
         canonical_owner_team_id.as_deref(),
+        resolved.metadata.as_ref(),
     )?;
     let submit_verified = inject_submit_verified(&inject_report);
     let readback_verified = pane_readback_verified(&inject_report);
@@ -554,14 +595,13 @@ pub fn deliver_pending_message(
         let token_marker = format!("[team-agent-token:{message_id}]");
         let grace = std::time::Duration::from_millis(200);
         let deadline = std::time::Instant::now() + std::time::Duration::from_millis(500);
-        let mut transcript_has_token = false;
-        loop {
-            transcript_has_token = rollout_tail_contains(&rollout_path, &token_marker, 64 * 1024);
-            if transcript_has_token || std::time::Instant::now() >= deadline {
-                break;
+        let transcript_has_token = loop {
+            let found = rollout_tail_contains(&rollout_path, &token_marker, 64 * 1024);
+            if found || std::time::Instant::now() >= deadline {
+                break found;
             }
             std::thread::sleep(grace);
-        }
+        };
         if !transcript_has_token {
             // Loud but non-fatal: emit a mismatch event for diagnose/status
             // observability. Do NOT mark delivered — degrade to
@@ -606,10 +646,11 @@ pub fn deliver_pending_message(
         }
     }
     store.mark(message_id, "delivered", None)?;
-    event_log.write(
-        "message.delivered",
-        serde_json::json!({"message_id": message_id}),
-    )?;
+    let mut delivered_event = serde_json::json!({"message_id": message_id});
+    if let Some(metadata) = resolved.metadata.as_ref() {
+        append_target_metadata(&mut delivered_event, metadata);
+    }
+    event_log.write("message.delivered", delivered_event)?;
     let outcome = DeliveryOutcome {
         ok: true,
         status: DeliveryStatus::Delivered,
@@ -633,6 +674,7 @@ pub fn deliver_pending_message(
         &outcome,
         event_log,
         canonical_owner_team_id.as_deref(),
+        resolved.metadata.as_ref(),
     )?;
     Ok(outcome)
 }
@@ -1056,15 +1098,61 @@ fn app_server_rebind_action(owner_team_id: Option<&str>, receiver: &serde_json::
 /// pane. U1-A real-machine fix is deferred to v0.3.25 (writer-shape + projection +
 /// rediscover-writer triad). U1-B jitter defer at try_deliver_message:213-237 and
 /// U1-C-Tail at the startup-prompt peek site are unchanged.
+#[derive(Clone)]
+struct ResolvedInjectTarget {
+    target: Target,
+    metadata: Option<TargetMetadata>,
+    stale_binding: Option<WorkerPaneBindingStale>,
+}
+
+#[derive(Clone)]
+struct TargetMetadata {
+    tmux_endpoint: Option<String>,
+    target_session: String,
+    target_window: String,
+    target_pane_id: String,
+    target_pane_pid: Option<u32>,
+    resolved_from: &'static str,
+}
+
+#[derive(Clone)]
+struct WorkerPaneBindingStale {
+    cached_pane_id: String,
+    expected_session: String,
+    expected_window: String,
+    observed_session: String,
+    observed_window: String,
+    observed_pane_pid: Option<u32>,
+}
+
+impl WorkerPaneBindingStale {
+    fn as_event_payload(&self, message_id: &str, recipient: &str) -> serde_json::Value {
+        serde_json::json!({
+            "message_id": message_id,
+            "recipient": recipient,
+            "cached_pane_id": self.cached_pane_id,
+            "expected_session": self.expected_session,
+            "expected_window": self.expected_window,
+            "observed_session": self.observed_session,
+            "observed_window": self.observed_window,
+            "observed_pane_pid": self.observed_pane_pid,
+        })
+    }
+}
+
 fn resolve_inject_target(
     state: &serde_json::Value,
     recipient: &str,
     transport: &dyn Transport,
     live_targets: &[PaneInfo],
-) -> Target {
+) -> ResolvedInjectTarget {
     if recipient == "leader" {
         if let Some(pane_id) = leader_receiver_pane_id(state) {
-            return Target::Pane(PaneId::new(pane_id));
+            return ResolvedInjectTarget {
+                target: Target::Pane(PaneId::new(pane_id)),
+                metadata: None,
+                stale_binding: None,
+            };
         }
     }
     let agent = state.get("agents").and_then(|a| a.get(recipient));
@@ -1096,37 +1184,71 @@ fn resolve_inject_target(
         if leader_receiver_pane_binding(state).is_some_and(|leader| {
             pane_conflicts_on_same_socket(pane.as_str(), worker_socket.as_deref(), leader)
         }) {
-            return Target::SessionWindow {
-                session: SessionName::new(session),
-                window: WindowName::new(format!("{recipient}_pane_conflicts_with_leader")),
+            return ResolvedInjectTarget {
+                target: Target::SessionWindow {
+                    session: SessionName::new(session),
+                    window: WindowName::new(format!("{recipient}_pane_conflicts_with_leader")),
+                },
+                metadata: None,
+                stale_binding: None,
             };
         }
-        if live_targets
-            .iter()
-            .any(|target| target.pane_id.as_str() == pane.as_str())
-        {
-            return Target::Pane(pane.clone());
-        }
     }
+    let stale_binding = cached_pane.as_ref().and_then(|pane| {
+        live_targets
+            .iter()
+            .find(|target| target.pane_id.as_str() == pane.as_str())
+            .and_then(|target| stale_worker_pane_binding(target, session, window))
+    });
     if let Some(live_pane) = live_pane_for_session_window(live_targets, session, window) {
-        return Target::Pane(live_pane);
+        return ResolvedInjectTarget {
+            target: Target::Pane(live_pane.pane_id.clone()),
+            metadata: Some(target_metadata(
+                transport,
+                live_pane,
+                "session_window_lookup",
+            )),
+            stale_binding,
+        };
     }
     if let Some(pane) = cached_pane {
-        if live_targets.is_empty() && !cached_pane_known_dead(transport, &pane) {
-            return Target::Pane(pane);
+        if let Some(live_pane) = live_targets.iter().find(|target| {
+            target.pane_id.as_str() == pane.as_str()
+                && target.session.as_str() == session
+                && target
+                    .window_name
+                    .as_ref()
+                    .is_some_and(|name| name.as_str() == window)
+        }) {
+            return ResolvedInjectTarget {
+                target: Target::Pane(pane),
+                metadata: Some(target_metadata(transport, live_pane, "validated_cached_pane")),
+                stale_binding: None,
+            };
+        }
+        if live_targets.is_empty() {
+            return ResolvedInjectTarget {
+                target: Target::Pane(pane),
+                metadata: None,
+                stale_binding: None,
+            };
         }
     }
-    Target::SessionWindow {
-        session: SessionName::new(session),
-        window: WindowName::new(window),
+    ResolvedInjectTarget {
+        target: Target::SessionWindow {
+            session: SessionName::new(session),
+            window: WindowName::new(window),
+        },
+        metadata: None,
+        stale_binding,
     }
 }
 
-fn live_pane_for_session_window(
-    targets: &[PaneInfo],
+fn live_pane_for_session_window<'a>(
+    targets: &'a [PaneInfo],
     session: &str,
     window: &str,
-) -> Option<PaneId> {
+) -> Option<&'a PaneInfo> {
     targets
         .iter()
         .find(|target| {
@@ -1136,14 +1258,86 @@ fn live_pane_for_session_window(
                     .as_ref()
                     .is_some_and(|name| name.as_str() == window)
         })
-        .map(|target| target.pane_id.clone())
 }
 
-fn cached_pane_known_dead(transport: &dyn Transport, pane: &PaneId) -> bool {
-    if matches!(transport.has_pane(pane), Ok(Some(false))) {
-        return true;
+fn stale_worker_pane_binding(
+    observed: &PaneInfo,
+    expected_session: &str,
+    expected_window: &str,
+) -> Option<WorkerPaneBindingStale> {
+    let observed_window = observed
+        .window_name
+        .as_ref()
+        .map(|window| window.as_str())
+        .unwrap_or_default();
+    if observed.session.as_str() == expected_session && observed_window == expected_window {
+        return None;
+    }
+    Some(WorkerPaneBindingStale {
+        cached_pane_id: observed.pane_id.as_str().to_string(),
+        expected_session: expected_session.to_string(),
+        expected_window: expected_window.to_string(),
+        observed_session: observed.session.as_str().to_string(),
+        observed_window: observed_window.to_string(),
+        observed_pane_pid: observed.pane_pid,
+    })
+}
+
+fn target_metadata(
+    transport: &dyn Transport,
+    pane: &PaneInfo,
+    resolved_from: &'static str,
+) -> TargetMetadata {
+    TargetMetadata {
+        tmux_endpoint: transport.tmux_endpoint(),
+        target_session: pane.session.as_str().to_string(),
+        target_window: pane
+            .window_name
+            .as_ref()
+            .map(|window| window.as_str().to_string())
+            .unwrap_or_default(),
+        target_pane_id: pane.pane_id.as_str().to_string(),
+        target_pane_pid: pane.pane_pid,
+        resolved_from,
     }
-    matches!(transport.liveness(pane), Ok(PaneLiveness::Dead))
+}
+
+fn append_target_metadata(event: &mut serde_json::Value, metadata: &TargetMetadata) {
+    let Some(obj) = event.as_object_mut() else {
+        return;
+    };
+    obj.insert("target_kind".to_string(), serde_json::json!("pane"));
+    obj.insert(
+        "tmux_endpoint".to_string(),
+        metadata
+            .tmux_endpoint
+            .as_ref()
+            .map(|endpoint| serde_json::json!(endpoint))
+            .unwrap_or(serde_json::Value::Null),
+    );
+    obj.insert(
+        "target_session".to_string(),
+        serde_json::json!(metadata.target_session),
+    );
+    obj.insert(
+        "target_window".to_string(),
+        serde_json::json!(metadata.target_window),
+    );
+    obj.insert(
+        "target_pane_id".to_string(),
+        serde_json::json!(metadata.target_pane_id),
+    );
+    obj.insert(
+        "target_pane_pid".to_string(),
+        metadata
+            .target_pane_pid
+            .map(|pid| serde_json::json!(pid))
+            .unwrap_or(serde_json::Value::Null),
+    );
+    obj.insert(
+        "resolved_from".to_string(),
+        serde_json::json!(metadata.resolved_from),
+    );
 }
 
 #[derive(Clone, Copy)]
@@ -1911,7 +2105,7 @@ pub fn record_turn_open_if_leader_to_worker(
 ) -> Result<(), MessagingError> {
     let _ = state;
     record_turn_open_if_leader_to_worker_scoped(
-        workspace, sender, recipient, delivered, event_log, None,
+        workspace, sender, recipient, delivered, event_log, None, None,
     )
 }
 
@@ -1922,6 +2116,7 @@ fn record_current_turn_after_inject_if_leader_to_worker_scoped(
     message_id: &str,
     event_log: &EventLog,
     owner_team_id: Option<&str>,
+    metadata: Option<&TargetMetadata>,
 ) -> Result<(), MessagingError> {
     if !matches!(sender, "leader" | "Leader") || recipient == "leader" {
         return Ok(());
@@ -1932,10 +2127,11 @@ fn record_current_turn_after_inject_if_leader_to_worker_scoped(
     save_scoped_state_reapplying_after_conflict(workspace, &state, owner_team_id, |latest| {
         arm_turn_open(latest, recipient, &message_id);
     })?;
-    event_log.write(
-        "turn_open.armed_after_inject",
-        serde_json::json!({"agent_id": recipient, "message_id": message_id}),
-    )?;
+    let mut event = serde_json::json!({"agent_id": recipient, "message_id": message_id});
+    if let Some(metadata) = metadata {
+        append_target_metadata(&mut event, metadata);
+    }
+    event_log.write("turn_open.armed_after_inject", event)?;
     Ok(())
 }
 
@@ -1946,6 +2142,7 @@ fn record_turn_open_if_leader_to_worker_scoped(
     delivered: &DeliveryOutcome,
     event_log: &EventLog,
     owner_team_id: Option<&str>,
+    metadata: Option<&TargetMetadata>,
 ) -> Result<(), MessagingError> {
     if !delivered.ok || !matches!(sender, "leader" | "Leader") || recipient == "leader" {
         return Ok(());
@@ -1955,10 +2152,12 @@ fn record_turn_open_if_leader_to_worker_scoped(
     save_scoped_state_reapplying_after_conflict(workspace, &state, owner_team_id, |latest| {
         arm_turn_open(latest, recipient, &delivered.message_id);
     })?;
-    event_log.write(
-        "turn_open.armed_after_delivery",
-        serde_json::json!({"agent_id": recipient, "message_id": delivered.message_id}),
-    )?;
+    let mut event =
+        serde_json::json!({"agent_id": recipient, "message_id": delivered.message_id});
+    if let Some(metadata) = metadata {
+        append_target_metadata(&mut event, metadata);
+    }
+    event_log.write("turn_open.armed_after_delivery", event)?;
     Ok(())
 }
 

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

@@ -10,7 +10,7 @@ use crate::transport::{PaneId, Transport};
 
 use super::helpers::{status_wire, MessageStatusShadow};
 use super::leader_receiver::{send_to_leader_receiver, send_to_leader_receiver_with_message_id};
-use super::{DeliveryOutcome, DeliveryRefusal, DeliveryStatus, MessagingError};
+use super::{DeliveryOutcome, DeliveryRefusal, DeliveryStage, DeliveryStatus, MessagingError};
 
 /// 发件目标:单 target / 广播 `*` / 扇出 list (`send.py:36` `target: str|list[str]|None`)。
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -182,6 +182,9 @@ pub fn send_message(
             }
         }
     }
+    if let Some(outcome) = stale_worker_target_preflight(workspace, &state, recipient, opts)? {
+        return Ok(outcome);
+    }
     if let Some(outcome) = coordinator_unavailable_outcome(workspace, recipient, opts, &event_log)?
     {
         return Ok(outcome);
@@ -231,6 +234,38 @@ pub fn send_message(
     })
 }
 
+fn stale_worker_target_preflight(
+    workspace: &Path,
+    state: &serde_json::Value,
+    recipient: &str,
+    opts: &SendOptions,
+) -> Result<Option<DeliveryOutcome>, MessagingError> {
+    let Ok(resolved) = crate::transport_factory::resolve_read_only_transport(
+        workspace,
+        Some(state),
+        crate::transport_factory::TransportPurpose::MessageDelivery,
+    ) else {
+        return Ok(None);
+    };
+    if !super::delivery::worker_target_missing_due_to_stale_binding(
+        state,
+        recipient,
+        resolved.backend.as_ref(),
+    ) {
+        return Ok(None);
+    }
+    Ok(Some(DeliveryOutcome {
+        ok: false,
+        status: DeliveryStatus::Blocked,
+        message_status: MessageStatusShadow("queued_pane_missing".to_string()),
+        message_id: opts.message_id.clone(),
+        verification: Some(format!("run team-agent start-agent {recipient} --allow-fresh")),
+        stage: Some(DeliveryStage::Inject),
+        reason: Some(DeliveryRefusal::TmuxTargetMissing),
+        channel: Some("delivery_blocked".to_string()),
+    }))
+}
+
 fn task_exists(state: &serde_json::Value, task_id: &TaskId) -> bool {
     state
         .get("tasks")

package/crates/team-agent/src/topology.rs

@@ -0,0 +1,152 @@
+use serde_json::{json, Value};
+
+use crate::transport::{SessionName, Transport};
+
+pub const WORKER_PANE_BINDING_STALE: &str = "worker_pane_binding_stale";
+pub const TMUX_ENDPOINT_SOCKET_CONFLICT: &str = "tmux_endpoint_socket_conflict";
+pub const LEADER_RECEIVER_SOCKET_MISMATCH: &str = "leader_receiver_socket_mismatch";
+pub const ORPHAN_TEAM_SESSION_ON_IGNORED_SOCKET: &str = "orphan_team_session_on_ignored_socket";
+pub const TEAM_SESSION_MISSING_ON_CANONICAL_SOCKET: &str =
+    "team_session_missing_on_canonical_socket";
+pub const RECENT_COORDINATOR_SESSION_MISSING: &str = "recent_coordinator_session_missing";
+
+pub fn diagnose_topology_issues(state: &Value, backend: &dyn Transport) -> Vec<Value> {
+    let mut issues = Vec::new();
+    append_socket_split_issues(state, &mut issues, true);
+    append_worker_pane_binding_issues(state, backend, &mut issues);
+    issues
+}
+
+pub fn restart_dirty_topology_issue_ids(state: &Value) -> Vec<String> {
+    let mut issues = Vec::new();
+    append_socket_split_issues(state, &mut issues, false);
+    issues
+        .into_iter()
+        .filter_map(|issue| issue.get("id").and_then(Value::as_str).map(str::to_string))
+        .collect()
+}
+
+pub fn issue_id(issue: &Value) -> Option<&str> {
+    issue.get("id").and_then(Value::as_str)
+}
+
+fn append_socket_split_issues(state: &Value, issues: &mut Vec<Value>, include_readiness: bool) {
+    let endpoint = non_empty_str(state, "tmux_endpoint");
+    let socket = non_empty_str(state, "tmux_socket");
+    let (Some(endpoint), Some(socket)) = (endpoint, socket) else {
+        return;
+    };
+    if same_endpoint(endpoint, socket) {
+        return;
+    }
+
+    let session = non_empty_str(state, "session_name").unwrap_or_default();
+    issues.push(json!({
+        "id": TMUX_ENDPOINT_SOCKET_CONFLICT,
+        "tmux_endpoint": endpoint,
+        "tmux_socket": socket,
+    }));
+
+    if state
+        .get("leader_receiver")
+        .and_then(|receiver| non_empty_str(receiver, "tmux_socket"))
+        .is_some_and(|leader_socket| !same_endpoint(leader_socket, endpoint))
+    {
+        issues.push(json!({
+            "id": LEADER_RECEIVER_SOCKET_MISMATCH,
+            "tmux_endpoint": endpoint,
+            "leader_receiver_tmux_socket": state
+                .get("leader_receiver")
+                .and_then(|receiver| non_empty_str(receiver, "tmux_socket")),
+        }));
+    }
+
+    if !session.is_empty() && session_exists_on_endpoint(endpoint, session) {
+        issues.push(json!({
+            "id": ORPHAN_TEAM_SESSION_ON_IGNORED_SOCKET,
+            "ignored_tmux_endpoint": endpoint,
+            "session_name": session,
+        }));
+    }
+
+    if include_readiness && !session.is_empty() && !session_exists_on_endpoint(socket, session) {
+        issues.push(json!({
+            "id": TEAM_SESSION_MISSING_ON_CANONICAL_SOCKET,
+            "tmux_endpoint": socket,
+            "session_name": session,
+        }));
+        issues.push(json!({
+            "id": RECENT_COORDINATOR_SESSION_MISSING,
+            "tmux_endpoint": socket,
+            "session_name": session,
+        }));
+    }
+}
+
+fn append_worker_pane_binding_issues(
+    state: &Value,
+    backend: &dyn Transport,
+    issues: &mut Vec<Value>,
+) {
+    let session = non_empty_str(state, "session_name").unwrap_or_default();
+    let Some(agents) = state.get("agents").and_then(Value::as_object) else {
+        return;
+    };
+    let Ok(live_targets) = backend.list_targets() else {
+        return;
+    };
+    for (agent_id, agent) in agents {
+        let Some(cached_pane_id) = non_empty_str(agent, "pane_id") else {
+            continue;
+        };
+        let window = non_empty_str(agent, "window").unwrap_or(agent_id.as_str());
+        let Some(observed) = live_targets
+            .iter()
+            .find(|pane| pane.pane_id.as_str() == cached_pane_id)
+        else {
+            continue;
+        };
+        let observed_window = observed
+            .window_name
+            .as_ref()
+            .map(|window| window.as_str())
+            .unwrap_or_default();
+        if observed.session.as_str() == session && observed_window == window {
+            continue;
+        }
+        issues.push(json!({
+            "id": WORKER_PANE_BINDING_STALE,
+            "agent_id": agent_id,
+            "cached_pane_id": cached_pane_id,
+            "expected_session": session,
+            "expected_window": window,
+            "observed_session": observed.session.as_str(),
+            "observed_window": observed_window,
+            "observed_pane_pid": observed.pane_pid,
+        }));
+    }
+}
+
+fn session_exists_on_endpoint(endpoint: &str, session: &str) -> bool {
+    crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
+        .has_session(&SessionName::new(session.to_string()))
+        .unwrap_or(false)
+}
+
+fn same_endpoint(left: &str, right: &str) -> bool {
+    normalize_endpoint(left) == normalize_endpoint(right)
+}
+
+fn normalize_endpoint(value: &str) -> String {
+    if std::path::Path::new(value).is_absolute() {
+        value.to_string()
+    } else if let Some(path) = crate::tmux_backend::socket_path_for_name(value) {
+        path.to_string_lossy().into_owned()
+    } else {
+        value.to_string()
+    }
+}
+
+fn non_empty_str<'a>(value: &'a Value, key: &str) -> Option<&'a str> {
+    value.get(key).and_then(Value::as_str).filter(|s| !s.is_empty())
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "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.10",
-    "@team-agent/cli-darwin-x64": "0.5.10",
-    "@team-agent/cli-linux-x64": "0.5.10"
+    "@team-agent/cli-darwin-arm64": "0.5.11",
+    "@team-agent/cli-darwin-x64": "0.5.11",
+    "@team-agent/cli-linux-x64": "0.5.11"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",