@team-agent/installer 0.3.26 → 0.3.28

package/Cargo.lock

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

package/Cargo.toml

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

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

@@ -443,6 +443,20 @@ pub mod lifecycle_port {
         );
         let mut error = None;
         for session in &to_kill {
+            // 0.3.28 Step 6 (warn-only invariant): the kill list MUST NOT
+            // contain a leader session. `sessions_to_kill` already excludes
+            // leader-prefixed sessions, but the managed-leader cleanup path
+            // (this function) computes its own `to_kill` from `target`. Any
+            // leader-prefixed entry here is a topology violation introduced
+            // somewhere upstream. Log loudly and skip the kill.
+            if session.as_str().starts_with(crate::leader::LEADER_SESSION_PREFIX) {
+                eprintln!(
+                    "team_agent::layout shutdown_invariant_violation kind=KillListContainsLeaderSession \
+                     session=`{}` action=skipping_kill (post-Step-9 will hard-fail)",
+                    session.as_str()
+                );
+                continue;
+            }
             if let Err(err) = transport.kill_session(session) {
                 if !tmux_absent_error(&err.to_string()) {
                     error.get_or_insert_with(|| err.to_string());

package/crates/team-agent/src/layout/manager.rs

@@ -0,0 +1,241 @@
+//! 0.3.28 layout step 2 — leader placement.
+//!
+//! Public API for managed-mode leader placement. The runtime calls
+//! `leader_placement` to compute where the leader pane lives and
+//! `ensure_leader_pane` to spawn/reuse it idempotently.
+//!
+//! Python parity (recap): leader **always** uses its dedicated session
+//! `team-agent-leader-<provider>-<folder>-<sha1[:8]>`. The window inside
+//! that session is named after the provider wire (`codex` / `claude` /
+//! `copilot`), never the literal `leader`. The pre-0.3.28 Rust managed
+//! mode co-located leader into the worker session `team-<team>` with a
+//! window named `leader` — this is the root cause of E49 / E51 / E53 /
+//! E57-3 / E60.
+
+use std::path::Path;
+
+use crate::leader::start::leader_session_name;
+use crate::leader::types::{LeaderIdentity, LeaderStartMode};
+use crate::model::enums::Provider;
+use crate::transport::{SessionName, WindowName};
+
+/// 0.3.28: managed-mode leader runs in its own session, window named after
+/// the provider. Mirrors `team-agent-leader-<provider>-<folder>-<sha1[:8]>`
+/// from Python.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LeaderPlacement {
+    /// Leader executes in the current pane (caller has `$TMUX` set).
+    /// No new session/window is created.
+    ExecCurrentPane,
+    /// Leader runs in its dedicated session.
+    DedicatedSession {
+        session: SessionName,
+        window: WindowName,
+    },
+}
+
+/// Compute the placement for a leader given its identity, the desired
+/// `LeaderStartMode`, and the environment (used to detect `$TMUX`).
+///
+/// Returns `ExecCurrentPane` iff `mode == ExecProvider`; otherwise
+/// `DedicatedSession{ leader_session_name(provider, workspace),
+/// WindowName(provider_wire(provider)) }`.
+pub fn leader_placement(
+    mode: LeaderStartMode,
+    provider: Provider,
+    workspace: &Path,
+) -> LeaderPlacement {
+    match mode {
+        LeaderStartMode::ExecProvider => LeaderPlacement::ExecCurrentPane,
+        // Managed + External + AttachExisting + NewTmuxSession all converge
+        // on the SAME `leader_session_name(provider, workspace)` per Python
+        // parity. The pre-0.3.28 managed branch used `team-<team_id>` (the
+        // worker session) — that divergence is what this step deletes.
+        _ => LeaderPlacement::DedicatedSession {
+            session: leader_session_name(provider, workspace),
+            window: WindowName::new(super::worker_window_helpers::provider_window_name(provider)),
+        },
+    }
+}
+
+/// The leader session name for a given provider + workspace. `LeaderIdentity`
+/// in this codebase does not carry the provider field; the caller supplies it
+/// explicitly (matches how `leader_session_name` itself is shaped).
+pub fn leader_session_for_provider(provider: Provider, workspace: &Path) -> SessionName {
+    leader_session_name(provider, workspace)
+}
+
+#[allow(dead_code)]
+fn _unused_identity_marker(_id: &LeaderIdentity) {}
+
+// ─── Worker placement (Step 4) ──────────────────────────────────────────
+
+use crate::layout::placement::{WorkerSpawnAction, WorkerSpawnTarget};
+use crate::model::yaml::Value as YamlValue;
+use crate::transport::Transport;
+
+/// Compute the spawn target for a worker. Python parity: one window per
+/// agent in the worker session, named after `agent_id`. First worker
+/// (= session does not yet exist) → NewSession; otherwise NewWindow.
+///
+/// `force` flag: when the window already exists, controls whether to
+/// emit `ForceReplace` (caller will `kill-window` then recreate) or
+/// `Noop` (caller does nothing).
+pub fn next_worker_window(
+    spec: &YamlValue,
+    agent_id: &str,
+    transport: &dyn Transport,
+    force: bool,
+) -> WorkerSpawnTarget {
+    let session = super::sessions::worker_session_name(spec);
+    let window = WindowName::new(agent_id);
+    let session_exists = transport.has_session(&session).unwrap_or(false);
+    if !session_exists {
+        return WorkerSpawnTarget::new(session, window, WorkerSpawnAction::NewSession);
+    }
+    let window_exists = transport
+        .list_windows(&session)
+        .unwrap_or_default()
+        .iter()
+        .any(|w| w.as_str() == window.as_str());
+    let action = if window_exists {
+        if force { WorkerSpawnAction::ForceReplace } else { WorkerSpawnAction::Noop }
+    } else {
+        WorkerSpawnAction::NewWindow
+    };
+    WorkerSpawnTarget::new(session, window, action)
+}
+
+#[cfg(test)]
+mod worker_placement_tests {
+    use super::*;
+
+    fn spec_for(team: &str) -> YamlValue {
+        YamlValue::Map(vec![(
+            "team".to_string(),
+            YamlValue::Map(vec![("name".to_string(), YamlValue::Str(team.to_string()))]),
+        )])
+    }
+
+    /// Pure-logic helper: same decision tree as `next_worker_window` but
+    /// without going through the `Transport` trait. Lets unit tests pin the
+    /// invariants without mocking the whole transport surface (which would
+    /// require ~20 unrelated method stubs).
+    fn next_worker_window_pure(
+        spec: &YamlValue,
+        agent_id: &str,
+        session_exists: bool,
+        window_exists: bool,
+        force: bool,
+    ) -> WorkerSpawnTarget {
+        let session = super::super::sessions::worker_session_name(spec);
+        let window = WindowName::new(agent_id);
+        if !session_exists {
+            return WorkerSpawnTarget::new(session, window, WorkerSpawnAction::NewSession);
+        }
+        let action = if window_exists {
+            if force { WorkerSpawnAction::ForceReplace } else { WorkerSpawnAction::Noop }
+        } else {
+            WorkerSpawnAction::NewWindow
+        };
+        WorkerSpawnTarget::new(session, window, action)
+    }
+
+    #[test]
+    fn first_worker_on_absent_session_returns_new_session() {
+        let t = next_worker_window_pure(&spec_for("alpha"), "developer", false, false, false);
+        assert_eq!(t.action, WorkerSpawnAction::NewSession);
+        assert_eq!(t.window.as_str(), "developer");
+        assert_eq!(t.session.as_str(), "team-alpha");
+    }
+
+    #[test]
+    fn second_worker_on_present_session_returns_new_window() {
+        let t = next_worker_window_pure(&spec_for("alpha"), "tester", true, false, false);
+        assert_eq!(t.action, WorkerSpawnAction::NewWindow);
+        assert_eq!(t.window.as_str(), "tester");
+    }
+
+    #[test]
+    fn existing_window_without_force_returns_noop() {
+        let t = next_worker_window_pure(&spec_for("alpha"), "developer", true, true, false);
+        assert_eq!(t.action, WorkerSpawnAction::Noop);
+    }
+
+    #[test]
+    fn existing_window_with_force_returns_force_replace() {
+        let t = next_worker_window_pure(&spec_for("alpha"), "developer", true, true, true);
+        assert_eq!(t.action, WorkerSpawnAction::ForceReplace);
+    }
+
+    #[test]
+    fn target_window_name_always_equals_agent_id_no_team_wN() {
+        // The pre-0.3.28 adaptive layout used team-w1/team-w2 windows with 3
+        // workers tiled per window. Step 4 design forbids that.
+        for agent_id in &["alice", "bob", "carol", "dave"] {
+            let t = next_worker_window_pure(&spec_for("alpha"), agent_id, false, false, false);
+            assert_eq!(t.window.as_str(), *agent_id);
+            assert!(
+                !t.window.as_str().starts_with("team-w"),
+                "no team-wN window allowed; got `{}`",
+                t.window.as_str()
+            );
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::layout::sessions::is_leader_session;
+
+    #[test]
+    fn exec_provider_mode_returns_exec_current_pane() {
+        let placement =
+            leader_placement(LeaderStartMode::ExecProvider, Provider::Claude, Path::new("/tmp/x"));
+        assert_eq!(placement, LeaderPlacement::ExecCurrentPane);
+    }
+
+    #[test]
+    fn managed_mode_returns_dedicated_leader_session() {
+        let placement = leader_placement(
+            LeaderStartMode::ManagedTmuxClient,
+            Provider::Claude,
+            Path::new("/tmp/x"),
+        );
+        match placement {
+            LeaderPlacement::DedicatedSession { session, window } => {
+                assert!(
+                    is_leader_session(&session),
+                    "managed mode must use the dedicated leader session prefix; got `{}`",
+                    session.as_str()
+                );
+                assert_eq!(
+                    window.as_str(),
+                    "claude",
+                    "leader window must be named after provider wire, not `leader`; got `{}`",
+                    window.as_str()
+                );
+            }
+            other => panic!("expected DedicatedSession, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn new_tmux_session_mode_returns_same_leader_session_as_managed() {
+        let managed = leader_placement(
+            LeaderStartMode::ManagedTmuxClient,
+            Provider::Codex,
+            Path::new("/tmp/x"),
+        );
+        let new_session = leader_placement(
+            LeaderStartMode::NewTmuxSession,
+            Provider::Codex,
+            Path::new("/tmp/x"),
+        );
+        assert_eq!(
+            managed, new_session,
+            "managed and new-tmux-session both target the dedicated leader session"
+        );
+    }
+}

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

@@ -0,0 +1,29 @@
+//! 0.3.28 — Unified adaptive layout manager.
+//!
+//! Single source of truth for tmux topology decisions in the runtime:
+//!   * leader session vs worker session (DISJOINT by naming)
+//!   * worker placement (1 window per agent, named `agent_id`)
+//!   * shutdown vs recovery semantics
+//!   * display-overlay 3-pane tiling (separate from worker execution layer)
+//!
+//! Mirrors the Python 0.2.11 truth source. Each invariant is documented in
+//! `assert_topology_invariants` so any regression surfaces as a `warn!` log
+//! (during the incremental migration) and eventually as a hard error.
+//!
+//! Module tree per `.team/artifacts/adaptive-layout-full-architecture-locate.md`:
+//!   * `sessions` — name constructors + is_leader_session / is_worker_session +
+//!                  assert_topology_invariants (Step 1, this file)
+//!   * `manager` — public API for leader_placement / next_worker_window /
+//!                 ensure_leader_pane / recover_leader_pane (Steps 2/4/7)
+//!   * `placement` — typed LeaderPlacement / WorkerSpawnTarget enums (Step 2/4)
+//!   * `overlay` — 3-pane display overlay (only place split-window appears)
+//!                 (Step 8)
+//!   * `worker_env` — worker_spawn_env whitelist + worker_spawn_cwd (Step 3)
+
+pub mod sessions;
+pub mod manager;
+pub mod worker_window_helpers;
+pub mod worker_env;
+pub mod placement;
+pub mod recovery;
+pub mod overlay;

package/crates/team-agent/src/layout/overlay.rs

@@ -0,0 +1,122 @@
+//! 0.3.28 layout step 8 — display overlay (3-pane tiling).
+//!
+//! Python truth source: 3-pane tiling exists ONLY in the display overlay
+//! (`display/tiling.py:7` `DISPLAY_PANES_PER_WINDOW = 3`), which is
+//! appended to the LEADER session (never the worker session). Math is
+//! `i // 3` (tab index), `i % 3` (slot index), deterministic by job
+//! index. Tab naming: `team-agent:<session_tag>:overview[-N]`.
+//!
+//! Step 8 ships the overlay computation helpers + the
+//! `assert_overlay_call_site` warning that fires when `spawn_split` is
+//! reached from a non-overlay path (Step 9 promotes to hard error).
+
+use crate::transport::{SessionName, WindowName};
+
+/// 3 panes per overlay window — Python parity.
+pub const OVERLAY_PANES_PER_WINDOW: usize = 3;
+
+/// Overlay window name for a 0-based group index. Index 0 → `overview`;
+/// N ≥ 1 → `overview-{N+1}`. Names are scoped by `session_tag` so multiple
+/// teams can coexist on one leader session.
+pub fn overlay_window_name(session_tag: &str, group_index: usize) -> WindowName {
+    if group_index == 0 {
+        WindowName::new(format!("team-agent:{session_tag}:overview"))
+    } else {
+        WindowName::new(format!("team-agent:{session_tag}:overview-{}", group_index + 1))
+    }
+}
+
+/// Plan output: where each agent_id job lands in the overlay.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OverlayPlacement {
+    pub agent_id: String,
+    pub group_index: usize,
+    pub slot_index: usize,
+    pub window: WindowName,
+}
+
+/// Compute the overlay placements for a list of agent_ids. Deterministic by
+/// input order: agent `i` → window `i / 3`, slot `i % 3`.
+pub fn plan_overlay_placements(session_tag: &str, agents: &[&str]) -> Vec<OverlayPlacement> {
+    agents
+        .iter()
+        .enumerate()
+        .map(|(i, agent_id)| OverlayPlacement {
+            agent_id: agent_id.to_string(),
+            group_index: i / OVERLAY_PANES_PER_WINDOW,
+            slot_index: i % OVERLAY_PANES_PER_WINDOW,
+            window: overlay_window_name(session_tag, i / OVERLAY_PANES_PER_WINDOW),
+        })
+        .collect()
+}
+
+/// True when a window name belongs to a display overlay (matches
+/// `team-agent:<...>:overview[-N]`).
+pub fn is_overlay_window(name: &WindowName) -> bool {
+    let n = name.as_str();
+    if !n.starts_with("team-agent:") {
+        return false;
+    }
+    n.contains(":overview")
+}
+
+/// 0.3.28 Step 8 invariant: `spawn_split` may ONLY be called from the
+/// overlay module. This helper emits a warn-level event when called from
+/// anywhere else (Step 9 promotes to a hard error / panic gate). The
+/// `target_session` and `target_window` are passed so the operator sees
+/// which spawn_split call drifted.
+pub fn assert_overlay_call_site(target_session: &SessionName, target_window: &WindowName) {
+    if !is_overlay_window(target_window) {
+        eprintln!(
+            "team_agent::layout overlay_invariant_violation kind=SplitOutsideOverlay \
+             session=`{}` window=`{}` action=permitted_with_warning \
+             (post-Step-9 will hard-fail; splits must only occur in display overlay)",
+            target_session.as_str(),
+            target_window.as_str()
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn overlay_window_name_first_group_is_overview() {
+        assert_eq!(
+            overlay_window_name("alpha", 0).as_str(),
+            "team-agent:alpha:overview"
+        );
+    }
+
+    #[test]
+    fn overlay_window_name_second_group_appends_two() {
+        assert_eq!(
+            overlay_window_name("alpha", 1).as_str(),
+            "team-agent:alpha:overview-2"
+        );
+    }
+
+    #[test]
+    fn plan_overlay_placements_three_per_window_deterministic() {
+        let agents = ["a", "b", "c", "d", "e", "f", "g"];
+        let plan = plan_overlay_placements("alpha", &agents);
+        assert_eq!(plan[0].group_index, 0);
+        assert_eq!(plan[0].slot_index, 0);
+        assert_eq!(plan[2].group_index, 0);
+        assert_eq!(plan[2].slot_index, 2);
+        assert_eq!(plan[3].group_index, 1);
+        assert_eq!(plan[3].slot_index, 0);
+        assert_eq!(plan[6].group_index, 2);
+        assert_eq!(plan[6].slot_index, 0);
+    }
+
+    #[test]
+    fn is_overlay_window_matches_overview_namespace_only() {
+        assert!(is_overlay_window(&WindowName::new("team-agent:alpha:overview")));
+        assert!(is_overlay_window(&WindowName::new("team-agent:alpha:overview-2")));
+        assert!(!is_overlay_window(&WindowName::new("developer")));
+        assert!(!is_overlay_window(&WindowName::new("team-w1")));
+        assert!(!is_overlay_window(&WindowName::new("team-alpha:leader")));
+    }
+}

package/crates/team-agent/src/layout/placement.rs

@@ -0,0 +1,47 @@
+//! 0.3.28 layout step 4 — typed worker placement target.
+//!
+//! Python parity (`runtime.py:1017-1020`): one window per agent in the
+//! worker session, named `agent_id`. First worker creates the session
+//! (`new-session`); subsequent workers each get a new window
+//! (`new-window`). No splits, no 3-pane tiling at the execution layer.
+//!
+//! This module provides the typed `WorkerSpawnTarget` enum returned by
+//! `next_worker_window` (in `layout::manager`). Step 4 lands the API +
+//! contract tests; Step 4b deletes `adaptive_layout_plan` and migrates
+//! all callsites.
+
+use crate::transport::{SessionName, WindowName};
+
+/// Action to take when spawning a worker into the layout.
+///
+/// `NewSession` is used for the first agent in a fresh team (the worker
+/// session does not yet exist). `NewWindow` is used for every subsequent
+/// agent. There is intentionally NO `SplitWindow` variant — splits exist
+/// only in the display overlay (`layout::overlay`), never in the worker
+/// execution layer.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WorkerSpawnAction {
+    /// `tmux new-session -d -s <session> -n <window> ...`
+    NewSession,
+    /// `tmux new-window -d -t <session> -n <window> ...`
+    NewWindow,
+    /// Window already exists; reuse (no spawn).
+    Noop,
+    /// Window already exists; caller asked to force replace —
+    /// `tmux kill-window -t <session>:<window>` then recreate.
+    ForceReplace,
+}
+
+/// A fully-resolved spawn target for a worker.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorkerSpawnTarget {
+    pub session: SessionName,
+    pub window: WindowName,
+    pub action: WorkerSpawnAction,
+}
+
+impl WorkerSpawnTarget {
+    pub fn new(session: SessionName, window: WindowName, action: WorkerSpawnAction) -> Self {
+        Self { session, window, action }
+    }
+}

package/crates/team-agent/src/layout/recovery.rs

@@ -0,0 +1,101 @@
+//! 0.3.28 layout step 7 — leader pane recovery.
+//!
+//! Python truth source (`leader/__init__.py:885-887` +
+//! `restart/orchestration.py:369-383`): leader recovery requires
+//! `TMUX_PANE` env. Without it, runtime emits `leader_receiver.rebind_required`
+//! and continues — NO proactive co-located leader spawn.
+//!
+//! Replaces the pre-0.3.28 `ensure_managed_leader_pane` path that masked
+//! missing leader windows by silently spawning a new one (often into the
+//! worker session — E57-3 root). After Step 2 the leader lives in its
+//! own session, so the proper recovery path is:
+//!   1. If `TMUX_PANE` is set → autobind to that pane.
+//!   2. Else → emit `leader_receiver.rebind_required` and return
+//!      `NeedsUserAttach`; the user runs `team-agent attach-leader` or
+//!      `team-agent claim-leader` from their leader pane.
+
+use crate::transport::PaneId;
+
+/// Outcome of a leader recovery attempt.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RecoveryOutcome {
+    /// `TMUX_PANE` env is set; caller should `autobind_leader` against this
+    /// pane id.
+    AutobindToPane(PaneId),
+    /// No `TMUX_PANE` env; runtime emits `leader_receiver.rebind_required`
+    /// and continues without a leader pane. The user must run
+    /// `team-agent attach-leader` from their leader pane to recover.
+    NeedsUserAttach,
+}
+
+/// Compute the recovery outcome from the current environment.
+///
+/// Reads `TMUX_PANE` from the supplied environment iterator (use
+/// `std::env::vars()` in production; tests inject a synthetic map).
+pub fn recover_leader_pane<I>(env: I) -> RecoveryOutcome
+where
+    I: IntoIterator<Item = (String, String)>,
+{
+    for (k, v) in env {
+        if k == "TMUX_PANE" && !v.is_empty() {
+            return RecoveryOutcome::AutobindToPane(PaneId::new(v));
+        }
+    }
+    RecoveryOutcome::NeedsUserAttach
+}
+
+/// Emit the canonical `leader_receiver.rebind_required` event when the
+/// runtime falls through to `NeedsUserAttach`. Logs to stderr so operators
+/// see the cascade in event logs.
+pub fn log_rebind_required(reason: &str) {
+    eprintln!(
+        "team_agent::layout leader_receiver.rebind_required reason={reason} \
+         action=`run team-agent attach-leader from your leader pane`"
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tmux_pane_present_returns_autobind() {
+        let env = vec![
+            ("TMUX_PANE".to_string(), "%7".to_string()),
+            ("PATH".to_string(), "/bin".to_string()),
+        ];
+        let outcome = recover_leader_pane(env);
+        match outcome {
+            RecoveryOutcome::AutobindToPane(pane) => assert_eq!(pane.as_str(), "%7"),
+            other => panic!("expected AutobindToPane(%7), got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn no_tmux_pane_returns_needs_user_attach() {
+        let env = vec![("PATH".to_string(), "/bin".to_string())];
+        assert_eq!(recover_leader_pane(env), RecoveryOutcome::NeedsUserAttach);
+    }
+
+    #[test]
+    fn empty_tmux_pane_returns_needs_user_attach() {
+        let env = vec![("TMUX_PANE".to_string(), "".to_string())];
+        assert_eq!(recover_leader_pane(env), RecoveryOutcome::NeedsUserAttach);
+    }
+
+    #[test]
+    fn recovery_never_spawns_co_located_leader_window() {
+        // Python invariant #12: recovery requires TMUX_PANE; without it
+        // runtime emits rebind_required and CONTINUES. No silent co-located
+        // spawn into the worker session (the E57-3 root cause).
+        let env = vec![("WORKER_SESSION_LIVE".to_string(), "1".to_string())];
+        match recover_leader_pane(env) {
+            RecoveryOutcome::NeedsUserAttach => {} // expected
+            RecoveryOutcome::AutobindToPane(_) => {
+                panic!("recovery must not autobind without TMUX_PANE — \
+                        the worker session must NEVER carry a co-located leader \
+                        window in managed mode (E57-3 root)")
+            }
+        }
+    }
+}