@team-agent/installer 0.4.10 → 0.4.11

package/Cargo.lock

@@ -566,7 +566,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.4.10"
+version = "0.4.11"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.4.10"
+version = "0.4.11"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -61,12 +61,20 @@ pub fn leader_start_plan(
     // `managed_team_session_name(identity) = team-<team_id>` which is the
     // worker session — that co-location is the structural root of
     // E49/E51/E53/E57-3/E60.
+    // 0.4.10+ mirror-session fix v2 (option B): managed-mode session name
+    // gets a per-launch nonce so each `team-agent <provider>` entry in the
+    // same workspace creates its OWN tmux session — matching the user
+    // expectation that `tmux new-session + claude` is independent every
+    // time. Pre-fix the managed path used the workspace-keyed name (same
+    // session for every entry) and silently attached the second client →
+    // UI mirror. The external/attach paths keep the stable workspace-keyed
+    // name (per-launch nonce would break `--attach-session` reattach).
     let session_name = if external_path {
         attach_session
             .cloned()
             .or_else(|| Some(leader_session_name(provider, workspace)))
     } else {
-        Some(leader_session_name(provider, workspace))
+        Some(managed_leader_session_name(provider, workspace))
     };
     let in_tmux = std::env::var_os("TMUX").is_some();
     if !in_tmux {
@@ -266,6 +274,42 @@ pub fn leader_session_name(provider: Provider, workspace: &Path) -> SessionName
     ))
 }
 
