@team-agent/installer 0.4.10 → 0.5.0

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

@@ -1,7 +1,8 @@
-use super::*;
 use super::common::*;
 use super::selection::decide_start_mode;
 use super::team_state::write_team_state;
+use super::*;
+use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest};
 
 /// `start_agent(workspace, agent_id, force, open_display, allow_fresh, team)`
 /// (`lifecycle/start.py:72`)。`_runtime_lock("start-agent")` 下串行:resume-or-fresh
@@ -17,8 +18,13 @@ pub fn start_agent(
     team: Option<&str>,
 ) -> Result<StartAgentOutcome, LifecycleError> {
     let paths = lifecycle_paths(workspace, team)?;
-    let transport =
-        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "start-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
+    let transport = lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
     start_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -43,9 +49,23 @@ pub fn start_agent_with_transport(
     team: Option<&str>,
     transport: &dyn crate::transport::Transport,
 ) -> Result<StartAgentOutcome, LifecycleError> {
+    let paths = match lifecycle_paths(workspace, team) {
+        Ok(paths) => paths,
+        Err(_) if team.is_none() => LifecyclePaths {
+            run_workspace: workspace.to_path_buf(),
+            spec_workspace: workspace.to_path_buf(),
+        },
+        Err(error) => return Err(error),
+    };
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "start-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
     start_agent_at_paths(
-        workspace,
-        workspace,
+        &paths.run_workspace,
+        &paths.spec_workspace,
         agent_id,
         force,
         open_display,
@@ -74,24 +94,27 @@ pub(crate) fn start_agent_at_paths(
             .map_err(|e| LifecycleError::StatePersist(e.to_string()))?
     };
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, Some(agent_id))?;
-    let agent = state
+    let raw_agent = state
         .get("agents")
         .and_then(|v| v.get(agent_id.as_str()))
         .ok_or_else(|| LifecycleError::RequirementUnmet(format!("agent {agent_id} not found")))?
         .clone();
-    if agent
+    let agent = rehydrate_agent_command_context_from_spec(spec_workspace, agent_id, &raw_agent);
+    if raw_agent
         .get("paused")
         .and_then(serde_json::Value::as_bool)
         .unwrap_or(false)
     {
-        return Ok(StartAgentOutcome::Paused { agent_id: agent_id.clone() });
+        return Ok(StartAgentOutcome::Paused {
+            agent_id: agent_id.clone(),
+        });
     }
     let session_name = state_session_name(&state);
     let window = agent_window(&agent, agent_id);
     let adaptive_layout =
         open_display && crate::lifecycle::launch::state_uses_adaptive_layout(&state);
     let agent_live = if adaptive_layout {
-        agent_pane_live(transport, &agent)
+        agent_pane_live(transport, &raw_agent)
     } else {
         window_exists(transport, &session_name, &window)
     };
@@ -103,7 +126,7 @@ pub(crate) fn start_agent_at_paths(
     // spawn (defensive). The check itself remains a no-op on healthy
     // state — assert_topology_invariants from Step 1 catches the
     // upstream corruption.
-    let has_collision = pane_conflicts_with_leader_or_other(&state, agent_id, &agent);
+    let has_collision = pane_conflicts_with_leader_or_other(&state, agent_id, &raw_agent);
     if has_collision {
         eprintln!(
             "team_agent::layout e51_collision_post_step2 agent_id=`{agent_id}` \
@@ -116,7 +139,7 @@ pub(crate) fn start_agent_at_paths(
     if !force && agent_live {
         mark_agent_running_noop(&mut state, agent_id, &session_name, &window)?;
         let team_key = restart_projection_team_key(&state, team);
-        save_restart_projected_state(workspace, &mut state, &team_key)?;
+        save_restart_projected_state(workspace, &mut state, &team_key, &[agent_id.as_str()])?;
         if let Ok(spec) = load_team_spec(spec_workspace) {
             write_team_state(spec_workspace, &spec, &state)?;
         }
@@ -208,7 +231,22 @@ pub(crate) fn start_agent_at_paths(
         None,
         Some(resolved_team_key.as_str()),
     )?;
-    mark_agent_started(&mut state, agent_id, &spawn_window, &spawn, transport, &safety, start_mode)?;
+    verify_spawned_pane_matches_target(
+        transport,
+        &spawn.spawn.pane_id,
+        &session_name,
+        &spawn.spawn.window,
+    )?;
+    let actual_spawn_window = spawn.spawn.window.as_str().to_string();
+    mark_agent_started(
+        &mut state,
+        agent_id,
+        &actual_spawn_window,
+        &spawn,
+        transport,
+        &safety,
+        start_mode,
+    )?;
     // **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
@@ -218,24 +256,7 @@ pub(crate) fn start_agent_at_paths(
     // 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()
-        )));
-    }
+    save_restart_projected_state(workspace, &mut state, &team_key, &[agent_id.as_str()])?;
     write_start_agent_start_event(
         workspace,
         agent_id,
@@ -243,7 +264,7 @@ pub(crate) fn start_agent_at_paths(
         provider,
         start_mode,
         &session_name,
-        &spawn_window,
+        &actual_spawn_window,
         spawn_session_id,
         tmux_start_mode_for_spawn(&spawn, into_existing_session),
     )?;
@@ -262,40 +283,51 @@ 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(
+fn verify_spawned_pane_matches_target(
     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;
+    session: &crate::transport::SessionName,
+    window: &crate::transport::WindowName,
+) -> Result<(), LifecycleError> {
+    let targets = transport
+        .list_targets()
+        .map_err(|e| LifecycleError::Transport(e.to_string()))?;
+    let observed = targets.iter().find(|target| target.pane_id == *pane);
+    let Some(observed) = observed else {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "start refused: spawned pane not addressable on transport socket (possible socket drift); window disappeared or spawned pane not owned by requested agent window; requested={}:{} pane={} observed=<missing>",
+            session.as_str(),
+            window.as_str(),
+            pane.as_str()
+        )));
+    };
+    let observed_window = observed
+        .window_name
+        .as_ref()
+        .map(crate::transport::WindowName::as_str)
+        .unwrap_or("<unknown>");
+    if observed.session.as_str() != session.as_str() || observed_window != window.as_str() {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "start refused: spawned pane not owned by requested agent window; requested={}:{} pane={} observed={}:{}",
+            session.as_str(),
+            window.as_str(),
+            pane.as_str(),
+            observed.session.as_str(),
+            observed_window
+        )));
     }
