@team-agent/installer 0.3.24 → 0.3.26

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

@@ -555,12 +555,26 @@ pub(crate) fn adaptive_placement_for_agent(
     if !state_uses_adaptive_layout(state) {
         return None;
     }
-    let live_panes: BTreeSet<String> = transport
-        .list_targets()
-        .unwrap_or_default()
-        .into_iter()
+    // E43 Fix A (0.3.24 bug#3, demo-director blocker): cross-check live panes
+    // by both pane_id AND window_name. Real-machine state can carry a stale
+    // `layout_window` residue (e.g. "team-w2") while the live pane for that
+    // agent actually lives under a DIFFERENT window_name (e.g. "architect").
+    // The prior pane_id-only check let the stale claim slip through, and the
+    // resulting placement asked spawn_agent_window to split a phantom window.
+    let live_targets = transport.list_targets().unwrap_or_default();
+    let live_panes: BTreeSet<String> = live_targets
+        .iter()
         .map(|pane| pane.pane_id.as_str().to_string())
         .collect();
+    // Map pane_id → window_name for the window-name cross-check.
+    let live_pane_window: BTreeMap<String, String> = live_targets
+        .iter()
+        .filter_map(|pane| {
+            pane.window_name
+                .as_ref()
+                .map(|name| (pane.pane_id.as_str().to_string(), name.as_str().to_string()))
+        })
+        .collect();
     let live_windows: BTreeSet<String> = transport
         .list_windows(session_name)
         .unwrap_or_default()
@@ -581,10 +595,32 @@ pub(crate) fn adaptive_placement_for_agent(
             else {
                 continue;
             };
-            let pane_live = agent
+            // E45 (0.3.24 bug#4): only canonical `team-w<N>[-suffix]` windows
+            // count as adaptive layout windows. Per-agent windows (named
+            // after agent_id like `developer`) are NOT layout windows even if
+            // the state's `layout_window`/`layout_index` carries them — those
+            // are residue from a prior launch or explicit per-agent topology.
+            // Treating them as adaptive caused add-agent to split into the
+            // developer worker's pane on macmini (split-window -t :developer
+            // succeeded → 2 panes in developer window, no new window for
+            // demo-director).
+            if !is_adaptive_layout_window(window) {
+                continue;
+            }
+            let pane_id = agent
                 .get("pane_id")
-                .and_then(serde_json::Value::as_str)
-                .is_some_and(|pane| live_panes.contains(pane));
+                .and_then(serde_json::Value::as_str);
+            let pane_live = pane_id.is_some_and(|pane| live_panes.contains(pane));
+            // E43 Fix A: window_name match — when the agent's pane is live,
+            // its live window_name MUST equal the claimed `window`; otherwise
+            // the claim is stale residue from a respawn/rename and must not
+            // count toward the layout map.
+            let pane_window_matches = pane_id
+                .and_then(|pane| live_pane_window.get(pane))
+                .is_some_and(|name| name == window);
+            if pane_live && !pane_window_matches {
+                continue;
+            }
             if !pane_live && (!live_panes.is_empty() || !live_windows.contains(window)) {
                 continue;
             }
@@ -611,6 +647,17 @@ pub(crate) fn adaptive_placement_for_agent(
             });
         }
     }