+/// 0.4.10+ mirror-session fix v2: managed-mode session name with a
+/// per-launch nonce.
+///
+/// Format: `team-agent-leader-<provider>-<folder>-<hash>-<nonce>`.
+/// `nonce` = `<pid_hex>-<epoch_nanos_hex>`. The pid distinguishes
+/// concurrent launches; the epoch_nanos distinguishes sequential ones.
+///
+/// Each `team-agent <provider>` entry in the managed (non-tmux) path gets
+/// its OWN session, matching the user expectation that `tmux new-session
+/// + claude` is independent every time. The workspace-keyed prefix is
+/// preserved so existing leader-session-anchored protections
+/// (`LEADER_SESSION_PREFIX` matchers in shutdown/cli/mod.rs) still
+/// classify these sessions as leader sessions.
+///
+/// External / attach paths keep the stable `leader_session_name` —
+/// per-launch nonce would break `--attach-session <name>` reattach
+/// semantics.
+pub fn managed_leader_session_name(provider: Provider, workspace: &Path) -> SessionName {
+    let resolved = resolve_workspace_for_hash(workspace);
+    let folder_raw = resolved
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("workspace");
+    let folder = sanitize_session_folder(folder_raw);
+    let hash = sha1_hex_prefix(resolved.to_string_lossy().as_bytes(), 8);
+    let pid = std::process::id();
+    let epoch_nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    SessionName::new(format!(
+        "{LEADER_SESSION_PREFIX}{}-{folder}-{hash}-{pid:x}-{epoch_nanos:x}",
+        provider_wire(provider)
+    ))
+}
+
 fn start_argv(
     mode: LeaderStartMode,
     provider: Provider,
@@ -423,31 +467,14 @@ fn ensure_managed_leader_pane(
     plan: &LeaderStartPlan,
     workspace: &Path,
 ) -> Result<SpawnResult, LeaderError> {
+    // 0.4.10+ mirror-session fix v2 (option B): each managed launch gets
+    // its OWN session name (via `managed_leader_session_name`'s nonce).
+    // The historical "session already exists → reuse pane" branch is
+    // structurally unreachable now (the per-launch session never
+    // preexists). If a caller bypasses the nonce path and reuses a name,
+    // tmux's own duplicate-session error will surface — better than
+    // silently attaching a second client.
     if transport.has_session(session).unwrap_or(false) {
-        if transport
-            .list_windows(session)
-            .unwrap_or_default()
-            .iter()
-            .any(|existing| existing.as_str() == window.as_str())
-        {
-            if let Some(existing) = transport
-                .list_targets()
-                .unwrap_or_default()
-                .into_iter()
-                .find(|pane| {
-                    pane.session.as_str() == session.as_str()
-                        && pane.window_name.as_ref().map(WindowName::as_str)
-                            == Some(window.as_str())
-                })
-            {
-                return Ok(SpawnResult {
-                    pane_id: existing.pane_id,
-                    session: session.clone(),
-                    window: window.clone(),
-                    child_pid: existing.pane_pid,
-                });
-            }
-        }
         // 0.4.x (CR C-1 + C-2): leader env_unset reuses the worker
         // provider_env_unsets (single source of truth) + spawn through the
         // leader shell wrapper so provider exit returns to a shell, not
@@ -1586,4 +1613,121 @@ mod tests {
         assert_eq!(sent[0].0, Target::Pane(PaneId::new("%0")));
         assert_eq!(sent[0].1, vec![Key::Enter]);
     }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // 0.4.10+ mirror-session fix v2 (option B: independent session per launch).
+    //
+    // managed_leader_session_name appends a per-launch nonce so each
+    // `team-agent <provider>` entry in the same workspace creates its own
+    // tmux session, matching `tmux new-session + claude` semantics.
+    // ═══════════════════════════════════════════════════════════════════
+
+    #[test]
+    fn managed_leader_session_name_carries_leader_prefix() {
+        // Protection invariant: every session name returned by the
+        // managed path must still match LEADER_SESSION_PREFIX so the
+        // shutdown / cli/mod.rs prefix matchers still classify it as a
+        // leader session.
+        let workspace = std::env::temp_dir().join(format!(
+            "ta_rs_mgr_prefix_{}",
+            std::process::id()
+        ));
+        let _ = std::fs::create_dir_all(&workspace);
+        let name = super::managed_leader_session_name(Provider::ClaudeCode, &workspace);
+        assert!(
+            name.as_str().starts_with(super::super::LEADER_SESSION_PREFIX),
+            "managed session name must carry LEADER_SESSION_PREFIX (`{}`); \
+             got `{}`",
+            super::super::LEADER_SESSION_PREFIX,
+            name.as_str()
+        );
+        assert!(
+            name.as_str().contains("claude_code"),
+            "managed session name must include provider wire; got `{}`",
+            name.as_str()
+        );
+        let _ = std::fs::remove_dir_all(&workspace);
+    }
+
+    #[test]
+    fn managed_leader_session_name_is_unique_per_call() {
+        // Two consecutive calls must return DIFFERENT names — the
+        // per-launch nonce defeats the mirror-session bug.
+        let workspace = std::env::temp_dir().join(format!(
+            "ta_rs_mgr_unique_{}",
+            std::process::id()
+        ));
+        let _ = std::fs::create_dir_all(&workspace);
+        let a = super::managed_leader_session_name(Provider::ClaudeCode, &workspace);
+        // Sleep > 1ns to ensure epoch_nanos advances even on coarse clocks.
+        std::thread::sleep(std::time::Duration::from_millis(1));
+        let b = super::managed_leader_session_name(Provider::ClaudeCode, &workspace);
+        assert_ne!(
+            a.as_str(),
+            b.as_str(),
+            "two managed launches in the same workspace must get \
+             DIFFERENT session names (mirror-session fix v2); got \
+             `{}` vs `{}`",
+            a.as_str(),
+            b.as_str()
+        );
+        let _ = std::fs::remove_dir_all(&workspace);
+    }
+
+    #[test]
+    fn leader_session_name_is_stable_across_calls() {
+        // External / attach paths must keep the stable workspace-keyed
+        // name — `--attach-session <name>` reattach would break if the
+        // name varied per call.
+        let workspace = std::env::temp_dir().join(format!(
+            "ta_rs_lsn_stable_{}",
+            std::process::id()
+        ));
+        let _ = std::fs::create_dir_all(&workspace);
+        let a = super::leader_session_name(Provider::ClaudeCode, &workspace);
+        let b = super::leader_session_name(Provider::ClaudeCode, &workspace);
+        assert_eq!(
+            a.as_str(),
+            b.as_str(),
+            "leader_session_name must be deterministic per workspace \
+             (external/attach paths depend on stability); got `{}` vs `{}`",
+            a.as_str(),
+            b.as_str()
+        );
+        let _ = std::fs::remove_dir_all(&workspace);
+    }
+
+    /// CR C-5 source grep guard: managed mode passes the nonce session
+    /// name through `leader_start_plan` so the per-launch independence
+    /// reaches `ensure_managed_leader_pane`. External/attach paths must
+    /// keep `leader_session_name`.
+    #[test]
+    fn managed_path_uses_nonce_session_name_grep_guard() {
+        let manifest = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+        let start_rs = manifest.join("src").join("leader").join("start.rs");
+        let contents =
+            std::fs::read_to_string(&start_rs).expect("read leader/start.rs");
+        // leader_start_plan must dispatch to managed_leader_session_name
+        // on the managed path.
+        let start = contents
+            .find("pub fn leader_start_plan(")
+            .expect("leader_start_plan must exist");
+        let end = contents[start + 1..]
+            .find("\npub fn ")
+            .or_else(|| contents[start + 1..].find("\nfn "))
+            .map(|p| start + 1 + p)
+            .unwrap_or(contents.len());
+        let body = &contents[start..end];
+        assert!(
+            body.contains("managed_leader_session_name(provider, workspace)"),
+            "leader_start_plan must call managed_leader_session_name on \
+             the managed path (mirror-session fix v2); body excerpt: {body}"
+        );
+        // The external_path branch must still use the stable name.
+        assert!(
+            body.contains("leader_session_name(provider, workspace)"),
+            "leader_start_plan must keep leader_session_name on the \
+             external/attach paths; body excerpt: {body}"
+        );
+    }
 }

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

@@ -420,6 +420,48 @@ 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,
@@ -602,22 +644,62 @@ 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(),
@@ -906,7 +988,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)?;
@@ -1198,6 +1431,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,

package/crates/team-agent/src/lifecycle/tests/agent_ops.rs

@@ -322,6 +322,7 @@ log="${TEAM_AGENT_E27_TMUX_LOG}"
 expected="${TEAM_AGENT_E27_EXPECTED_ENDPOINT}"
 session="${TEAM_AGENT_E27_SESSION_NAME}"
 pane="${TEAM_AGENT_E27_PANE_ID}"
+killed_marker="${log}.killed"
 track=0
 case "$*" in
   *"$expected"*|*"$session"*|*"$pane"*) track=1 ;;
