@team-agent/installer 0.3.19 → 0.3.20

package/Cargo.lock

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

package/Cargo.toml

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

package/crates/team-agent/src/coordinator/backoff.rs

@@ -34,21 +34,42 @@ pub struct DaemonArgs {
 /// §10:返 `Result`(顶层 bin 用 anyhow 收;§12 边界)。
 pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     // CP-1: the daemon's whole tick surface (has_session / capture / inject / list_windows / kill)
-    // runs through this backend — bind it to the per-team socket so a dying shared `default` server
-    // can no longer tear the team down. The daemon knows its --workspace.
+    // runs through this backend. Prefer the persisted runtime endpoint so attached explicit-socket
+    // teams are checked on the same socket as lifecycle worker operations.
+    let state = crate::state::persist::load_runtime_state(args.workspace.as_path()).ok();
+    let tmux_selection = crate::tmux_backend::tmux_backend_for_runtime_state_or_workspace(
+        args.workspace.as_path(),
+        state.as_ref(),
+    );
+    let tmux_metadata = DaemonTmuxEndpointMetadata {
+        tmux_endpoint_used: tmux_selection.tmux_endpoint_used.clone(),
+        tmux_endpoint_source: tmux_selection.tmux_endpoint_source.as_str(),
+    };
     let coordinator = Coordinator::new(
         args.workspace.clone(),
         Box::new(RealProviderRegistry),
-        Box::new(crate::tmux_backend::TmuxBackend::for_workspace(
-            args.workspace.as_path(),
-        )),
+        Box::new(tmux_selection.backend),
     );
-    run_daemon_with_coordinator(&args, &coordinator)
+    run_daemon_with_coordinator_and_boot_tmux(&args, &coordinator, Some(tmux_metadata))
 }
 
 pub fn run_daemon_with_coordinator(
     args: &DaemonArgs,
     coordinator: &Coordinator,
+) -> Result<(), DaemonError> {
+    run_daemon_with_coordinator_and_boot_tmux(args, coordinator, None)
+}
+
+#[derive(Debug, Clone)]
+struct DaemonTmuxEndpointMetadata {
+    tmux_endpoint_used: Option<String>,
+    tmux_endpoint_source: &'static str,
+}
+
+fn run_daemon_with_coordinator_and_boot_tmux(
+    args: &DaemonArgs,
+    coordinator: &Coordinator,
+    tmux_metadata: Option<DaemonTmuxEndpointMetadata>,
 ) -> Result<(), DaemonError> {
     let runtime_dir = crate::model::paths::runtime_dir(args.workspace.as_path());
     std::fs::create_dir_all(&runtime_dir)?;
@@ -57,13 +78,26 @@ pub fn run_daemon_with_coordinator(
     write_coordinator_metadata(&args.workspace, pid, MetadataSource::Boot)?;
 
     let event_log = EventLog::new(args.workspace.as_path());
-    event_log.write(
-        "coordinator.boot",
-        serde_json::json!({
-            "workspace": args.workspace.as_path().to_string_lossy(),
-            "once": args.once,
-        }),
-    )?;
+    let mut boot_event = serde_json::json!({
+        "workspace": args.workspace.as_path().to_string_lossy(),
+        "once": args.once,
+    });
+    if let Some(metadata) = tmux_metadata {
+        if let Some(object) = boot_event.as_object_mut() {
+            object.insert(
+                "tmux_endpoint_source".to_string(),
+                serde_json::Value::String(metadata.tmux_endpoint_source.to_string()),
+            );
+            object.insert(
+                "tmux_endpoint_used".to_string(),
+                metadata
+                    .tmux_endpoint_used
+                    .map(serde_json::Value::String)
+                    .unwrap_or(serde_json::Value::Null),
+            );
+        }
+    }
+    event_log.write("coordinator.boot", boot_event)?;
     let tick_interval = match args.tick_interval_sec {
         Some(v) if v > 0.0 => v,
         _ => resolve_tick_interval(&args.workspace)?,

package/crates/team-agent/src/coordinator/tests/daemon.rs

@@ -209,6 +209,156 @@ fn coord_over_staged_tmux(
     (coord, dir, seen)
 }
 
+fn coord_over_runtime_state_tmux_endpoint(
+    session_name: &str,
+    endpoint: &str,
+    steps: Vec<RunnerStep>,
+    last: RunnerStep,
+) -> (
+    Coordinator,
+    std::path::PathBuf,
+    std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
+    Option<String>,
+    &'static str,
+) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static N: AtomicU64 = AtomicU64::new(0);
+    let dir = std::env::temp_dir().join(format!(
+        "ta-rs-e27-coord-explicit-{}-{}",
+        std::process::id(),
+        N.fetch_add(1, Ordering::Relaxed)
+    ));
+    std::fs::create_dir_all(crate::model::paths::runtime_dir(&dir)).unwrap();
+    let _ = crate::message_store::MessageStore::open(&dir).unwrap();
+    let state = serde_json::json!({
+        "session_name": session_name,
+        "tmux_endpoint": endpoint,
+        "tmux_socket": endpoint,
+        "agents": {},
+    });
+    crate::state::persist::save_runtime_state(&dir, &state).unwrap();
+    let seen = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    let runner = StagedTmuxRunner {
+        steps: std::sync::Mutex::new(steps.into_iter().collect()),
+        last,
+        seen: std::sync::Arc::clone(&seen),
+    };
+    let selection = crate::tmux_backend::tmux_backend_with_runner_for_runtime_state_or_workspace(
+        Box::new(runner),
+        &dir,
+        Some(&state),
+    );
+    let endpoint_used = selection.tmux_endpoint_used.clone();
+    let endpoint_source = selection.tmux_endpoint_source.as_str();
+    let reg: Box<dyn ProviderRegistry> = Box::new(MockRegistry::new(&[], &[]));
+    let coord = Coordinator::for_test(
+        WorkspacePath::new(dir.clone()),
+        reg,
+        Box::new(selection.backend),
+        None,
+        None,
+    );
+    (coord, dir, seen, endpoint_used, endpoint_source)
+}
+
+#[test]
+fn e27_coordinator_tick_uses_runtime_explicit_endpoint_for_session_gate() {
+    let session = "team-e27-explicit-restart";
+    let endpoint = "/tmp/e27-explicit-restart-test.sock";
+    let (coord, dir, seen, endpoint_used, endpoint_source) = coord_over_runtime_state_tmux_endpoint(
+        session,
+        endpoint,
+        vec![RunnerStep::Exit(true)],
+        RunnerStep::Exit(true),
+    );
+    assert_eq!(endpoint_used.as_deref(), Some(endpoint));
+    assert_eq!(endpoint_source, "state.tmux_endpoint");
+
+    let report = coord
+        .tick()
+        .expect("explicit endpoint with present session should tick");
+    assert!(
+        report.ok,
+        "present explicit endpoint session should keep tick ok"
+    );
+    assert!(
+        !report.stop,
+        "present explicit endpoint session must not trip the session-missing stop gate"
+    );
+    let calls = seen.lock().unwrap().clone();
+    assert!(
+        calls
+            .iter()
+            .all(|argv| !argv.iter().any(|part| part == "-L")),
+        "explicit endpoint coordinator must not fall back to workspace -L socket; got {calls:?}"
+    );
+    assert_eq!(
+        calls.first(),
+        Some(&vec![
+            "tmux".to_string(),
+            "-S".to_string(),
+            endpoint.to_string(),
+            "has-session".to_string(),
+            "-t".to_string(),
+            session.to_string(),
+        ]),
+        "session gate must probe the persisted explicit endpoint"
+    );
+    let events = read_event_log_dir(&dir);
+    assert!(
+        events
+            .iter()
+            .all(|event| event.get("event").and_then(|v| v.as_str())
+                != Some("coordinator.session_missing")),
+        "present explicit endpoint session must not emit coordinator.session_missing; got {events:?}"
+    );
+}
+
+#[test]
+fn e27_coordinator_tick_still_stops_when_explicit_endpoint_session_is_missing() {
+    let session = "team-e27-explicit-restart";
+    let endpoint = "/tmp/e27-explicit-restart-test.sock";
+    let (coord, dir, seen, endpoint_used, endpoint_source) = coord_over_runtime_state_tmux_endpoint(
+        session,
+        endpoint,
+        vec![RunnerStep::Exit(false)],
+        RunnerStep::Exit(false),
+    );
+    assert_eq!(endpoint_used.as_deref(), Some(endpoint));
+    assert_eq!(endpoint_source, "state.tmux_endpoint");
+
+    let report = coord
+        .tick()
+        .expect("definitive missing session is a typed stop report");
+    assert!(!report.ok, "missing explicit endpoint session => ok=false");
+    assert!(
+        report.stop,
+        "genuine missing session on the selected explicit endpoint must still stop"
+    );
+    assert_eq!(report.reason, Some(TickStopReason::TmuxSessionMissing));
+    let calls = seen.lock().unwrap().clone();
+    assert_eq!(
+        calls.first(),
+        Some(&vec![
+            "tmux".to_string(),
+            "-S".to_string(),
+            endpoint.to_string(),
+            "has-session".to_string(),
+            "-t".to_string(),
+            session.to_string(),
+        ]),
+        "negative control must also probe the persisted explicit endpoint"
+    );
+    let events = read_event_log_dir(&dir);
+    assert!(
+        events
+            .iter()
+            .any(|event| event.get("event").and_then(|v| v.as_str())
+                == Some("coordinator.session_missing")),
+        "genuine explicit endpoint miss must still emit coordinator.session_missing; got {events:?}"
+    );
+}
+
 // ── 2(a) tick TOLERATES a has-session TIMEOUT as Err (NOT a definitive miss) — LOCK ───────────────
 #[test]
 fn tick_tolerates_has_session_timeout_as_transport_err_not_session_missing() {

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

@@ -17,6 +17,8 @@ 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)?;
     start_agent_at_paths(
         &paths.run_workspace,
         &paths.spec_workspace,
@@ -25,7 +27,7 @@ pub fn start_agent(
         open_display,
         allow_fresh,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&paths.run_workspace),
+        &transport,
     )
 }
 
@@ -267,11 +269,15 @@ pub fn stop_agent(
     agent_id: &AgentId,
     team: Option<&str>,
 ) -> Result<StopAgentReport, LifecycleError> {
-    stop_agent_with_transport(
-        workspace,
+    let paths = lifecycle_paths(workspace, team)?;
+    let transport =
+        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    stop_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
         agent_id,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&lifecycle_run_workspace(workspace)?),
+        &transport,
     )
 }
 