-    // (b) liveness probe: not-Dead → addressable. Dead → unreachable.
     if matches!(
         transport.liveness(pane),
-        Ok(crate::model::enums::PaneLiveness::Live)
+        Ok(crate::model::enums::PaneLiveness::Dead)
     ) {
-        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;
-        }
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "start refused: spawned pane not addressable on transport socket; pane is dead after spawn; requested={}:{} pane={}",
+            session.as_str(),
+            window.as_str(),
+            pane.as_str()
+        )));
     }
-    false
+    Ok(())
 }
 
 /// E51 (0.3.26 P0, restart self-heal): returns `true` when the agent's pane_id
@@ -318,9 +350,11 @@ fn pane_conflicts_with_leader_or_other(
     let agent_socket = tmux_socket_field(agent).or(state_socket);
     // Check leader anchor.
     for key in ["leader_receiver", "team_owner"] {
-        if state.get(key).and_then(pane_socket_binding).is_some_and(|leader| {
-            pane_conflicts_on_same_socket(pane_id, agent_socket, leader)
-        }) {
+        if state
+            .get(key)
+            .and_then(pane_socket_binding)
+            .is_some_and(|leader| pane_conflicts_on_same_socket(pane_id, agent_socket, leader))
+        {
             return true;
         }
     }
@@ -392,10 +426,7 @@ fn pane_socket_binding(value: &serde_json::Value) -> Option<PaneSocketBinding<'_
     })
 }
 