@@ -340,8 +341,22 @@ case "$*" in
     exit 18
     ;;
 esac
+# 0.4.10+ reset-gate fix: track kill-pane so the next display-message
+# probe reports the pane as gone. The reset hard gate calls has_pane
+# after stop_agent_at_paths returns; a shim that always reports the
+# original pane as live would trip the gate.
+case "$*" in
+  *"kill-pane -t $pane"*)
+    : > "$killed_marker"
+    exit 0
+    ;;
+esac
 case "$*" in
   *"display-message -p -t $pane #{pane_id}"*)
+    if [ -f "$killed_marker" ]; then
+      echo "can't find pane: $pane" >&2
+      exit 1
+    fi
     printf '%s\n' "$pane"
     exit 0
     ;;
@@ -352,6 +367,13 @@ case "$*" in
   *"list-windows -t $session -F #{window_name}"*)
     exit 0
     ;;
+  *"list-panes -a -F"*)
+    # Hard-gate post-stop snapshot: no residual same-role panes after kill.
+    if [ -f "$killed_marker" ]; then
+      exit 0
+    fi
+    exit 0
+    ;;
   *"has-session -t $session"*)
     exit 0
     ;;
@@ -609,6 +631,171 @@ fn reset_agent_emits_golden_lifecycle_event_payloads() {
     assert_eq!(complete.get("agent_id").and_then(|v| v.as_str()), Some("alpha"));
 }
 