@@ -473,13 +479,22 @@ pub fn reset_agent(
     open_display: bool,
     team: Option<&str>,
 ) -> Result<ResetAgentOutcome, LifecycleError> {
-    reset_agent_with_transport(
-        workspace,
+    if !discard_session {
+        return Ok(ResetAgentOutcome::Refused {
+            reason: ResetRefusal::DiscardSessionRequired,
+        });
+    }
+    let paths = lifecycle_paths(workspace, team)?;
+    let transport =
+        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    reset_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
         agent_id,
         discard_session,
         open_display,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&lifecycle_run_workspace(workspace)?),
+        &transport,
     )
 }
 

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

@@ -208,6 +208,38 @@ pub(super) fn start_coordinator_for_workspace(workspace: &Path) -> Result<bool,
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))
 }
 
+pub(super) fn lifecycle_worker_tmux_backend_for_selected_state(
+    run_workspace: &Path,
+    team: Option<&str>,
+) -> Result<crate::tmux_backend::TmuxBackend, LifecycleError> {
+    let (state, refusal) = crate::state::projection::resolve_team_scoped_state(run_workspace, team)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    if let Some(refusal) = refusal {
+        let reason = refusal
+            .get("reason")
+            .and_then(|v| v.as_str())
+            .unwrap_or("team_target_unresolved");
+        let detail = refusal
+            .get("error")
+            .or_else(|| refusal.get("message"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("");
+        return Err(LifecycleError::TeamSelect(format!("{reason}: {detail}")));
+    }
+    Ok(state
+        .as_ref()
+        .map(|state| lifecycle_worker_tmux_backend_for_state(run_workspace, state))
+        .unwrap_or_else(|| crate::tmux_backend::TmuxBackend::for_workspace(run_workspace)))
+}
+
+pub(super) fn lifecycle_worker_tmux_backend_for_state(
+    run_workspace: &Path,
+    state: &serde_json::Value,
+) -> crate::tmux_backend::TmuxBackend {
+    crate::tmux_backend::tmux_backend_for_runtime_state_or_workspace(run_workspace, Some(state))
+        .backend
+}
+
 pub(super) fn persist_effective_approval_policy_for_restart(
     agent: &mut serde_json::Map<String, serde_json::Value>,
     safety: &DangerousApproval,

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

@@ -22,12 +22,14 @@ pub fn restart_with_session_convergence_deadline(
     team: Option<&str>,
     session_converge_deadline_ms: Option<u64>,
 ) -> Result<RestartReport, LifecycleError> {
-    let run_ws = lifecycle_run_workspace(workspace)?;
+    let paths = lifecycle_paths(workspace, team)?;
+    let transport =
+        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
     restart_with_transport_with_session_convergence_deadline(
         workspace,
         allow_fresh,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&run_ws),
+        &transport,
         session_converge_deadline_ms,
         None,
     )

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

@@ -13,13 +13,17 @@ pub fn remove_agent(
     force: bool,
     team: Option<&str>,
 ) -> Result<RemoveAgentOutcome, LifecycleError> {
-    remove_agent_with_transport(
-        workspace,
+    let paths = lifecycle_paths(workspace, team)?;
+    let transport =
+        lifecycle_worker_tmux_backend_for_selected_state(&paths.run_workspace, team)?;
+    remove_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
         agent_id,
         from_spec,
         force,
         team,
-        &crate::tmux_backend::TmuxBackend::for_workspace(&lifecycle_run_workspace(workspace)?),
+        &transport,
     )
 }
 

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

@@ -260,6 +260,228 @@ fn bug_a_stop_agent_team_dir_input_kills_existing_window_real_machine() {
     assert!(report.stopped, "existing worker window must be killed, not silently reported absent");
 }
 
+struct EnvVarGuard {
+    key: &'static str,
+    previous: Option<String>,
+}
+
+impl EnvVarGuard {
+    fn set(key: &'static str, value: &str) -> Self {
+        let previous = std::env::var(key).ok();
+        unsafe {
+            std::env::set_var(key, value);
+        }
+        Self { key, previous }
+    }
+}
+
+impl Drop for EnvVarGuard {
+    fn drop(&mut self) {
+        unsafe {
+            if let Some(value) = self.previous.take() {
+                std::env::set_var(self.key, value);
+            } else {
+                std::env::remove_var(self.key);
+            }
+        }
+    }
+}
+
+struct TmuxShim {
+    log: std::path::PathBuf,
+    _path: EnvVarGuard,
+    _log: EnvVarGuard,
+    _endpoint: EnvVarGuard,
+    _session: EnvVarGuard,
+    _pane: EnvVarGuard,
+    _real_tmux: EnvVarGuard,
+}
+
+fn install_e27_tmux_shim(expected_endpoint: &str, session_name: &str) -> TmuxShim {
+    use std::os::unix::fs::PermissionsExt;
+
+    let root = temp_ws().join("e27_tmux_shim");
+    let bin = root.join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    let log = root.join("tmux-argv.log");
+    let tmux = bin.join("tmux");
+    let real_tmux = std::process::Command::new("sh")
+        .arg("-lc")
+        .arg("command -v tmux || true")
+        .output()
+        .ok()
+        .and_then(|out| String::from_utf8(out.stdout).ok())
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .unwrap_or_default();
+    std::fs::write(
+        &tmux,
+        r#"#!/bin/sh
+set -eu
+log="${TEAM_AGENT_E27_TMUX_LOG}"
+expected="${TEAM_AGENT_E27_EXPECTED_ENDPOINT}"
+session="${TEAM_AGENT_E27_SESSION_NAME}"
+pane="${TEAM_AGENT_E27_PANE_ID}"
+track=0
+case "$*" in
+  *"$expected"*|*"$session"*|*"$pane"*) track=1 ;;
+esac
+if [ "$track" != 1 ]; then
+  if [ -n "${TEAM_AGENT_E27_REAL_TMUX}" ]; then
+    exec "${TEAM_AGENT_E27_REAL_TMUX}" "$@"
+  fi
+  exit 127
+fi
+printf '%s\n' "$*" >> "$log"
+case "$*" in
+  *"-S $expected"*) ;;
+  *)
+    echo "missing expected socket $expected: $*" >&2
+    exit 18
+    ;;
+esac
+case "$*" in
+  *"display-message -p -t $pane #{pane_id}"*)
+    printf '%s\n' "$pane"
+    exit 0
+    ;;
+  *"display-message -p -t $session:alpha #{pane_id}"*)
+    printf '%%9288\n'
+    exit 0
+    ;;
+  *"list-windows -t $session -F #{window_name}"*)
+    exit 0
+    ;;
+  *"has-session -t $session"*)
+    exit 0
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+"#,
+    )
+    .unwrap();
+    let mut perms = std::fs::metadata(&tmux).unwrap().permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(&tmux, perms).unwrap();
+    let old_path = std::env::var("PATH").unwrap_or_default();
+    TmuxShim {
+        log: log.clone(),
+        _path: EnvVarGuard::set("PATH", &format!("{}:{old_path}", bin.display())),
+        _log: EnvVarGuard::set("TEAM_AGENT_E27_TMUX_LOG", &log.to_string_lossy()),
+        _endpoint: EnvVarGuard::set("TEAM_AGENT_E27_EXPECTED_ENDPOINT", expected_endpoint),
+        _session: EnvVarGuard::set("TEAM_AGENT_E27_SESSION_NAME", session_name),
+        _pane: EnvVarGuard::set("TEAM_AGENT_E27_PANE_ID", "%9277"),
+        _real_tmux: EnvVarGuard::set("TEAM_AGENT_E27_REAL_TMUX", &real_tmux),
+    }
+}
+
+fn seed_e27_attached_socket_state(ws: &std::path::Path, endpoint: &str, session_name: &str) {
+    let mut state = crate::state::persist::load_runtime_state(ws).unwrap();
+    let obj = state.as_object_mut().unwrap();
+    obj.insert("session_name".to_string(), json!(session_name));
+    obj.insert("tmux_endpoint".to_string(), json!(endpoint));
+    obj.insert("tmux_socket".to_string(), json!(endpoint));
+    let alpha = obj
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|agents| agents.get_mut("alpha"))
+        .and_then(serde_json::Value::as_object_mut)
+        .unwrap();
+    alpha.insert("status".to_string(), json!("running"));
+    alpha.insert("provider".to_string(), json!("fake"));
+    alpha.insert("window".to_string(), json!("alpha"));
+    alpha.insert("pane_id".to_string(), json!("%9277"));
+    alpha.insert("session_id".to_string(), json!("old-session"));
+    crate::state::persist::save_runtime_state(ws, &state).unwrap();
+    seed_healthy_coordinator(ws);
+}
+
+fn assert_only_expected_socket_used(log: &std::path::Path, expected_endpoint: &str) {
+    let raw = std::fs::read_to_string(log).unwrap();
+    assert!(!raw.is_empty(), "tmux shim was not invoked");
+    assert!(
+        !raw.contains("-L ta-"),
+        "lifecycle worker operation must not use workspace-derived -L ta-* socket; argv log:\n{raw}"
+    );
+    for line in raw.lines() {
+        assert!(
+            line.contains(&format!("-S {expected_endpoint}")),
+            "tmux argv must use state endpoint {expected_endpoint}; got line {line:?}; full log:\n{raw}"
+        );
+    }
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn e27_stop_agent_uses_attached_explicit_state_socket() {
+    let endpoint = "/tmp/loop13-e27-explicit.sock";
+    let session_name = "team-e27-explicit-stop";
+    let ws = lanea_team_ws("running");
+    seed_e27_attached_socket_state(&ws, endpoint, session_name);
+    let shim = install_e27_tmux_shim(endpoint, session_name);
+
+    let report = stop_agent(&ws, &aid("alpha"), None).expect("stop-agent");
+
+    assert!(report.stopped, "attached explicit-socket worker should be stopped");
+    assert_only_expected_socket_used(&shim.log, endpoint);
+    let state = crate::state::persist::load_runtime_state(&ws).unwrap();
+    assert_eq!(
+        state.pointer("/agents/alpha/status").and_then(serde_json::Value::as_str),
+        Some("stopped")
+    );
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn e27_reset_agent_uses_attached_explicit_state_socket_for_stop_and_spawn() {
+    let endpoint = "/tmp/loop13-e27-explicit.sock";
+    let session_name = "team-e27-explicit-reset";
+    let ws = lanea_team_ws("running");
+    seed_e27_attached_socket_state(&ws, endpoint, session_name);
+    let shim = install_e27_tmux_shim(endpoint, session_name);
+
+    let outcome = reset_agent(&ws, &aid("alpha"), true, false, None).expect("reset-agent");
+
+    assert!(
+        matches!(outcome, ResetAgentOutcome::Reset { .. }),
+        "reset-agent should complete over attached explicit socket; got {outcome:?}"
+    );
+    assert_only_expected_socket_used(&shim.log, endpoint);
+    let raw = std::fs::read_to_string(&shim.log).unwrap();
+    assert!(raw.contains("kill-pane"), "reset must stop the old pane first; argv log:\n{raw}");
+    assert!(
+        raw.contains("new-window") || raw.contains("new-session"),
+        "reset must respawn the worker through the same endpoint; argv log:\n{raw}"
+    );
+    let state = crate::state::persist::load_runtime_state(&ws).unwrap();
+    assert_ne!(
+        state.pointer("/agents/alpha/session_id").and_then(serde_json::Value::as_str),
+        Some("old-session"),
+        "discard-session must not preserve the old session id"
+    );
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn e27_stop_agent_expands_short_state_socket_name() {
+    let short = "ta-loop13-e27-short";
+    let session_name = "team-e27-short-stop";
+    let expected = crate::tmux_backend::socket_path_for_name(short)
+        .unwrap()
+        .to_string_lossy()
+        .to_string();
+    let ws = lanea_team_ws("running");
+    seed_e27_attached_socket_state(&ws, short, session_name);
+    let shim = install_e27_tmux_shim(&expected, session_name);
+
+    let report = stop_agent(&ws, &aid("alpha"), None).expect("stop-agent short endpoint");
+
+    assert!(report.stopped, "short endpoint worker should be stopped");
+    assert_only_expected_socket_used(&shim.log, &expected);
+}
+
 // ═════════════════════════════════════════════════════════════════════════
 // WAVE-2 · LANE A v2 — DEEPENED byte-parity REDs (stop / reset / remove / fork).
 //

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

@@ -188,6 +188,29 @@ impl TmuxSocketEndpoint {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RuntimeTmuxEndpointSource {
+    StateTmuxEndpoint,
+    StateTmuxSocket,
+    WorkspaceFallback,
+}
+
+impl RuntimeTmuxEndpointSource {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::StateTmuxEndpoint => "state.tmux_endpoint",
+            Self::StateTmuxSocket => "state.tmux_socket",
+            Self::WorkspaceFallback => "workspace_fallback",
+        }
+    }
+}
+
+pub(crate) struct RuntimeTmuxBackendSelection {
+    pub(crate) backend: TmuxBackend,
+    pub(crate) tmux_endpoint_used: Option<String>,
+    pub(crate) tmux_endpoint_source: RuntimeTmuxEndpointSource,
+}
+
 impl TmuxBackend {
     /// Backend bound to the real `tmux` subprocess on the SHARED default socket (no `-L`).
     /// Non-team callers + existing argv/unit tests stay unaffected.
@@ -338,6 +361,70 @@ impl TmuxBackend {
     }
 }
 
+pub(crate) fn tmux_backend_for_runtime_state_or_workspace(
+    workspace: &Path,
+    state: Option<&serde_json::Value>,
+) -> RuntimeTmuxBackendSelection {
+    let (backend, source) =
+        if let Some((endpoint, source)) = runtime_tmux_endpoint_from_state(state) {
+            (TmuxBackend::for_tmux_endpoint(endpoint), source)
+        } else {
+            (
+                TmuxBackend::for_workspace(workspace),
+                RuntimeTmuxEndpointSource::WorkspaceFallback,
+            )
+        };
+    RuntimeTmuxBackendSelection {
+        tmux_endpoint_used: backend.tmux_endpoint(),
+        backend,
+        tmux_endpoint_source: source,
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn tmux_backend_with_runner_for_runtime_state_or_workspace(
+    runner: Box<dyn CommandRunner>,
+    workspace: &Path,
+    state: Option<&serde_json::Value>,
+) -> RuntimeTmuxBackendSelection {
+    let (backend, source) =
+        if let Some((endpoint, source)) = runtime_tmux_endpoint_from_state(state) {
+            (
+                TmuxBackend::with_runner_for_tmux_endpoint(runner, endpoint),
+                source,
+            )
+        } else {
+            (
+                TmuxBackend::with_runner_for_workspace(runner, workspace),
+                RuntimeTmuxEndpointSource::WorkspaceFallback,
+            )
+        };
+    RuntimeTmuxBackendSelection {
+        tmux_endpoint_used: backend.tmux_endpoint(),
+        backend,
+        tmux_endpoint_source: source,
+    }
+}
+
+fn runtime_tmux_endpoint_from_state(
+    state: Option<&serde_json::Value>,
+) -> Option<(&str, RuntimeTmuxEndpointSource)> {
+    state.and_then(|state| {
+        state
+            .get("tmux_endpoint")
+            .and_then(|v| v.as_str())
+            .filter(|endpoint| !endpoint.is_empty())
+            .map(|endpoint| (endpoint, RuntimeTmuxEndpointSource::StateTmuxEndpoint))
+            .or_else(|| {
+                state
+                    .get("tmux_socket")
+                    .and_then(|v| v.as_str())
+                    .filter(|endpoint| !endpoint.is_empty())
+                    .map(|endpoint| (endpoint, RuntimeTmuxEndpointSource::StateTmuxSocket))
+            })
+    })
+}
+
 /// CP-1 socket name: SHORT + DETERMINISTIC per canonical workspace path. `ta-` + 12 hex chars of a
 /// stable FNV-1a hash over the canonicalized path. AF_UNIX `sun_path` is ~104 chars and the socket
 /// lives at `/tmp/tmux-<uid>/<name>`, so we must NOT use the (~88-char) session name. §10: a

package/package.json

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