-fn agent_pane_live(
-    transport: &dyn crate::transport::Transport,
-    agent: &serde_json::Value,
-) -> bool {
+fn agent_pane_live(transport: &dyn crate::transport::Transport, agent: &serde_json::Value) -> bool {
     let Some(pane) = agent
         .get("pane_id")
         .and_then(serde_json::Value::as_str)
@@ -420,6 +451,47 @@ fn agent_pane_live_by_id(
     }
 }
 
+/// 0.4.10+ reset duplicate-window fix (CR-approved, plan §1).
+///
+/// Enumerate live panes whose `(session, window_name)` match the given pair.
+/// Used by `stop_agent_at_paths` (when the stored pane_id is stale/dead but a
+/// same-role window survives) and by the reset hard gate (to prove no
+/// duplicate window residue remains before `start_agent_at_paths`).
+///
+/// `list_targets()` is a point-in-time tmux snapshot — duplicates ARE
+/// preserved in the result so callers can see the full set.
+///
+/// Caller MUST also check `is_per_agent_window(window, agent_id)` before
+/// using this list to kill panes (plan §2 safety constraint): a shared
+/// layout window may host co-tenants.
+fn list_same_role_panes(
+    transport: &dyn crate::transport::Transport,
+    session: &crate::transport::SessionName,
+    window: &str,
+) -> Vec<crate::transport::PaneInfo> {
+    transport
+        .list_targets()
+        .unwrap_or_default()
+        .into_iter()
+        .filter(|pane| {
+            pane.session.as_str() == session.as_str()
+                && pane.window_name.as_ref().map(WindowName::as_str) == Some(window)
+        })
+        .collect()
+}
+
+/// 0.4.10+ reset duplicate-window fix (plan §2 safety constraint).
+///
+/// Returns true only when `window == agent_id`, i.e. the canonical
+/// per-agent window. Adaptive/shared layout windows (`workers`, `team`,
+/// or any layout window name produced by `is_adaptive_layout_window_pub`)
+/// MUST NOT be broad-killed by name — they may host co-tenants. The
+/// caller falls back to safer behavior (refuse stop, surface
+/// RequirementUnmet/transport error) when this returns false.
+fn is_per_agent_window(window: &str, agent_id: &AgentId) -> bool {
+    window == agent_id.as_str() && !crate::lifecycle::launch::is_adaptive_layout_window_pub(window)
+}
+
 fn tmux_start_mode_for_spawn(
     spawn: &SpawnedAgentWindow,
     into_existing_session: bool,
@@ -542,8 +614,13 @@ pub fn stop_agent(
     team: Option<&str>,
 ) -> Result<StopAgentReport, LifecycleError> {
     let paths = lifecycle_paths(workspace, team)?;
-    let transport =
-        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "stop-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
+    let transport = lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
     stop_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -560,6 +637,12 @@ pub fn stop_agent_with_transport(
     transport: &dyn crate::transport::Transport,
 ) -> Result<StopAgentReport, LifecycleError> {
     let paths = lifecycle_paths(workspace, team)?;
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "stop-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
     stop_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -580,8 +663,7 @@ pub(super) fn stop_agent_at_paths(
     let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, Some(agent_id))?;
     let spec = load_team_spec(spec_workspace)?;
-    let agent = find_spec_agent(&spec, agent_id)
-        .ok_or_else(|| unknown_worker(agent_id))?;
+    let agent = find_spec_agent(&spec, agent_id).ok_or_else(|| unknown_worker(agent_id))?;
     let session_name = state_session_name_from_spec(&state, &spec);
     let window = state
         .get("agents")
@@ -602,29 +684,73 @@ pub(super) fn stop_agent_at_paths(
         .as_ref()
         .map(|pane| pane.as_str().to_string())
         .unwrap_or_else(|| format!("{}:{window}", session_name.as_str()));
-    let stopped = pane_id
+    // 0.4.10+ reset duplicate-window fix (plan §2): stop must resolve a
+    // STALE stored pane_id to live same-role panes by `(session, window)`
+    // enumeration BEFORE concluding the worker is absent. Pre-fix logic
+    // returned stopped=false when pane_id was dead even if a residual
+    // duplicate window survived — that residue then collided with
+    // reset's unconditional start, producing the observed
+    // `stopped=false, started=true` duplicate-window pattern.
+    //
+    // Only the STALE-pane-id branch enumerates same-role panes. When
+    // pane_id was never set in state (legacy state shape, never observed
+    // a real spawn), the existing window-based fallback is preserved —
+    // the duplicate-window bug requires a stored-but-stale pane_id as
+    // the trigger.
+    let stored_pane_live = pane_id
         .as_ref()
         .map(|pane| agent_pane_live_by_id(transport, pane))
-        .unwrap_or_else(|| window_exists(transport, &session_name, &window));
+        .unwrap_or(false);
+    let stored_pane_stale = pane_id.is_some() && !stored_pane_live;
+    let same_role_panes: Vec<crate::transport::PaneInfo> =
+        if stored_pane_stale && is_per_agent_window(&window, agent_id) {
+            list_same_role_panes(transport, &session_name, &window)
+        } else {
+            Vec::new()
+        };
+    let stopped = stored_pane_live
+        || !same_role_panes.is_empty()
+        || (pane_id.is_none() && window_exists(transport, &session_name, &window));
     if stopped {
         // golden operations.py:84-86: a non-zero kill-window raises
         // RuntimeError(f"failed to stop agent {agent_id}: {proc.stderr.strip()}").
-        let kill_result = if let Some(pane) = pane_id.as_ref() {
-            transport.kill_pane(pane)
-        } else {
-            let target = Target::SessionWindow {
-                session: session_name.clone(),
-                window: WindowName::new(&window),
+        //
+        // 0.4.10+ kill resolution order (plan §2):
+        //   1. stored pane_id is live → kill it by pane_id.
+        //   2. stored pane_id is stale BUT same-role panes survive →
+        //      kill each by pane_id (duplicate window names make
+        //      kill-window -t session:window ambiguous).
+        //   3. no pane_id at all but window exists → kill_window as
+        //      before (legacy compat for state without pane_id field).
+        let kill_result: Result<(), crate::transport::TransportError> =
+            if let Some(pane) = pane_id.as_ref().filter(|_| stored_pane_live) {
+                transport.kill_pane(pane)
+            } else if !same_role_panes.is_empty() {
+                let mut last_err: Option<crate::transport::TransportError> = None;
+                for residual in &same_role_panes {
+                    if let Err(e) = transport.kill_pane(&residual.pane_id) {
+                        last_err = Some(e);
+                    }
+                }
+                last_err.map(Err).unwrap_or(Ok(()))
+            } else {
+                let target = Target::SessionWindow {
+                    session: session_name.clone(),
+                    window: WindowName::new(&window),
+                };
+                transport.kill_window(&target)
             };
-            transport.kill_window(&target)
-        };
         if let Err(e) = kill_result {
             let stderr = match &e {
-                crate::transport::TransportError::Subprocess { stderr, .. } => stderr.trim().to_string(),
+                crate::transport::TransportError::Subprocess { stderr, .. } => {
+                    stderr.trim().to_string()
+                }
                 other => other.to_string(),
             };
             let _ = write_stop_window_failed_event(workspace, agent_id, &target_str, &stderr);
-            return Err(LifecycleError::Transport(format!("failed to stop agent {agent_id}: {stderr}")));
+            return Err(LifecycleError::Transport(format!(
+                "failed to stop agent {agent_id}: {stderr}"
+            )));
         }
         // 0.4.6 Stage 1: drain-and-prove. The pre-fix path trusted `kill_pane`'s
         // success return without waiting for the pane / pid to actually exit.
@@ -647,8 +773,12 @@ pub(super) fn stop_agent_at_paths(
     mark_agent_stopped(&mut state, agent_id, agent, &window)?;
     // golden operations.py:95: save_team_scoped_state (team projection) — NOT a raw save, so a
     // multi-team workspace keeps the other teams' persisted runtime state instead of being clobbered.
-    crate::state::projection::save_team_scoped_state(workspace, &state)
-        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    crate::state::projection::save_team_scoped_state_with_lifecycle_topology_authority(
+        workspace,
+        &state,
+        &[agent_id.as_str()],
+    )
+    .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     // golden operations.py:96-99: snapshot (side-effect), then state_file = write_team_state path.
     // snapshot.py:19-21 returns None silently when session_name is falsy — mirror that no-op here so
     // a workspace whose persisted state lacks session_name proceeds to write team_state and return ok
@@ -690,7 +820,9 @@ pub(super) fn resolve_team_scoped_state_or_refuse(
             .unwrap_or("");
         return Err(LifecycleError::TeamSelect(format!("{reason}: {detail}")));
     }
-    state.ok_or_else(|| LifecycleError::StatePersist("resolve_team_scoped_state returned no state".to_string()))
+    state.ok_or_else(|| {
+        LifecycleError::StatePersist("resolve_team_scoped_state returned no state".to_string())
+    })
 }
 
 fn mark_agent_started(
@@ -725,7 +857,10 @@ fn mark_agent_started(
     // codex, claude, copilot. Reset_agent --discard-session already does
     // this at common.rs:1144-1188; here we mirror it for start-agent /
     // restart-agent fresh paths so the fresh-tuple invariant is global.
-    if matches!(start_mode, StartMode::Fresh | StartMode::FreshAfterMissingRollout) {
+    if matches!(
+        start_mode,
+        StartMode::Fresh | StartMode::FreshAfterMissingRollout
+    ) {
         for field in [
             "session_id",
             "rollout_path",
@@ -782,17 +917,10 @@ fn mark_agent_started(
     // so future restart/start cycles read it directly from the agent row.
     if let Some(ref team_id) = spawn.owner_team_id {
         if !team_id.is_empty() {
-            agent.insert(
-                "owner_team_id".to_string(),
-                serde_json::json!(team_id),
-            );
+            agent.insert("owner_team_id".to_string(), serde_json::json!(team_id));
         }
     }
-    crate::lifecycle::launch::persist_command_plan_state(
-        agent,
-        &spawn.plan,
-        &spawn.profile_launch,
-    );
+    crate::lifecycle::launch::persist_command_plan_state(agent, &spawn.plan, &spawn.profile_launch);
     crate::lifecycle::launch::persist_effective_approval_policy(agent, safety);
     if let Some(placement) = spawn.layout_placement.as_ref() {
         agent.insert(
@@ -803,7 +931,10 @@ fn mark_agent_started(
             "layout_index".to_string(),
             serde_json::json!(placement.layout_index),
         );
-        agent.insert("pane_index".to_string(), serde_json::json!(placement.pane_index));
+        agent.insert(
+            "pane_index".to_string(),
+            serde_json::json!(placement.pane_index),
+        );
         agent.insert(
             "display".to_string(),
             serde_json::json!({
@@ -844,8 +975,13 @@ pub fn reset_agent(
         });
     }
     let paths = lifecycle_paths(workspace, team)?;
-    let transport =
-        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "reset-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
+    let transport = lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
     reset_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -871,6 +1007,12 @@ pub fn reset_agent_with_transport(
         });
     }
     let paths = lifecycle_paths(workspace, team)?;
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &paths.run_workspace,
+        operation: "reset-agent",
+        team,
+        agent_id: Some(agent_id),
+    })?;
     reset_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -906,7 +1048,158 @@ fn reset_agent_at_paths(
         .filter(|session| !session.is_empty())
         .map(SessionId::new);
     crate::lifecycle::launch::ensure_owner_allowed_for_state(&state_before_stop, Some(agent_id))?;
+    // Capture old pane_id / pane_pid / window BEFORE stop, so the hard gate
+    // below can prove the same prior instance is gone (or refuse start).
+    let old_pane_id_before = state_before_stop
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("pane_id"))
+        .and_then(|v| v.as_str())
+        .filter(|p| !p.is_empty())
+        .map(crate::transport::PaneId::new);
+    let old_pane_pid_before = state_pane_pid(&state_before_stop, agent_id);
+    // CR C-2: take ONE pre-stop snapshot of the team session's panes so
+    // the gate below can compute "what survived stop" by set difference,
+    // not "what panes exist at all" (which would refuse legitimate
+    // reset flows where stop killed the pane and the post-stop snapshot
+    // includes that same pane id in a transport mock that does not
+    // reflect kill removal).
+    let pre_stop_window = state_before_stop
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("window"))
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty())
+        .unwrap_or_else(|| agent_id.as_str())
+        .to_string();
+    let pre_stop_spec = load_team_spec(spec_workspace).ok();
+    let pre_stop_session = pre_stop_spec
+        .as_ref()
+        .map(|spec| state_session_name_from_spec(&state_before_stop, spec));
+    let pre_stop_pane_ids: std::collections::BTreeSet<String> =
+        if let Some(session) = pre_stop_session.as_ref() {
+            if is_per_agent_window(&pre_stop_window, agent_id) {
+                list_same_role_panes(transport, session, &pre_stop_window)
+                    .iter()
+                    .map(|p| p.pane_id.as_str().to_string())
+                    .collect()
+            } else {
+                std::collections::BTreeSet::new()
+            }
+        } else {
+            std::collections::BTreeSet::new()
+        };
     let stop = stop_agent_at_paths(workspace, spec_workspace, agent_id, team, transport)?;
+
+    // 0.4.10+ paused agent skip: a paused agent's start path returns
+    // StartAgentOutcome::Paused (no spawn). There is no duplicate-window
+    // hazard, so the gate is a no-op for paused agents.
+    let agent_is_paused = state_before_stop
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("paused"))
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+    // 0.4.10+ reset duplicate-window fix (plan §3): HARD GATE before start.
+    // After stop_agent_at_paths returns, prove the old instance is gone OR
+    // refuse to spawn. The pre-fix path unconditionally proceeded to
+    // discard/save/start even when stop returned stopped=false (stop's
+    // pane_id was stale), creating the observed duplicate-window pattern.
+    //
+    // Residue definition (correct: differential, not absolute):
+    //   A pane is RESIDUE iff it appears in BOTH the pre-stop snapshot
+    //   AND the post-stop snapshot. The pre-fix attempt used "any
+    //   matching pane exists post-stop" which broke legitimate flows
+    //   where the transport mock does not model kill_pane removal.
+    //
+    // Old pane id / pid checks:
+    //   The OLD stored pane_id / pane_pid must be gone (not just
+    //   reachable but actually killed). For real tmux this is the
+    //   structural truth source; for mocks the differential approach
+    //   above covers the post-stop visibility.
+    //
+    // CR C-5: gate is reset-specific; standalone stop-agent path keeps
+    // existing "already absent is ok" behavior.
+    //
+    // Gate scope refinement: when stop.stopped == true, the kill_pane
+    // call already succeeded (and drain_old_pane_and_pid polled for
+    // the pane to become unreachable). Treat that as the authoritative
+    // signal — running the gate again post-stop introduces a race
+    // window where tmux's has_pane lag can spuriously report Live.
+    // Only gate the dangerous case: stop reported stopped == false
+    // (state's stale pane_id pointed at nothing kill-able), which is
+    // exactly the duplicate-window bug pattern from the macmini
+    // evidence: `stop_agent.complete stopped=false` followed by an
+    // unconditional `start_agent.agent_start`.
+    if !agent_is_paused && !stop.stopped {
+        let spec_for_gate = load_team_spec(spec_workspace)?;
+        let gate_state = resolve_team_scoped_state_or_refuse(workspace, team)?;
+        let session_name_gate = state_session_name_from_spec(&gate_state, &spec_for_gate);
+        let gate_window = gate_state
+            .get("agents")
+            .and_then(|v| v.get(agent_id.as_str()))
+            .and_then(|v| v.get("window"))
+            .and_then(|v| v.as_str())
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| agent_id.as_str())
+            .to_string();
+        let old_pane_still_live = old_pane_id_before
+            .as_ref()
+            .map(|p| agent_pane_live_by_id(transport, p))
+            .unwrap_or(false);
+        // Take a SECOND snapshot post-stop and compute the differential.
+        // Only panes present in BOTH snapshots are residue (stop did not
+        // remove them).
+        let post_stop_panes: Vec<crate::transport::PaneInfo> =
+            if is_per_agent_window(&gate_window, agent_id) {
+                list_same_role_panes(transport, &session_name_gate, &gate_window)
+            } else {
+                Vec::new()
+            };
+        let remaining_panes: Vec<crate::transport::PaneInfo> = post_stop_panes
+            .into_iter()
+            .filter(|p| pre_stop_pane_ids.contains(p.pane_id.as_str()))
+            .collect();
+        // Pid-alone aliveness is secondary evidence and noisy under fixtures
+        // (synthetic pids may by chance be live on the test machine). Block
+        // ONLY on tmux-visible residue: old pane still live OR same-role
+        // panes survived stop. The pid is still recorded in the event for
+        // diagnostics.
+        let old_pid_still_live = old_pane_pid_before
+            .filter(|_| old_pane_still_live)
+            .map(|pid| pid_is_alive(pid))
+            .unwrap_or(false);
+        if old_pane_still_live || !remaining_panes.is_empty() {
+            let remaining_pane_ids: Vec<String> = remaining_panes
+                .iter()
+                .map(|p| p.pane_id.as_str().to_string())
+                .collect();
+            let old_pane_str = old_pane_id_before
+                .as_ref()
+                .map(|p| p.as_str().to_string())
+                .unwrap_or_default();
+            let old_pid_val = old_pane_pid_before.unwrap_or(0);
+            let _ = write_reset_stop_not_proven_event(
+                workspace,
+                agent_id,
+                &old_pane_str,
+                old_pid_val,
+                &remaining_pane_ids,
+            );
+            // CR C-1 N38 three-line error: error / action / log_hint.
+            let _ = stop; // silence unused on the refusal path
+            return Err(LifecycleError::RequirementUnmet(format!(
+                "reset refused: old agent instance still live for {agent_id}\n\
+                 action: stop the worker manually with `team-agent stop-agent {agent_id} --team <team>` then retry reset, or kill the residual tmux panes [{ids}]\n\
+                 log_hint: see reset_agent.stop_not_proven event (old_pane_id={old}, old_pane_pid={pid}, remaining_panes=[{ids}])",
+                agent_id = agent_id.as_str(),
+                ids = remaining_pane_ids.join(", "),
+                old = old_pane_str,
+                pid = old_pid_val,
+            )));
+        }
+    }
+
     let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
     let spec = load_team_spec(spec_workspace)?;
     discard_agent_session_fields(&mut state, agent_id)?;
@@ -927,12 +1220,12 @@ fn reset_agent_at_paths(
     sync_restart_team_projections(&mut state, &team_key);
     // golden operations.py (reset): save_team_scoped_state on the team projection — same multi-team
     // preservation as stop, not a raw save_runtime_state.
-    crate::state::projection::save_team_scoped_state_with_tombstoned_agents(
+    crate::state::projection::save_team_scoped_state_with_tombstone_lifecycle_topology_authority(
         workspace,
         &state,
         &[agent_id.as_str()],
     )
-        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     // golden operations.py:125: write_team_state after the discard-save (the intermediate stopped snapshot).
     write_team_state(spec_workspace, &spec, &state)?;
     write_reset_tombstone_event(
@@ -1018,12 +1311,11 @@ fn write_start_agent_start_event(
     // Contract C / F6.4: event log must record the same context-aware argv that the
     // actual spawn used — so the role/tools/MCP context appears in `start_agent.agent_start`.
     let safety = crate::lifecycle::launch::effective_runtime_config_for_worker_spawn()?;
-    let command_agent =
-        crate::lifecycle::worker_command_context::WorkerCommandAgent::from_json(
-            agent,
-            Some(agent_id.as_str()),
-            provider,
-        );
+    let command_agent = crate::lifecycle::worker_command_context::WorkerCommandAgent::from_json(
+        agent,
+        Some(agent_id.as_str()),
+        provider,
+    );
     let system_prompt =
         crate::lifecycle::worker_command_context::compile_worker_system_prompt(&command_agent)?;
     let tools = crate::lifecycle::worker_command_context::resolved_tool_strings_for_command(
@@ -1035,17 +1327,18 @@ fn write_start_agent_start_event(
     let mcp_config = adapter
         .mcp_config(auth_mode)
         .map_err(|e| LifecycleError::Provider(e.to_string()))?;
-    let team_id = agent
-        .get("owner_team_id")
-        .and_then(|v| v.as_str());
+    let team_id = agent.get("owner_team_id").and_then(|v| v.as_str());
     let mcp_config = crate::lifecycle::launch::resolve_mcp_config(
         mcp_config,
         workspace,
         agent_id.as_str(),
         team_id.unwrap_or(""),
     );
-    let mcp_config_path =
-        crate::lifecycle::launch::write_worker_mcp_config(workspace, agent_id.as_str(), &mcp_config)?;
+    let mcp_config_path = crate::lifecycle::launch::write_worker_mcp_config(
+        workspace,
+        agent_id.as_str(),
+        &mcp_config,
+    )?;
     let profile_launch =
         crate::lifecycle::profile_launch::prepare_provider_profile_launch_from_json(
             workspace,
@@ -1053,16 +1346,15 @@ fn write_start_agent_start_event(
             agent,
             Some(&mcp_config),
         )?;
-    let command_model = profile_launch
-        .command_overrides
-        .model
-        .as_deref()
-        .or(model);
+    let command_model = profile_launch.command_overrides.model.as_deref().or(model);
     // 0.4.x provider effort MVP: start_agent path preserves effort from the
     // persisted agent JSON.
-    let start_agent_effort = crate::lifecycle::launch::provider_effort_for_spawn_json(&agent, provider);
+    let start_agent_effort =
+        crate::lifecycle::launch::provider_effort_for_spawn_json(&agent, provider);
     if let Some(event_value) = crate::lifecycle::launch::provider_effort_event_if_dropped_json(
-        &agent, provider, agent_id.as_str(),
+        &agent,
+        provider,
+        agent_id.as_str(),
     ) {
         let _ = crate::event_log::EventLog::new(workspace)
             .write("provider.effort_unsupported", event_value);
@@ -1154,10 +1446,7 @@ pub(super) fn write_stop_drain_event(
         }
     }
     crate::event_log::EventLog::new(workspace)
-        .write(
-            "stop_agent.drain",
-            serde_json::Value::Object(payload),
-        )
+        .write("stop_agent.drain", serde_json::Value::Object(payload))
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     Ok(())
 }
@@ -1198,6 +1487,32 @@ fn write_reset_tombstone_event(
     Ok(())
 }
 
+/// 0.4.10+ reset duplicate-window fix (plan §3): emit a structured event
+/// when the reset hard gate refuses to start because the old instance is
+/// proven still live (old pane id reachable, old pane pid alive, or
+/// same-role panes remain in the team session).
+fn write_reset_stop_not_proven_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    old_pane_id: &str,
+    old_pane_pid: u32,
+    remaining_panes: &[String],
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "reset_agent.stop_not_proven",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "old_pane_id": old_pane_id,
+                "old_pane_pid": old_pane_pid,
+                "remaining_panes": remaining_panes,
+                "action": "stop the worker manually then retry reset, or kill the residual tmux panes",
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
 fn write_reset_complete_event(
     workspace: &Path,
     agent_id: &AgentId,