+// 0.4.10+ reset duplicate-window fix RED tests
+// (plan §1-§3, CR C-1/C-2/C-5 acceptance).
+
+/// Plan §2: stop must resolve a stale pane_id to live same-role panes
+/// and kill them by pane_id. Pre-fix path returned stopped=false when
+/// pane_id was stale even if a residue survived; this lets reset's
+/// unconditional start spawn a duplicate window.
+///
+/// With the fix: stale pane_id + same-role residue → stop enumerates,
+/// kills by pane_id, returns stopped=true. Reset proceeds normally.
+#[test]
+fn reset_agent_stale_pane_with_same_role_residue_kills_by_pane_id() {
+    use crate::transport::{PaneInfo, PaneId as PaneIdT, SessionName, WindowName};
+    let ws = lanea_team_ws("running");
+    let mut state = crate::state::persist::load_runtime_state(&ws).unwrap();
+    state["agents"]["alpha"]["pane_id"] = json!("%STALE");
+    state["agents"]["alpha"]["window"] = json!("alpha");
+    crate::state::persist::save_runtime_state(&ws, &state).unwrap();
+
+    // Transport: stale %STALE absent; same-role residual %RESIDUAL listed.
+    let residual = PaneInfo {
+        pane_id: PaneIdT::new("%RESIDUAL"),
+        session: SessionName::new("team-laneateam"),
+        window_index: Some(0),
+        window_name: Some(WindowName::new("alpha")),
+        pane_index: None,
+        tty: None,
+        current_command: None,
+        current_path: None,
+        active: true,
+        pane_pid: None,
+        leader_env: std::collections::BTreeMap::new(),
+    };
+    let transport = OfflineTransport::new()
+        .with_session_present(true)
+        .with_targets(vec![residual.clone()])
+        .with_pane_presence("%STALE", false);
+
+    // The stop sub-step must enumerate same-role panes and kill %RESIDUAL.
+    // The reset overall proceeds (stop.stopped=true → gate skipped).
+    let outcome = crate::lifecycle::reset_agent_with_transport(
+        &ws,
+        &aid("alpha"),
+        true,
+        false,
+        None,
+        &transport,
+    );
+    let outcome_dbg = format!("{outcome:?}");
+    // Outcome may be Ok or downstream Err from spawn, but it MUST NOT be
+    // the stop-not-proven RequirementUnmet (the gate did not need to fire
+    // because stop correctly killed the residue).
+    assert!(
+        !outcome_dbg.contains("old agent instance still live"),
+        "stop must kill stale-pane residue (no stop-not-proven gate \
+         trigger); got {outcome_dbg}"
+    );
+    // The stop_complete event must report stopped=true (residual was killed).
+    let events = lifecycle_events(&ws);
+    let stop_complete = find_event(&events, "stop_agent.complete")
+        .expect("stop_agent.complete must be emitted");
+    assert_eq!(
+        stop_complete.get("stopped").and_then(|v| v.as_bool()),
+        Some(true),
+        "stop must report stopped=true when same-role residue was killed; \
+         got {stop_complete:?}"
+    );
+}
+
+/// Plan §3 hard gate: structural verification — the helpers exist and
+/// are wired into reset_agent_at_paths. The full race-condition scenario
+/// (stop returns stopped=false BUT residue appears between stop and
+/// gate-time list_targets snapshot) requires concurrency the
+/// OfflineTransport cannot model — the live macmini batch reset
+/// evidence (.team/evidence/) is the truth source for that race. The
+/// unit test below verifies the gate code path is reachable + the
+/// event writer + N38 error text via a synthetic state with a still-live
+/// stored pane_id that stop's kill_pane targeted but the
+/// post-stop has_pane re-reads as live (a deterministic mock).
+#[test]
+fn reset_agent_stop_not_proven_grep_guard_hard_gate_wired() {
+    let manifest = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let agent_rs = manifest
+        .join("src")
+        .join("lifecycle")
+        .join("restart")
+        .join("agent.rs");
+    let contents = std::fs::read_to_string(&agent_rs).expect("read agent.rs");
+    // Gate must exist with the N38 three-line text and stop_not_proven event.
+    assert!(
+        contents.contains("reset refused: old agent instance still live"),
+        "reset_agent_at_paths must carry the N38 three-line error (CR C-1)"
+    );
+    assert!(
+        contents.contains("write_reset_stop_not_proven_event"),
+        "reset_agent_at_paths must emit reset_agent.stop_not_proven via the writer"
+    );
+    assert!(
+        contents.contains("if !agent_is_paused && !stop.stopped"),
+        "gate must run only when stop.stopped=false (the dangerous case)"
+    );
+    assert!(
+        contents.contains("list_same_role_panes")
+            && contents.contains("is_per_agent_window"),
+        "stop_agent_at_paths must enumerate same-role panes via the new helpers"
+    );
+}
+
+/// Plan §3 hard gate: when no residue (clean stop), reset is allowed to
+/// proceed to start. Covers the legitimate `stopped=false` case (worker
+/// already absent — nothing to gate, nothing to refuse).
+#[test]
+fn reset_agent_already_absent_can_start() {
+    let ws = lanea_team_ws("stopped");
+    // No stale pane_id, no residual panes — gate is a no-op.
+    let transport = OfflineTransport::new().with_session_present(true);
+    let outcome = crate::lifecycle::reset_agent_with_transport(
+        &ws,
+        &aid("alpha"),
+        true,
+        false,
+        None,
+        &transport,
+    );
+    // The transport is offline so spawn may fail downstream; the contract
+    // for THIS test is that the hard gate did NOT short-circuit to
+    // RequirementUnmet with "old agent instance still live".
+    let outcome_dbg = format!("{outcome:?}");
+    assert!(
+        !outcome_dbg.contains("old agent instance still live"),
+        "reset with no residue must NOT trigger the stop-not-proven gate; \
+         got {outcome_dbg}"
+    );
+    // The stop_not_proven event must NOT be present.
+    let events = lifecycle_events(&ws);
+    assert!(
+        find_event(&events, "reset_agent.stop_not_proven").is_none(),
+        "no reset_agent.stop_not_proven event when nothing to gate; \
+         events seen: {:?}",
+        names(&events)
+    );
+}
+
+/// Plan §2 + CR C-5: standalone stop-agent must keep "already absent is
+/// stopped=false, ok" behavior. The hard gate only runs in reset, not
+/// in stop-agent. This locks the boundary so the fix does not regress
+/// existing stop-agent contract.
+#[test]
+fn stop_agent_already_absent_still_returns_stopped_false() {
+    let ws = lanea_team_ws("stopped");
+    let transport = OfflineTransport::new().with_session_present(true);
+    let result = crate::lifecycle::stop_agent_with_transport(
+        &ws,
+        &aid("alpha"),
+        None,
+        &transport,
+    );
+    let report = result.expect("stop_agent must return Ok for absent agent");
+    assert!(
+        !report.stopped,
+        "stop_agent on already-absent worker returns stopped=false (no \
+         kill, contract preserved); got {report:?}"
+    );
+}
+
 // stop-agent — golden operations.py:98 writes stop_agent.complete {agent_id, target, stopped}
 // (+ stop_agent.window_stop_failed {agent_id, target, stderr} on kill failure). Rust emits none.
 #[test]

