@team-agent/installer 0.5.9 → 0.5.11

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.9"
+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.9"
+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

@@ -267,6 +267,26 @@ pub(crate) fn resolve_name_for_cli(
     Ok((resolved, transport))
 }
 
+/// E6 wiring helper (`cli::send::maybe_enqueue_offline_leader_mailbox`):
+/// re-parse a `<workspace>::<team>/leader` name and return the resolved
+/// target workspace + canonical team_key so send.rs can enqueue the
+/// mailbox without duplicating the parser. Returns `Ok(None)` for names
+/// that aren't `<team>/leader` shapes (worker sends, session:window,
+/// etc. keep their existing refusal semantics).
+pub(crate) fn parse_leader_target_workspace_and_team(
+    sender_workspace: &Path,
+    raw_name: &str,
+) -> Result<Option<(PathBuf, String)>, NamedAddressError> {
+    let parsed = parse_named_address(raw_name)?;
+    let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())?;
+    match parsed.target {
+        ParsedTarget::TeamEntity { team, entity } if entity == "leader" => {
+            Ok(Some((target_workspace, team)))
+        }
+        _ => Ok(None),
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct ParsedNamedAddress {
     workspace: Option<PathBuf>,
@@ -701,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(),
@@ -731,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/cli/send.rs

@@ -52,10 +52,34 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
         let (resolved, transport) =
             match crate::cli::named_address::resolve_name_for_cli(&args.workspace, to_name) {
                 Ok(resolved) => resolved,
-                Err(error) if args.json => {
-                    return Ok(CmdResult::from_json(error.to_json(), args.json));
+                Err(error) => {
+                    // E6 (0.5.9 offline-mailbox-toname-design §3.1/§6.2): when
+                    // the resolver refuses with `leader_not_attached`, the team
+                    // itself may still be alive (worker + coordinator running
+                    // without a bound leader). Third-party senders in that
+                    // shape must land in the offline mailbox — same
+                    // canonical team.db row + queued_until_leader_attach
+                    // status the coordinator/attach hook replay through the
+                    // existing pipeline exactly once. Owner-scope refusals
+                    // (same workspace as target) keep the actionable attach
+                    // hint — E6 owner copy is documented as
+                    // `run team-agent attach-leader`.
+                    if let Some(mut value) = maybe_enqueue_offline_leader_mailbox(
+                        &args.workspace,
+                        to_name,
+                        &content,
+                        &args.sender,
+                        args.task.as_deref(),
+                        &error,
+                    )? {
+                        add_send_reminder_if_ok(&mut value);
+                        return Ok(cmd_send_result(value, args.json));
+                    }
+                    if args.json {
+                        return Ok(CmdResult::from_json(error.to_json(), args.json));
+                    }
+                    return Err(CliError::Usage(error.n38_message()));
                 }
-                Err(error) => return Err(CliError::Usage(error.n38_message())),
             };
         let mut value = send_to_named_pane_direct(
             &args.workspace,
@@ -786,6 +810,119 @@ fn add_send_reminder_if_ok(value: &mut Value) {
     }
 }
 
+/// E6 (0.5.9 offline-mailbox-toname-design §§3.1/6.2/8, real-machine
+/// escape evidence
+/// `.team/artifacts/0.5.9-subscription-gate.md` +
+/// `.team/evidence/0.5.9-subscription-gate-20260707T143241Z-4645/`):
+/// when the `--to-name <ws>::<team>/leader` resolver refused with
+/// `leader_not_attached`, decide whether the target team is still alive
+/// (worker + coordinator running without a bound leader) and, if so,
+/// enqueue the mailbox row so `attach-leader` replays it exactly once.
+///
+/// Only queues for third-party senders (sender workspace ≠ target
+/// workspace). Owner-scope refusals stay refused so status/diagnose can
+/// keep pushing the operator toward `attach-leader`.
+fn maybe_enqueue_offline_leader_mailbox(
+    sender_workspace: &Path,
+    to_name: &str,
+    content: &str,
+    sender: &str,
+    task_id: Option<&str>,
+    error: &crate::cli::named_address::NamedAddressError,
+) -> Result<Option<Value>, CliError> {
+    if error.kind != crate::cli::named_address::NamedAddressErrorKind::LeaderNotAttached {
+        return Ok(None);
+    }
+    let parsed = match crate::cli::named_address::parse_leader_target_workspace_and_team(
+        sender_workspace,
+        to_name,
+    ) {
+        Ok(Some(v)) => v,
+        Ok(None) => return Ok(None),
+        Err(_) => return Ok(None),
+    };
+    let (target_workspace, team_key) = parsed;
+    // Owner-scope refusal: sender workspace == target workspace. Keep
+    // the actionable attach hint (owner sees status/diagnose copy that
+    // points at `attach-leader`).
+    let sender_canonical = std::fs::canonicalize(sender_workspace)
+        .unwrap_or_else(|_| sender_workspace.to_path_buf());
+    let target_canonical = std::fs::canonicalize(&target_workspace)
+        .unwrap_or_else(|_| target_workspace.clone());
+    if sender_canonical == target_canonical {
+        return Ok(None);
+    }
+    // Verify the target team is actually alive on this host — mailbox
+    // is only for `team live + leader unattached`. Fail-closed otherwise
+    // so we never leave a message in a permanently-dead workspace's DB.
+    let state = match crate::state::persist::load_runtime_state(&target_workspace) {
+        Ok(s) => s,
+        Err(_) => return Ok(None),
+    };
+    let team_alive = target_team_is_alive_for_mailbox(&state, &team_key);
+    if !team_alive {
+        return Ok(None);
+    }
+    let event_log = crate::event_log::EventLog::new(&target_workspace);
+    let task = task_id.map(|s| crate::model::ids::TaskId::new(s.to_string()));
+    let outcome = messaging::enqueue_leader_mailbox_until_attach(
+        &target_workspace,
+        &team_key,
+        content,
+        task.as_ref(),
+        sender,
+        &event_log,
+    )
+    .map_err(|e| CliError::Runtime(e.to_string()))?;
+    let message_id = outcome
+        .message_id
+        .clone()
+        .unwrap_or_else(|| "".to_string());
+    Ok(Some(json!({
+        "ok": true,
+        "status": "queued_until_leader_attach",
+        "message_status": "queued_until_leader_attach",
+        "channel": "leader_mailbox",
+        "delivered": false,
+        "to_name": to_name,
+        "target_workspace": target_workspace.display().to_string(),
+        "team_key": team_key,
+        "recipient": "leader",
+        "leader_attached": false,
+        "message_id": message_id,
+    })))
+}
+
+/// Positive-source liveness heuristic per offline-mailbox-toname-design.md §4:
+/// - target workspace has state and the team key is present + not archived/down;
+/// - AND at least one live tmux fact — a persisted `session_name` OR any
+///   agent with a recorded pane on the recorded socket.
+///
+/// We deliberately do NOT poll coordinator health here — enqueuing is
+/// safe even when the coordinator is transiently down; attach-leader
+/// itself replays via `requeue_blocked_leader_messages` regardless.
+fn target_team_is_alive_for_mailbox(state: &Value, team_key: &str) -> bool {
+    let team = state
+        .get("teams")
+        .and_then(|v| v.as_object())
+        .and_then(|teams| teams.get(team_key));
+    let Some(team) = team else {
+        return false;
+    };
+    let status = team
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("alive");
+    if matches!(status, "archived" | "down" | "stopped") {
+        return false;
+    }
+    // A recorded session_name is enough — target's coordinator/attach
+    // path will re-verify tmux presence when the replay fires.
+    team.get("session_name")
+        .and_then(|v| v.as_str())
+        .is_some_and(|s| !s.is_empty())
+}
+
 fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
     let exit = if value.get("ok").and_then(Value::as_bool) == Some(false) {
         ExitCode::Error

package/crates/team-agent/src/leader/lease.rs

@@ -50,7 +50,7 @@ pub fn attach_leader(
     if let Some(endpoint) = target.endpoint.as_ref() {
         receiver.tmux_socket = Some(endpoint.clone());
     }
-    let validation = validate_attach_target(workspace, &state, &target.info);
+    let validation = validate_attach_target(workspace, &state, &target.info, provider);
     if validation.is_err() {
         let pane_info = pane_info_value(&target.info);
         let targets_value = Value::Array(targets.iter().map(|target| pane_info_value(&target.info)).collect());
@@ -66,6 +66,7 @@ pub fn attach_leader(
             LeaseSource::Manual,
             &event_log,
         )? {
+            if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
             let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
             return Ok(LeaseResult {
                 ok: true,
@@ -98,6 +99,7 @@ pub fn attach_leader(
             super::LeaderEvent::ReceiverAttached.name(),
             json!({"pane_id": pane_id.as_str(), "owner_epoch": epoch.0}),
         )?;
+        if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
         let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
         return Ok(LeaseResult {
             ok: true,
@@ -121,6 +123,7 @@ pub fn attach_leader(
         super::LeaderEvent::ReceiverAttached.name(),
         json!({"pane_id": pane_id.as_str(), "owner_epoch": next_epoch.0}),
     )?;
+    if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
     let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
     Ok(LeaseResult {
         ok: true,
@@ -134,6 +137,63 @@ pub fn attach_leader(
     })
 }
 
+/// 0.5.9 (E6 real-machine e2e wiring): Fake-provider leader panes in the
+/// e2e harness run `/bin/cat`, which lets the TTY driver echo every
+/// injected byte AND then prints the same bytes on stdout — so pane
+/// capture ends up with two copies of every delivered token. Real Codex/
+/// Claude/Copilot binaries drive the pane through their own TUI and never
+/// echo raw input, so they don't need this. Attach-leader is the
+/// canonical binding hook for this pane, so it's the right place to
+/// disable the TTY echo bit once. Best-effort: any failure is silent
+/// (Fake-provider binding stays useful even without echo suppression).
+///
+/// N16/CP-1 (`.team/anchors/REQUIREMENTS.md`): all tmux invocations MUST
+/// go through the `TmuxBackend` single entry point. The pane's tty query
+/// is done via `TmuxBackend::for_tmux_endpoint(endpoint).query(...,
+/// PaneField::PaneTty)` — socket-scoped by construction. The `stty` call
+/// itself is not a tmux operation, so it uses `Command` directly.
+fn quiet_fake_leader_pane_echo(provider: Provider, target: &PaneInfo, endpoint: &str) {
+    use crate::transport::{PaneField, Target as TransportTarget};
+    if !matches!(provider, Provider::Fake) {
+        return;
+    }
+    if endpoint.is_empty() {
+        return;
+    }
+    let backend = crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint);
+    let Ok(Some(tty)) = <crate::tmux_backend::TmuxBackend as crate::transport::Transport>::query(
+        &backend,
+        &TransportTarget::Pane(target.pane_id.clone()),
+        PaneField::PaneTty,
+    ) else {
+        return;
+    };
+    if tty.trim().is_empty() {
+        return;
+    }
+    // stty against the pane's tty flips the terminal driver's echo bit
+    // without asking the pane process (`/bin/cat`) to interpret any
+    // command. Best-effort: failure is silent.
+    //
+    // Cross-platform tty-file flag: macOS/BSD uses `-f <file>`; GNU
+    // coreutils on Linux uses `-F <file>`. CI runs on Linux and the
+    // previous BSD-only invocation silently no-op'd there — the token
+    // was double-injected because echo stayed on. Try `-F` first (Linux
+    // is the CI baseline), then fall back to `-f` on macOS. Both are
+    // safe to run: the wrong-platform variant just fails silently.
+    let tty = tty.trim();
+    let linux_ok = std::process::Command::new("stty")
+        .args(["-F", tty, "-echo"])
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false);
+    if !linux_ok {
+        let _ = std::process::Command::new("stty")
+            .args(["-f", tty, "-echo"])
+            .output();
+    }
+}
+
 /// Explicit app-server leader binding. Validates the supplied socket/thread tuple
 /// before writing the typed physical-channel anchor through the lease primitive.
 pub fn attach_app_server_leader(
@@ -824,9 +884,26 @@ fn validate_attach_target(
     workspace: &Path,
     state: &Value,
     target: &PaneInfo,
+    requested_provider: Provider,
 ) -> Result<(), &'static str> {
-    let Some(claim_target) = claim_target_from_pane_info(workspace, target) else {
-        return Err("leader_pane_validation_failed");
+    // 0.5.9 (E6 real-machine e2e wiring): an explicit `--provider fake`
+    // is the operator's declaration that this pane is a fake-provider
+    // stub for tests / fixtures. The normal pane-command attribution
+    // path can't recognize `/bin/cat` (or any bare shell process) as a
+    // provider, so honoring the explicit request here is the only way
+    // real-machine E6 acceptance can spin up a leader without shipping
+    // a real Codex/Claude/Copilot binary. This is a targeted escape
+    // hatch — `Provider::Fake` is not selectable from the user-facing
+    // provider list, only wired in test/fixture flows.
+    let claim_target = match claim_target_from_pane_info(workspace, target) {
+        Some(target) => Some(target),
+        None if matches!(requested_provider, Provider::Fake) => None,
+        None => return Err("leader_pane_validation_failed"),
+    };
+    let Some(claim_target) = claim_target else {
+        // Fake provider: skip session-uuid check since attribution was
+        // bypassed. Nothing else to validate.
+        return Ok(());
     };
     let recorded_uuid = get_path_str(state, &["team_owner", "leader_session_uuid"])
         .or_else(|| get_path_str(state, &["leader_receiver", "leader_session_uuid"]));

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/crates/team-agent/src/transport/tests/mod.rs

@@ -108,6 +108,7 @@
                 PaneField::PaneCurrentCommand => "sh",
                 PaneField::PaneCurrentPath => "/tmp/ws",
                 PaneField::SessionName => "team-sess",
+                PaneField::PaneTty => "/dev/ttys000",
             };
             Ok(Some(value.to_string()))
         }

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

@@ -201,6 +201,11 @@ pub enum PaneField {
     PaneCurrentCommand,
     PaneCurrentPath,
     SessionName,
+    /// pane's controlling tty (e.g. `/dev/ttys015`). Consumers use it to
+    /// flip terminal driver bits like `stty -f <tty> -echo` from outside
+    /// tmux's control channel — the query itself still goes through the
+    /// backend so N16/CP-1 (single tmux entry point) stays intact.
+    PaneTty,
 }
 
 /// 后端种类(诊断/事件用)。
@@ -843,6 +848,7 @@ pub fn tmux_query_argv(pane: &PaneId, field: PaneField) -> Vec<String> {
         PaneField::PaneCurrentCommand => "#{pane_current_command}",
         PaneField::PaneCurrentPath => "#{pane_current_path}",
         PaneField::SessionName => "#{session_name}",
+        PaneField::PaneTty => "#{pane_tty}",
     };
     let mut argv = vec![
         "tmux".to_string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.9",
+  "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.9",
-    "@team-agent/cli-darwin-x64": "0.5.9",
-    "@team-agent/cli-linux-x64": "0.5.9"
+    "@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",