+    // E45 (0.3.24 bug#4): when the live session has NO real adaptive layout
+    // window (the topology is effectively per-agent, even though state says
+    // display_backend=adaptive), DO NOT synthesise a fresh `team-w<N>`
+    // window — that would force the new agent into an adaptive-layout pane
+    // shape the rest of the session does not actually use. Return None so
+    // the caller (`start_agent_at_paths` → `spawn_agent_window`) falls back
+    // to its non-placement path, which opens a new window named after the
+    // agent_id (canonical per-agent pattern, matches the existing 7 workers).
+    if windows.is_empty() {
+        return None;
+    }
     let next_index = windows.keys().next_back().map(|idx| idx + 1).unwrap_or(0);
     let base = format!("team-w{}", next_index + 1);
     Some(LayoutPlacement {
@@ -637,6 +684,14 @@ pub(crate) fn adaptive_existing_placement_for_agent(
         .or_else(|| agent.get("window"))
         .and_then(serde_json::Value::as_str)
         .filter(|window| !window.is_empty())?;
+    // E45 (0.3.24 bug#4): existing-placement is meaningless for a per-agent
+    // window name (e.g. `developer`). Return None and let the caller fall
+    // back to its non-placement spawn path, which opens / reuses a window
+    // named after the agent_id. Only canonical `team-w<N>` windows are
+    // honored as existing adaptive placements.
+    if !is_adaptive_layout_window(window) {
+        return None;
+    }
     let layout_index = agent
         .get("layout_index")
         .and_then(serde_json::Value::as_u64)
@@ -655,12 +710,18 @@ pub(crate) fn adaptive_existing_placement_for_agent(
         .map(|window| window.as_str().to_string())
         .collect();
     if !live_windows.contains(window) {
+        // E43 Fix B (0.3.24 bug#3): the claimed `layout_window` is NOT in
+        // live_windows — it's stale residue. The session is effectively
+        // per-agent (live windows are named after agent_ids), so fall back
+        // to a new window named after the agent_id itself instead of
+        // synthesising a fresh phantom-named window the next spawn would
+        // try (and fail) to split.
         return Some(LayoutPlacement {
             agent_id: agent_id.clone(),
-            layout_window: WindowName::new(window),
+            layout_window: WindowName::new(agent_id.as_str()),
             layout_index,
-            pane_index: desired_pane_index,
-            starts_window: desired_pane_index == 0,
+            pane_index: 0,
+            starts_window: true,
         });
     }
     let existing_panes = transport
@@ -692,6 +753,28 @@ fn parse_team_layout_index(window: &str) -> Option<usize> {
         .and_then(|idx| idx.checked_sub(1))
 }
 
+/// E45 (0.3.24 bug#4, demo-director second-layer drift): a window name is a
+/// REAL adaptive layout window only when it matches the canonical
+/// `team-w<N>[-suffix]` shape (i.e. `parse_team_layout_index` returns Some).
+/// Per-agent window names like `developer` / `architect` / `demo-director`
+/// are NOT adaptive layout windows even if state happens to carry them in
+/// the agent's `layout_window` or `layout_index` field — they are residue
+/// from a prior launch / explicit per-agent topology. Treating them as
+/// adaptive caused the macmini repro: add-agent demo-director split into
+/// the developer worker's window @453 instead of opening its own.
+fn is_adaptive_layout_window(window: &str) -> bool {
+    parse_team_layout_index(window).is_some()
+}
+
+/// Crate-public wrapper for the defensive guard at
+/// `restart/common.rs::spawn_agent_window`. Same semantics as the private
+/// helper above; promoted to `pub(crate)` so the spawn-time defence-in-depth
+/// layer can refuse to split into a per-agent window even if a stale
+/// placement asks for it.
+pub(crate) fn is_adaptive_layout_window_pub(window: &str) -> bool {
+    is_adaptive_layout_window(window)
+}
+
 fn unique_layout_window_name(base: &str, live_windows: &BTreeSet<String>) -> WindowName {
     if !live_windows.contains(base) {
         return WindowName::new(base);
@@ -2917,7 +3000,13 @@ pub fn quick_start_with_transport_in_workspace_with_display(
     })
 }
 
-fn annotate_runtime_tmux_endpoint(state: &mut serde_json::Value, transport: &dyn Transport, workspace: &Path) {
+/// Annotate `state.tmux_endpoint` / `state.tmux_socket` (and `tmux_socket_source`)
+/// from the active transport. Originally only called at `launch_with_transport`
+/// init time; **`0.3.24` opened this to `pub(crate)` so restart/add/fork can keep
+/// the persisted endpoint synchronized with the transport they actually used,
+/// closing the silent socket-drift gap** (single state-save path; no parallel
+/// "annotate after spawn" race with coordinator).
+pub(crate) fn annotate_runtime_tmux_endpoint(state: &mut serde_json::Value, transport: &dyn Transport, workspace: &Path) {
     let Some(endpoint) = transport.tmux_endpoint() else {
         return;
     };
@@ -3360,19 +3449,41 @@ pub fn add_agent(
     ) {
         Ok(selected) => selected,
         Err(_) if workspace.join("TEAM.md").exists() => {
+            // **0.3.24 add-agent socket drift fix**: even on the TEAM.md fallback
+            // path (no spec yet), prefer the state-aware resolver. It reads the
+            // team's persisted `tmux_endpoint` (set at `team-agent launch` time)
+            // and routes the new agent's spawn to the SAME tmux socket the live
+            // team uses. Cold workspaces / first-agent paths safely fall back to
+            // `TmuxBackend::for_workspace(team_workspace)` inside the resolver.
+            let team_ws = team_workspace(workspace);
+            let transport = crate::lifecycle::restart::lifecycle_worker_tmux_backend_for_selected_state(
+                &team_ws, team,
+            )
+            .unwrap_or_else(|_| crate::tmux_backend::TmuxBackend::for_workspace(&team_ws));
             return add_agent_with_transport(
                 workspace,
                 agent_id,
                 role_file_path,
                 open_display,
                 team,
-                &crate::tmux_backend::TmuxBackend::for_workspace(&team_workspace(workspace)),
+                &transport,
             );
         }
         Err(error) => return Err(LifecycleError::TeamSelect(error.to_string())),
     };
     // E5 §3:compile_team 要角色定义目录(team_dir),不是 spec 落点(spec_workspace=runtime)。
     let team_dir = selected.team_dir;
+    // **0.3.24 add-agent socket drift fix**: route to the live team's persisted
+    // tmux endpoint (NOT the workspace-hash for_workspace socket). Without this,
+    // `add-agent` spawns into an orphan socket (e.g. `ta-<hash>/termclaud`) while
+    // the live team runs on its persisted default socket — the leader can't see
+    // the new window, state never registers, and the orphaned `claude` process
+    // floats forever (macmini repro: `demo-director` startup blocker).
+    let transport = crate::lifecycle::restart::lifecycle_worker_tmux_backend_for_selected_state(
+        &selected.run_workspace,
+        Some(selected.team_key.as_str()),
+    )
+    .unwrap_or_else(|_| crate::tmux_backend::TmuxBackend::for_workspace(&selected.run_workspace));
     add_agent_with_transport_at_paths(
         &selected.run_workspace,
         &team_dir,
@@ -3380,7 +3491,7 @@ pub fn add_agent(
         role_file_path,
         open_display,
         Some(selected.team_key.as_str()),
-        &crate::tmux_backend::TmuxBackend::for_workspace(&selected.run_workspace),
+        &transport,
     )
 }
 
@@ -3463,18 +3574,40 @@ fn add_agent_with_transport_at_paths(
     let safety = effective_runtime_config(&spec)?;
     // E5 spec 迁移:重编译的 spec 原子写到 .team/runtime/<team_key>/(不落用户目录 team_dir)。
     let spec_path = crate::model::paths::runtime_spec_path(run_workspace, &canonical_team_key);
+    // E42 (0.3.24 P0): capture pre-write bytes for atomic rollback. If anything
+    // downstream of write_spec_atomic + upsert_agent_state_from_role + spawn
+    // fails, restore the prior bytes so the canonical spec / runtime state never
+    // get a half-written row that disagrees with what remove-agent can see.
+    let pre_spec_text = match std::fs::read_to_string(&spec_path) {
+        Ok(text) => Some(text),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
+        Err(e) => return Err(LifecycleError::StatePersist(format!("read spec: {e}"))),
+    };
+    let pre_runtime_state = crate::state::persist::load_runtime_state(run_workspace).ok();
     write_spec_atomic(&spec_path, &spec)?;
     let (meta, _) = crate::compiler::read_front_matter(role_file_path)
         .map_err(|e| LifecycleError::Compile(e.to_string()))?;
-    upsert_agent_state_from_role(
+    // upsert writes status="starting" (E42) — start_agent_at_paths::mark_agent_started
+    // promotes to "running" on Ok. If anything fails between here and the Ok
+    // return below, rollback restores the captured pre-bytes.
+    if let Err(error) = upsert_agent_state_from_role(
         run_workspace,
         &canonical_team_key,
         agent_id,
         &meta,
         role_file_path,
         &safety,
-    )?;
-    let started = crate::lifecycle::restart::start_agent_at_paths(
+    ) {
+        rollback_add_agent_atomic(
+            run_workspace,
+            &spec_path,
+            pre_spec_text.as_deref(),
+            pre_runtime_state.as_ref(),
+            agent_id,
+        );
+        return Err(error);
+    }
+    let started = match crate::lifecycle::restart::start_agent_at_paths(
         run_workspace,
         team_dir,
         agent_id,
@@ -3483,13 +3616,32 @@ fn add_agent_with_transport_at_paths(
         true,
         Some(&canonical_team_key),
         transport,
-    )?;
+    ) {
+        Ok(started) => started,
+        Err(error) => {
+            rollback_add_agent_atomic(
+                run_workspace,
+                &spec_path,
+                pre_spec_text.as_deref(),
+                pre_runtime_state.as_ref(),
+                agent_id,
+            );
+            return Err(error);
+        }
+    };
     let (env, start_mode) = match started {
         StartAgentOutcome::Running {
             env, start_mode, ..
         } => (env, start_mode),
         StartAgentOutcome::Noop { env, .. } => (env, StartMode::Noop),
         StartAgentOutcome::Paused { .. } => {
+            rollback_add_agent_atomic(
+                run_workspace,
+                &spec_path,
+                pre_spec_text.as_deref(),
+                pre_runtime_state.as_ref(),
+                agent_id,
+            );
             return Err(LifecycleError::RequirementUnmet(format!(
                 "added agent {agent_id} is paused"
             )));
@@ -3502,6 +3654,40 @@ fn add_agent_with_transport_at_paths(
     })
 }
 
+/// E42 (0.3.24 P0, double-spec deadlock): best-effort atomic rollback for a
+/// failed add-agent. Restores the canonical spec to its pre-write bytes (or
+/// removes the file if it didn't exist), and restores runtime state to its
+/// pre-write JSON (so the half-written `status:starting` row is gone). The
+/// caller propagates the ORIGINAL operation error after rollback; rollback
+/// errors are swallowed (best-effort, no panic).
+fn rollback_add_agent_atomic(
+    run_workspace: &Path,
+    spec_path: &Path,
+    pre_spec_text: Option<&str>,
+    pre_runtime_state: Option<&serde_json::Value>,
+    agent_id: &AgentId,
+) {
+    if let Some(text) = pre_spec_text {
+        let _ = std::fs::write(spec_path, text);
+    } else {
+        let _ = std::fs::remove_file(spec_path);
+    }
+    if let Some(state) = pre_runtime_state {
+        let _ = crate::state::persist::save_runtime_state(run_workspace, state);
+    } else {
+        // No prior runtime state — drop just the agent we added (load → strip → save).
+        if let Ok(mut state) = crate::state::persist::load_runtime_state(run_workspace) {
+            if let Some(agents) = state
+                .get_mut("agents")
+                .and_then(serde_json::Value::as_object_mut)
+            {
+                agents.remove(agent_id.as_str());
+            }
+            let _ = crate::state::persist::save_runtime_state(run_workspace, &state);
+        }
+    }
+}
+
 fn upsert_agent_state_from_role(
     workspace: &Path,
     canonical_team_key: &str,
@@ -3544,11 +3730,15 @@ fn upsert_agent_state_from_role(
         .get("role")
         .and_then(Value::as_str)
         .unwrap_or_else(|| agent_id.as_str());
+    // E42 (0.3.24 P0, double-spec deadlock): persist the initial state row as
+    // "starting" (not "running"). The caller (add_agent_with_transport_at_paths)
+    // promotes to "running" only after start_agent_at_paths returns Running.
+    // If the spawn fails, the rollback below removes the entry entirely.
     let mut entry = serde_json::json!({
         "provider": provider,
         "auth_mode": auth_mode,
         "role": role,
-        "status": "running",
+        "status": "starting",
         "dynamic_role_file": dynamic_role_file.to_string_lossy().to_string(),
     });
     if let Some(model) = meta.get("model").and_then(Value::as_str) {
@@ -3675,6 +3865,14 @@ pub fn fork_agent(
         crate::state::selector::SelectorMode::RequireSpec,
     )
     .map_err(|e| LifecycleError::TeamSelect(e.to_string()))?;
+    // **0.3.24 add-agent socket drift fix** (same root cause): fork-agent must
+    // also route to the live team's persisted tmux endpoint, not the workspace-
+    // hash for_workspace socket. Same orphan-on-wrong-socket pathology.
+    let transport = crate::lifecycle::restart::lifecycle_worker_tmux_backend_for_selected_state(
+        &selected.run_workspace,
+        Some(selected.team_key.as_str()),
+    )
+    .unwrap_or_else(|_| crate::tmux_backend::TmuxBackend::for_workspace(&selected.run_workspace));
     fork_agent_with_transport(
         workspace,
         source_agent_id,
@@ -3682,7 +3880,7 @@ pub fn fork_agent(
         label,
         open_display,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&selected.run_workspace),
+        &transport,
     )
 }
 

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

@@ -95,6 +95,16 @@ pub(crate) fn start_agent_at_paths(
     } else {
         window_exists(transport, &session_name, &window)
     };
+    // E51 (0.3.26 P0, restart self-heal): even if the pane is structurally
+    // alive, it must not be considered "this agent's pane" if it's actually
+    // the leader anchor pane or another agent's pane. When lease corruption
+    // (E51 root cause) left `agent.pane_id == leader_receiver.pane_id`,
+    // start_agent would short-circuit to Noop (the pane IS live — it's just
+    // the wrong pane). Force a fresh spawn by treating the pane as not-live
+    // when it conflicts with the leader or a different agent.
+    let agent_live = agent_live && !pane_conflicts_with_leader_or_other(
+        &state, agent_id, &agent,
+    );
     if !force && agent_live {
         mark_agent_running_noop(&mut state, agent_id, &session_name, &window)?;
         let team_key = restart_projection_team_key(&state, team);
@@ -185,8 +195,33 @@ pub(crate) fn start_agent_at_paths(
         None,
     )?;
     mark_agent_started(&mut state, agent_id, &spawn_window, &spawn, transport, &safety)?;
+    // **0.3.24 add-agent socket drift fix**: keep `state.tmux_endpoint` /
+    // `state.tmux_socket` synchronized with the transport actually used for the
+    // spawn. Without this, add-agent / fork-agent could spawn to a socket that
+    // never gets persisted, and the next coordinator tick would re-resolve to
+    // the workspace-hash socket and lose the new pane. Annotation runs inside
+    // the same `save_restart_projected_state` window — no parallel "annotate
+    // after spawn" race with coordinator and no double source of truth.
+    crate::lifecycle::launch::annotate_runtime_tmux_endpoint(&mut state, transport, workspace);
     let team_key = restart_projection_team_key(&state, team);
     save_restart_projected_state(workspace, &mut state, &team_key)?;
+    // **0.3.24 reachability gate (调整 4)** — strict, non-capture verification
+    // that the spawn actually produced an addressable window/pane on the
+    // transport's socket. Catches the macmini假绿 (`ok=true` returned by
+    // `add_agent` while the spawned `claude` process orphaned on a different
+    // socket and the leader never registered it). We use `has_pane` /
+    // `liveness` / `list_targets` (structural addressing only) — never
+    // `capture` — to avoid contention with E31's pane-readback gate timing.
+    if !spawned_pane_is_reachable(transport, &spawn.spawn.pane_id) {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "add-agent spawn unreachable: pane {} not addressable on transport \
+             socket {:?} (likely socket drift — see 0.3.24 fix); the agent \
+             process may have orphaned on a different tmux socket. Re-run after \
+             confirming the team's tmux_endpoint persisted via `team-agent status`.",
+            spawn.spawn.pane_id.as_str(),
+            transport.tmux_endpoint().unwrap_or_default()
+        )));
+    }
     write_start_agent_start_event(
         workspace,
         agent_id,
@@ -213,6 +248,87 @@ pub(crate) fn start_agent_at_paths(
     })
 }
 
+/// **0.3.24 strict-non-capture reachability gate**. Returns `true` IFF the spawn's
+/// pane is currently addressable on the transport's tmux socket. Uses structural
+/// addressing only (`has_pane` → `liveness` → `list_targets`) — **never**
+/// `capture` — so it does not race with E31's pane-readback gate timing
+/// (E31 reads pane contents after submit; running our own capture here would
+/// either consume the first-paste tokens E31 looks for, or vice versa).
+///
+/// The gate fires after `mark_agent_started` + `save_restart_projected_state`,
+/// so an unreachable pane returns a structured `LifecycleError` that the CLI
+/// surface translates to `ok=false`, replacing the macmini假绿
+/// (`ok=true` with orphaned-on-wrong-socket spawn).
+fn spawned_pane_is_reachable(
+    transport: &dyn crate::transport::Transport,
+    pane: &crate::transport::PaneId,
+) -> bool {
+    // (a) authoritative: has_pane Some(true) → addressable.
+    if matches!(transport.has_pane(pane), Ok(Some(true))) {
+        return true;
+    }
+    // (b) liveness probe: not-Dead → addressable. Dead → unreachable.
+    if matches!(
+        transport.liveness(pane),
+        Ok(crate::model::enums::PaneLiveness::Live)
+    ) {
+        return true;
+    }
+    // (c) last resort: enumeration. If the pane appears in `list_targets()`
+    // (cross-session enumeration on the socket), it is addressable.
+    if let Ok(targets) = transport.list_targets() {
+        if targets.iter().any(|t| t.pane_id.as_str() == pane.as_str()) {
+            return true;
+        }
+    }
+    false
+}
+
+/// 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
+/// pane as "this agent's live pane" (it should spawn fresh).
+fn pane_conflicts_with_leader_or_other(
+    state: &serde_json::Value,
+    agent_id: &crate::model::ids::AgentId,
+    agent: &serde_json::Value,
+) -> bool {
+    let Some(pane_id) = agent
+        .get("pane_id")
+        .and_then(serde_json::Value::as_str)
+        .filter(|s| !s.is_empty())
+    else {
+        return false;
+    };
+    // Check leader anchor.
+    for key in ["leader_receiver", "team_owner"] {
+        if state
+            .get(key)
+            .and_then(|v| v.get("pane_id"))
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|lp| lp == pane_id)
+        {
+            return true;
+        }
+    }
+    // Check other agents.
+    if let Some(agents) = state.get("agents").and_then(serde_json::Value::as_object) {
+        for (id, other) in agents {
+            if id == agent_id.as_str() {
+                continue;
+            }
+            if other
+                .get("pane_id")
+                .and_then(serde_json::Value::as_str)
+                .is_some_and(|op| op == pane_id)
+            {
+                return true;
+            }
+        }
+    }
+    false
+}
+
 fn agent_pane_live(
     transport: &dyn crate::transport::Transport,
     agent: &serde_json::Value,

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

@@ -157,6 +157,29 @@ pub(super) fn spawn_agent_window(
                     &env_unset,
                 )
             }
+        } else if !window_present_in_live(transport, session_name, &window)
+            || !crate::lifecycle::launch::is_adaptive_layout_window_pub(window.as_str())
+        {
+            // E43 Fix C + E45 (0.3.24 bug#3 → bug#4): never split into a
+            // window that either does not exist on live tmux OR is a
+            // per-agent window (`developer`, `architect`, ...) that the
+            // upstream placement guards should have refused. This is the
+            // defence-in-depth layer; the primary fix is in
+            // `adaptive_placement_for_agent` / `adaptive_existing_placement_for_agent`,
+            // but a placement built from stale `pane_index>0` state can
+            // still ask to split a per-agent window — and the macmini repro
+            // showed split-window -t :developer would otherwise succeed and
+            // hijack the developer worker's pane. Downgrade to spawn_into
+            // (new window named after agent_id) — canonical per-agent
+            // fallback the existing 7 workers use.
+            transport.spawn_into_with_env_unset(
+                session_name,
+                &WindowName::new(agent_id.as_str()),
+                &plan.argv,
+                spawn_cwd,
+                &env,
+                &env_unset,
+            )
         } else {
             transport.spawn_split_with_env_unset(
                 session_name,
@@ -211,6 +234,33 @@ pub(super) fn spawn_agent_window(
     })
 }
 
+/// E43 Fix C helper (0.3.24 bug#3): probe live tmux for a window's existence
+/// before issuing `split-window -t :<window>`. Uses `list_windows` first
+/// (cheaper, authoritative when present); falls back to `list_targets` so
+/// transports that don't seed `windows` directly still surface real entries.
+fn window_present_in_live(
+    transport: &dyn crate::transport::Transport,
+    session: &SessionName,
+    window: &WindowName,
+) -> bool {
+    if let Ok(windows) = transport.list_windows(session) {
+        if windows.iter().any(|w| w.as_str() == window.as_str()) {
+            return true;
+        }
+    }
+    if let Ok(targets) = transport.list_targets() {
+        if targets.iter().any(|t| {
+            t.session.as_str() == session.as_str()
+                && t.window_name
+                    .as_ref()
+                    .is_some_and(|n| n.as_str() == window.as_str())
+        }) {
+            return true;
+        }
+    }
+    false
+}
+
 pub(super) fn start_coordinator_for_workspace(workspace: &Path) -> Result<bool, LifecycleError> {
     let workspace = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
     crate::coordinator::start_coordinator(&workspace)
@@ -218,7 +268,22 @@ pub(super) fn start_coordinator_for_workspace(workspace: &Path) -> Result<bool,
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))
 }
 
-pub(super) fn lifecycle_worker_tmux_backend_for_selected_state(
+/// State-aware tmux backend resolver. Reads the team's persisted
+/// `tmux_endpoint` (set at `team-agent launch` time and shared across
+/// restart/add-agent/fork-agent) and constructs a TmuxBackend on THAT socket,
+/// so add-agent / fork-agent / restart all spawn into the SAME tmux socket
+/// the live team already runs on.
+///
+/// First-agent / cold workspace (no persisted endpoint) safely falls back to
+/// `TmuxBackend::for_workspace(run_workspace)` — the canonical workspace-hash
+/// socket. No panic, no None.
+///
+/// **Exposed `pub(crate)` for `lifecycle::launch::add_agent` / `fork_agent`
+/// (`0.3.24 add-agent socket drift fix`). Previously `pub(super)` and shared
+/// only within `lifecycle::restart`. Sharing the resolver across the lifecycle
+/// module is the correct ownership: restart/add/fork all need the SAME socket
+/// the live team uses, and duplicating the lookup invited drift.**
+pub(crate) fn lifecycle_worker_tmux_backend_for_selected_state(
     run_workspace: &Path,
     team: Option<&str>,
 ) -> Result<crate::tmux_backend::TmuxBackend, LifecycleError> {

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

@@ -34,6 +34,10 @@ mod team_state;
 pub use agent::{reset_agent, reset_agent_with_transport, start_agent, start_agent_with_transport, stop_agent, stop_agent_with_transport};
 pub(crate) use agent::start_agent_at_paths;
 pub(crate) use common::refresh_missing_provider_sessions;
+// 0.3.24 add-agent socket drift fix: state-aware tmux resolver shared with
+// `lifecycle::launch::add_agent` / `fork_agent` so all three (restart / add / fork)
+// route to the SAME tmux socket the live team uses.
+pub(crate) use common::lifecycle_worker_tmux_backend_for_selected_state;
 pub use orchestrator::{halt_plan, plan_status};
 pub use rebuild::{
     restart, restart_candidates, restart_with_session_convergence_deadline, restart_with_transport,
@@ -66,8 +70,21 @@ fn lifecycle_paths(workspace: &Path, team: Option<&str>) -> Result<LifecyclePath
         crate::state::selector::SelectorMode::RequireSpec,
     )
     .map_err(|e| LifecycleError::TeamSelect(e.to_string()))?;
-    let spec_workspace = selected_state_spec_workspace(&selected.state)
-        .or(selected.spec_workspace)
+    // E42 (0.3.24 P0, double-spec deadlock): canonical-first. The selector at
+    // state/selector.rs:71-74 already sets `selected.spec_workspace` to the
+    // canonical runtime spec parent (.team/runtime/<key>/) whenever the
+    // runtime spec exists; only when the runtime spec is missing does it fall
+    // back to the legacy user-dir spec_workspace. Honoring that first stops
+    // remove-agent / stop-agent / reset-agent / fork-agent from reading a
+    // stale `state.spec_path` (legacy `.team/<key>/team.spec.yaml`) that
+    // disagrees with what add-agent writes to canonical
+    // (lifecycle/launch.rs:3576-3577). Pre-fix order let the legacy stale
+    // spec win and remove-agent couldn't see agents add-agent had just
+    // added — the macmini e46-probe deadlock truth source.
+    let spec_workspace = selected
+        .spec_workspace
+        .clone()
+        .or_else(|| selected_state_spec_workspace(&selected.state))
         .ok_or_else(|| LifecycleError::TeamSelect("active team spec workspace not found".to_string()))?;
     Ok(LifecyclePaths {
         run_workspace: selected.run_workspace,