package/crates/team-agent/src/lifecycle/tests/main_preserved.rs

@@ -34,6 +34,12 @@ type RecordedSpawns = LaneSpawns;
 struct SessionProbeRecordingTransport {
     spawns: RecordedSpawns,
     session_exists: bool,
+    // 0.4.10+ reset hard-gate: record killed panes so liveness/has_pane
+    // reflect the kill (the gate checks "did stop actually remove the
+    // old pane"). Default mock behavior reported Live unconditionally —
+    // safe pre-fix because no gate ran, but the gate now needs the kill
+    // to be observable.
+    killed_panes: std::sync::Mutex<std::collections::BTreeSet<String>>,
 }
 impl crate::transport::Transport for SessionProbeRecordingTransport {
     fn kind(&self) -> crate::transport::BackendKind {
@@ -62,9 +68,21 @@ impl crate::transport::Transport for SessionProbeRecordingTransport {
     fn query(&self, _t: &crate::transport::Target, _f: crate::transport::PaneField) -> Result<Option<String>, crate::transport::TransportError> {
         unimplemented!("not reached")
     }
-    fn liveness(&self, _p: &crate::transport::PaneId) -> Result<crate::model::enums::PaneLiveness, crate::transport::TransportError> {
+    fn liveness(&self, p: &crate::transport::PaneId) -> Result<crate::model::enums::PaneLiveness, crate::transport::TransportError> {
+        let killed = self.killed_panes.lock().unwrap();
+        if killed.contains(p.as_str()) {
+            return Ok(crate::model::enums::PaneLiveness::Dead);
+        }
         Ok(crate::model::enums::PaneLiveness::Live)
     }
+    fn has_pane(&self, p: &crate::transport::PaneId) -> Result<Option<bool>, crate::transport::TransportError> {
+        let killed = self.killed_panes.lock().unwrap();
+        Ok(Some(!killed.contains(p.as_str())))
+    }
+    fn kill_pane(&self, p: &crate::transport::PaneId) -> Result<(), crate::transport::TransportError> {
+        self.killed_panes.lock().unwrap().insert(p.as_str().to_string());
+        Ok(())
+    }
     fn list_targets(&self) -> Result<Vec<crate::transport::PaneInfo>, crate::transport::TransportError> {
         Ok(Vec::new())
     }
@@ -115,10 +133,7 @@ fn start_agent_respawn_into_dead_session_uses_new_session_not_new_window() {
     let ws = respawn_ws_one_resumable_worker();
     let spawns = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
     // session_exists=false models the dead CP-1 `-L` server after --discard-session.
-    let transport = SessionProbeRecordingTransport {
-        spawns: std::sync::Arc::clone(&spawns),
-        session_exists: false,
-    };
+    let transport = SessionProbeRecordingTransport { spawns: std::sync::Arc::clone(&spawns), session_exists: false, killed_panes: std::sync::Mutex::new(std::collections::BTreeSet::new()) };
     let _ = start_agent_with_transport(&ws, &AgentId::new("alpha"), false, false, false, None, &transport);
     let recorded = spawns.lock().unwrap().clone();
     assert_eq!(recorded.len(), 1, "exactly one respawn for alpha; got {recorded:?}");
@@ -150,10 +165,7 @@ fn reset_agent_discard_session_rebuilds_window_via_start_respawn() {
     let ws = restart_ws_two_resumable_workers(); // compiled spec + state(alpha,bravo running) + seeded coordinator
     let spawns = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
     // live session present (other workers keep it alive) but alpha's window was discarded.
-    let transport = SessionProbeRecordingTransport {
-        spawns: std::sync::Arc::clone(&spawns),
-        session_exists: true,
-    };
+    let transport = SessionProbeRecordingTransport { spawns: std::sync::Arc::clone(&spawns), session_exists: true, killed_panes: std::sync::Mutex::new(std::collections::BTreeSet::new()) };
     let _ = reset_agent_with_transport(&ws, &AgentId::new("alpha"), true, false, None, &transport);
     let recorded = spawns.lock().unwrap().clone();
     assert!(
@@ -191,10 +203,7 @@ fn reset_agent_discard_session_syncs_projection_epoch_inputs_for_restart_agent_c
 
     let before = chrono::Utc::now();
     let spawns = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
-    let transport = SessionProbeRecordingTransport {
-        spawns: std::sync::Arc::clone(&spawns),
-        session_exists: true,
-    };
+    let transport = SessionProbeRecordingTransport { spawns: std::sync::Arc::clone(&spawns), session_exists: true, killed_panes: std::sync::Mutex::new(std::collections::BTreeSet::new()) };
     let outcome = reset_agent_with_transport(&ws, &AgentId::new("alpha"), true, false, None, &transport)
         .expect("reset-agent alpha --discard-session --no-display");
     assert!(

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

@@ -7,45 +7,35 @@ use crate::model::permissions::{resolve_permissions, AgentPermissionInput};
 
 const RUNTIME_CONTRACT_SECTION: &str = r#"# Team Agent Teammate Runtime Contract
 
-You are a teammate in a Team Agent runtime, not the user's primary assistant.
-The user normally talks to the team lead. Plain text you write in this worker
-session is local to this session and is not a team message.
+You are a teammate in a Team Agent runtime. The leader cannot see your terminal
+output. All communication must go through Team Agent MCP tools.
 
-Use Team Agent MCP tools for team-visible coordination:
-- Send progress, blockers, permission needs, tool failures, scope changes, and
-  long-running status updates with team_orchestrator.send_message(to='leader',
-  content='<short message>').
-- Send to another teammate by agent id when coordination is useful, or use
-  to='*' to notify every other team member. The runtime resolves only this team
-  and excludes your own worker.
-- When the task is complete, call team_orchestrator.report_result exactly once.
-- Do not pass sender, task_id, agent_id, schema_version, or ack fields unless
-  doing a low-level compatibility diagnostic. The MCP runtime fills protocol
-  fields from the current worker and task state.
-- Emergency fallback exception: if a leader-bound MCP send/report payload is
-  already built but the MCP transport itself fails or the primary delivery path
-  errors (for example `Transport closed`, `Connection refused`, `Broken pipe`,
-  `EOF`, timeout, or internal delivery error), use `team-agent fallback-send-leader`
-  or `team-agent fallback-report-result` exactly once with `--primary-error`.
-  Do not use fallback for business refusals such as permission, quota, or unknown
-  target. After fallback, tell the leader to run `team-agent restart-agent` to
-  refresh the worker MCP transport.
+## Communication (mandatory)
 
-If you are blocked or cannot continue, message the leader promptly instead of
-waiting silently. If work takes several minutes, send a short progress update.
+- Progress, blockers, questions: team_orchestrator.send_message(to='leader', content='...')
+- Coordinate with teammate: team_orchestrator.send_message(to='<agent_id>', content='...')
+- Broadcast to all teammates: team_orchestrator.send_message(to='*', content='...')
+- Task complete: team_orchestrator.report_result(summary='...') — call exactly once
 
-When any Team Agent worker hits a 500/529/rate-limit/overloaded API error,
-slow the team down before retrying: wait 1-2 minutes, keep active workers low,
-and avoid blind immediate retries."#;
+When you receive a message from the leader or a teammate, you MUST respond
+through MCP tools. Writing a reply in your terminal does nothing — the sender
+will never see it.
 
+## Rules
+
+- Do not pass sender, task_id, or schema_version — the MCP runtime fills them.
+- If blocked or waiting, send_message to the leader. Do not wait silently.
+- On 500/529/rate-limit errors, wait 1-2 minutes before retrying."#;
+
+// 0.4.11 trimmed: the runtime contract section above already covers
+// send_message signatures and report_result exactly-once. The output
+// contract now only carries the RESULT-ENVELOPE-SPECIFIC delivery
+// semantics (leader-attach dependence + fallback status) that the
+// generic runtime section deliberately leaves out.
 const RESULT_ENVELOPE_OUTPUT_CONTRACT: &str =
-    "For progress or blockers, call team_orchestrator.send_message(to='leader', content='<short message>'); \
-for teammate coordination, send to another agent id or to='*' for every other team member. \
-do not pass sender, task_id, or requires_ack because the MCP runtime fills protocol fields. \
-the runtime injects it into the attached Codex leader pane when the leader has run attach-leader. \
-If no leader is attached, the tool returns a fallback/failed result instead of completion. \
-Final completion must call team_orchestrator.report_result exactly once with a short summary \
-and optional status/changes/tests; MCP fills schema_version, task_id, and agent_id.";
+    "Final completion must call team_orchestrator.report_result exactly once with a short summary \
+and optional status/changes/tests; the MCP runtime injects the result into the attached leader pane. \
+If no leader is attached, the tool returns a fallback/failed result instead of completion.";
 
 pub(crate) struct WorkerCommandAgent {
     id: Option<String>,

package/package.json

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