@team-agent/installer 0.5.60 → 0.5.62

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

@@ -1,3 +1,4 @@
+//!
 //! step 5 · state — state.json 持久化 / identity / owner-gate / projection(真相源 `state.py`)。
 //!
 //! §6 step 5:原子写/锁/self-heal(**bug-084** 血泪)/ team projection / leader receiver identity /
@@ -32,6 +33,7 @@ pub mod selector;
 use serde_json::Value;
 use thiserror::Error;
 
+///
 /// Python 真值语义(`null`/`false`/`0`/`""`/`[]`/`{}` → false),`state` 模块共用。
 pub(crate) fn json_truthy(v: &Value) -> bool {
     match v {

package/crates/team-agent/src/state/owner_gate.rs

@@ -1,3 +1,4 @@
+//!
 //! owner-gate:trust own-vs-foreign(§11 / bug-064 / bug-082 血泪;真相源 `state.py`)。
 //!
 //! 三核心纯判定(集成 send_message/MCP 是 step 11/14):
@@ -37,6 +38,7 @@ pub struct CallerIdentity {
     pub leader_session_uuid_source: String,
 }
 
+///
 /// `check_team_owner`(`state.py:366`)的纯判定版:caller 身份 + 是否有 TEAM_AGENT_ID + liveness 注入。
 /// 返回 `None`=允许(own / 无 owner / 死 owner pane 可接管);`Some(dict)`=拒绝(team_owner_mismatch)。
 ///
@@ -123,6 +125,7 @@ fn caller_to_value(c: &CallerIdentity) -> Value {
     })
 }
 
+///
 /// `worker_sender_bypasses_owner_gate`(`state.py:400`):worker peer-send 绕过 owner 门。
 /// 返回 `Some(agent_id)`=绕过;`None`=不绕过(走 owner 门)。
 pub fn worker_sender_bypasses_owner_gate(
@@ -160,6 +163,7 @@ pub fn worker_sender_bypasses_owner_gate(
     Some(sender.to_string())
 }
 
+///
 /// §11 realpath own-vs-foreign(`state.py:449`):**两边 canonicalize** 后全等才判 own。
 /// macOS `/tmp → /private/tmp` 软链不对称由「两边 canonicalize」消除。canonicalize 失败(路径不存在)
 /// → 退化为词法绝对比较(此时无软链可解,等价)。**禁 basename/startswith/子串/反推**。
@@ -187,6 +191,7 @@ fn lexical_abs(p: &Path) -> std::path::PathBuf {
     }
 }
 
+///
 /// `os.path.realpath` 等价(对抗 P0-B):全路径存在 → `canonicalize`;否则对**最长存在前缀**
 /// canonicalize(解析其软链)再拼回缺失末段(规范化 `..`/`.`)。这复刻 Python「解析存在部分的
 /// 软链 + 保留不存在末段」,修掉「父目录是软链 + 末段不存在 → 漏判 own」的 §11 血泪。

package/crates/team-agent/src/state/ownership.rs

@@ -1,3 +1,4 @@
+//!
 //! Stage 2 of identity-boundary unified plan (architect direction 2026-06-23):
 //! `state::ownership` — single read entry point for `team_owner` lookups.
 //!
@@ -41,7 +42,7 @@ use crate::state::projection::{read_owner as projection_read_owner, team_state_k
 /// owner value. CLI status / diagnose use it to surface legacy duplicate
 /// warnings.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum OwnershipSource {
+enum OwnershipSource {
     /// Stage 5 canonical path: `.team/runtime/<team_key>/state.json` (not
     /// yet emitted — placeholder for forward compatibility).
     CanonicalPerTeamState,
@@ -57,11 +58,12 @@ pub enum OwnershipSource {
 /// caller consumes (same shape as `state.get("team_owner")` returned today);
 /// the `source` is diagnostic.
 #[derive(Debug, Clone)]
-pub struct OwnershipRead<'a> {
+struct OwnershipRead<'a> {
     pub value: &'a Value,
     pub source: OwnershipSource,
 }
 
+///
 /// Stage 2 entry point: read the team owner for the given `team_key` from an
 /// in-memory state value, honouring the legacy precedence. Returns `None` if
 /// no source carries a non-empty, valid owner record.
@@ -73,7 +75,7 @@ pub struct OwnershipRead<'a> {
 /// This deliberately reuses `projection::read_owner` so the pane-id validity
 /// check (`%N` or all-digits) stays in one place. The repository's value-add
 /// is the precedence ordering and the `OwnershipSource` tag.
-pub fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<OwnershipRead<'a>> {
+fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<OwnershipRead<'a>> {
     // Step 1 (Stage 5): canonical per-team state. Stage 2 does not consult
     // a separate file yet — owner truth still lives in the in-memory state.
     // Once Stage 5 wires `.team/runtime/<team_key>/state.json` as canonical,
@@ -109,6 +111,7 @@ pub fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<Owner
     None
 }
 
+///
 /// Convenience: just the JSON value, no diagnostic source. Returns `None`
 /// when no owner is found. Stable across Stage 5 — only the lookup
 /// implementation will move.
@@ -116,6 +119,7 @@ pub fn read_owner_value<'a>(state: &'a Value, team_key: &str) -> Option<&'a Valu
     read_owner_for_team(state, team_key).map(|read| read.value)
 }
 
+///
 /// Stage 3 (identity-boundary unified plan, architect direction 2026-06-23):
 /// single write entry point for owner mutations. Pre-Stage-3, owner writes
 /// were spread across 13 sites (claim/attach/readopt/managed-leader/quick-
@@ -187,6 +191,7 @@ pub fn write_owner(state: &mut Value, team_key: &str, record: OwnershipWrite) {
     }
 }
 
+///
 /// Stage 3 top-level cleanup (architect direction 2026-06-24,
 /// .team/artifacts/stage3-toplevel-cleanup-fix.md): strip the legacy
 /// top-level `team_owner / leader_receiver / owner_epoch` fields from a
@@ -202,12 +207,13 @@ pub fn write_owner(state: &mut Value, team_key: &str, record: OwnershipWrite) {
 /// load-time path — legacy single-team states may still have only
 /// top-level owner and no canonical `teams.<key>` owner, and a blind load
 /// strip would lose ownership before migration.
-pub fn strip_top_level_ownership(root: &mut serde_json::Map<String, Value>) {
+fn strip_top_level_ownership(root: &mut serde_json::Map<String, Value>) {
     for key in ["team_owner", "leader_receiver", "owner_epoch"] {
         root.remove(key);
     }
 }
 
+///
 /// Stage 3 save-output canonical-aware strip (architect direction
 /// 2026-06-24, .team/artifacts/stage3-save-strip-fix.md): conditional
 /// version of `strip_top_level_ownership` used by `state::persist`'s

package/crates/team-agent/src/state/paths.rs

@@ -1,3 +1,4 @@
+//!
 //! Stage 0 of the identity-boundary unified plan (architect direction
 //! 2026-06-23): `TeamScope` + `TeamRuntimePaths` foundation.
 //!
@@ -42,6 +43,7 @@ pub struct TeamScope {
 }
 
 impl TeamScope {
+    ///
     /// Construct a TeamScope from an already-resolved workspace + team_key.
     /// Callers that have a display name must resolve it through the existing
     /// `state::selector` machinery first; this constructor refuses an empty
@@ -66,6 +68,7 @@ impl TeamScope {
         &self.team_key
     }
 
+    ///
     /// Convenience: derive the path helper from this scope.
     pub fn paths(&self) -> TeamRuntimePaths {
         TeamRuntimePaths::for_scope(self)
@@ -110,6 +113,7 @@ impl TeamRuntimePaths {
         &self.team_key
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/` — the team's future B3 runtime
     /// directory. It is not used as product authority until the B3 migration;
     /// current callers must keep using `runtime_state_path`.
@@ -119,6 +123,7 @@ impl TeamRuntimePaths {
             .join(&self.team_key)
     }
 
+    ///
     /// Transitional runtime spec path. Mirrors the existing
     /// `runtime_spec_path` helper while specs remain at
     /// `.team/runtime/<team_key>/team.spec.yaml`.
@@ -126,6 +131,7 @@ impl TeamRuntimePaths {
         runtime_spec_path(&self.workspace, &self.team_key)
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/state.json` — the canonical per-team
     /// state path that B3 will start writing. Not used by current product
     /// code; callers must continue using `runtime_state_path` until B3
@@ -134,11 +140,13 @@ impl TeamRuntimePaths {
         self.team_dir().join("state.json")
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/coordinator.pid` — future sidecar location.
     pub fn coordinator_pid_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.pid")
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/coordinator.log` — future sidecar location.
     pub fn coordinator_log_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.log")
@@ -180,6 +188,7 @@ pub enum CommandScope {
 }
 
 impl CommandScope {
+    ///
     /// Resolve the CLI's `--team` argument against the workspace state.
     /// On any I/O error the empty case is returned — destructive commands
     /// will run their own selector and surface the real error.
@@ -202,6 +211,7 @@ impl CommandScope {
         }
     }
 
+    ///
     /// Convert to an `Option<String>` for backward compatibility with
     /// existing `args.team.as_deref()` call sites.
     pub fn team_key(&self) -> Option<&str> {
@@ -211,11 +221,13 @@ impl CommandScope {
         }
     }
 
+    ///
     /// True iff there are 2+ alive teams and no explicit `--team`.
     pub fn is_ambiguous(&self) -> bool {
         matches!(self, Self::Ambiguous(_))
     }
 
+    ///
     /// The candidate list when ambiguous; empty otherwise.
     pub fn candidates(&self) -> &[String] {
         match self {

package/crates/team-agent/src/state/persist.rs

@@ -1,3 +1,4 @@
+//!
 //! state.json 持久化(bug-084 韧性;真相源 `state.py:save_runtime_state` + `_self_heal_runtime_state`
 //! + `runtime.py:_runtime_lock`)。
 //!
@@ -71,6 +72,7 @@ static RUNTIME_STATE_CACHE: LazyLock<Mutex<HashMap<PathBuf, Value>>> =
     LazyLock::new(|| Mutex::new(HashMap::new()));
 static TMP_SEQ: AtomicU64 = AtomicU64::new(0);
 
+///
 /// `state.py:41`。
 pub fn runtime_state_path(workspace: &Path) -> PathBuf {
     runtime_dir(workspace).join("state.json")
@@ -202,6 +204,7 @@ impl Drop for RuntimeLock {
     }
 }
 
+///
 /// `save_runtime_state`(bug-084)。`state` 是 state.json 的内存 Value(插入序保留)。
 /// 注:Python 在此还调 `_migrate_state_identity`(identity slice 落地后接入;本 slice 不改 state 内容)。
 pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateError> {
@@ -1135,10 +1138,11 @@ fn self_heal(
     }
 }
 
+///
 /// `load_runtime_state`(本 slice 最小:读+parse+缓存;normalize/migration 待 identity slice)。
 /// `normalize_agent_session_state`(`state.py:45`):为每个 agent dict 的 SESSION_STATE_FIELDS
 /// setdefault None(缺则末尾插)。
-pub fn normalize_agent_session_state(state: &mut Value) {
+fn normalize_agent_session_state(state: &mut Value) {
     let Some(agents) = state.get_mut("agents").and_then(Value::as_object_mut) else {
         return;
     };
@@ -1151,12 +1155,13 @@ pub fn normalize_agent_session_state(state: &mut Value) {
     }
 }
 
+///
 /// `_migrate_active_team_key`(`state.py:73`,0.2.6 Family B C6):legacy state 缺 active_team_key
 /// 时 seed 一次。返回是否有改动。
 ///
 /// 注:Python `seed if seed in teams or not teams else seed` 两支均为 `seed`(死三元),
 /// 此处直接 `= seed`,与可观测行为一致。
-pub fn migrate_active_team_key(state: &mut Value) -> bool {
+fn migrate_active_team_key(state: &mut Value) -> bool {
     if state
         .as_object()
         .is_some_and(|o| o.contains_key("active_team_key"))
@@ -1191,6 +1196,7 @@ pub fn migrate_active_team_key(state: &mut Value) -> bool {
     true
 }
 
+///
 /// RM-039-STAT-001 second-round compat normalizer (architect verdict
 /// 2026-06-22). When `active_team_key` names an existing `teams` entry
 /// but root `team_key` is missing, set root `team_key = active_team_key`
@@ -1210,7 +1216,7 @@ pub fn migrate_active_team_key(state: &mut Value) -> bool {
 ///   * Does NOT touch any other field (no generic deep merge).
 ///
 /// Returns `true` if state was mutated and the caller should persist.
-pub fn migrate_team_key_to_match_active_team(state: &mut Value) -> bool {
+fn migrate_team_key_to_match_active_team(state: &mut Value) -> bool {
     let Some(obj) = state.as_object() else {
         return false;
     };

package/crates/team-agent/src/state/projection.rs

@@ -1,3 +1,4 @@
+//!
 //! projection:team 选择 / top-level 派生视图(真相源 `state.py`,0.2.6 Family B C6-C8)。
 //!
 //! `state.teams` 是唯一候选源(`status == "alive"`);顶层 `session_name`/`team_dir`/`agents`/`tasks`
@@ -24,6 +25,7 @@ use crate::state::persist::{
 
 pub(crate) const CURRENT_TEAM_ALIAS: &str = "current";
 
+///
 /// `team_state_key`(`state.py:93`):从 team_dir(.name)/spec_path(.parent.name)派生 team key,
 /// 跳过 `.team`/`runtime`;兜底 `session_name` 或 `"current"`。
 pub fn team_state_key(state: &Value) -> String {
@@ -184,6 +186,7 @@ fn legacy_owner_team_aliases(entry: &Value) -> impl Iterator<Item = String> + '_
         .map(str::to_string)
 }
 
+///
 /// `compact_team_state`(`state.py:105`):剔除 `teams`(team entry 不嵌套全量 teams),保序。
 pub fn compact_team_state(state: &Value) -> Value {
     match state.as_object() {
@@ -208,6 +211,7 @@ pub fn state_is_managed_leader(state: &Value) -> bool {
     !state_is_external_leader(state)
 }
 
+///
 /// `merge_workspace_team_state`(`state.py:111`):把新启动的 team 并入既有 workspace state。
 pub fn merge_workspace_team_state(existing: &Value, launched: &Value) -> Value {
     let launched_key = team_state_key(launched);
@@ -239,6 +243,7 @@ pub fn merge_workspace_team_state(existing: &Value, launched: &Value) -> Value {
     Value::Object(merged)
 }
 
+///
 /// `team_state_candidates`(`state.py:131`):唯一候选源 = `state.teams` 中
 /// `status=="alive"`(大小写不敏感;缺 status/空 视为 alive,但 0.5.26 起
 /// legacy shutdown 残留「无 status + 全体 agents 处于终态」不再算 alive)。
@@ -263,6 +268,7 @@ pub fn team_state_candidates(state: &Value) -> Map<String, Value> {
     out
 }
 
+///
 /// 0.5.26 (`.team/artifacts/stale-team-saveconflict-locate.md` §7.1): 唯一 alive
 /// 谓词。规则:
 /// - 非 object → 排除;
@@ -348,8 +354,9 @@ pub(crate) fn agent_status_is_terminal(status: &str) -> bool {
     )
 }
 
+///
 /// `format_team_candidates`(`state.py:148`):候选摘要串(key 排序;agents 排序逗号连,空→`-`)。
-pub fn format_team_candidates(team_states: &Map<String, Value>) -> String {
+fn format_team_candidates(team_states: &Map<String, Value>) -> String {
     if team_states.is_empty() {
         return "No team state was found.".to_string();
     }
@@ -412,6 +419,7 @@ fn valid_owner_pane_id(pane_id: &str) -> bool {
     pane_id.starts_with('%') || pane_id.chars().all(|ch| ch.is_ascii_digit())
 }
 
+///
 /// `_project_top_level_view`(`state.py:167`,C8):把 `teams[team_key]` 投影成扁平顶层视图。
 pub fn project_top_level_view(state: &Value, team_key: &str) -> Value {
     // entry = _team_entry_from_state(...) or {} —— 空 dict 亦走 {} 分支(同内容)。
@@ -488,6 +496,7 @@ pub struct TeamScopeResolution {
     pub state: Value,
 }
 
+///
 /// Resolve a requested team selector once, returning both the canonical map key and its
 /// projected state. Callers must carry `canonical_team_key` forward rather than deriving team
 /// identity again from the projection or the original alias.
@@ -646,6 +655,7 @@ pub fn resolve_runtime_team_scope(
     ))
 }
 
+///
 /// `select_runtime_state`(`state.py:193`):compatibility projection wrapper.
 pub fn select_runtime_state(workspace: &Path, team: Option<&str>) -> Result<Value, StateError> {
     resolve_runtime_team_scope(workspace, team).map(|resolved| resolved.state)
@@ -677,8 +687,9 @@ fn team_selector_matches(team: &str, key: &str, value: &Value) -> bool {
         .is_some_and(|name| team == name)
 }
 
+///
 /// `ambiguous_team_target_result`(`state.py:226`):无显式 team 且多候选 → 拒绝 dict;否则 None。
-pub fn ambiguous_team_target_result(state: &Value) -> Option<Value> {
+fn ambiguous_team_target_result(state: &Value) -> Option<Value> {
     let alive = team_state_candidates(state);
     let active = state
         .get("active_team_key")
@@ -704,6 +715,7 @@ pub fn ambiguous_team_target_result(state: &Value) -> Option<Value> {
     }))
 }
 
+///
 /// `resolve_team_scoped_state`(`state.py:243`):返回 `(state, refusal)`,二者恰一为 Some。
 /// `team=None` 且歧义 → refusal;否则 select,RuntimeError → `team_target_unresolved` refusal。
 pub fn resolve_team_scoped_state(
@@ -732,6 +744,7 @@ pub fn resolve_team_scoped_state(
     }
 }
 
+///
 /// `save_team_scoped_state`(`state.py:594`):把 team-scoped(投影后)state 写回 workspace,**保全**
 /// 多 team workspace 里其他 team 的持久态。单 team(磁盘无 `teams` 且 primary key == target)退化为
 /// 纯 `save_runtime_state`(字节等价);多 team 时把本 team 落到 `teams[target_key]=compact(...)`,顶层

package/crates/team-agent/src/state/repository/intent.rs

@@ -1,3 +1,4 @@
+
 use super::StateWriteIntent;
 
 impl<'a> StateWriteIntent<'a> {

package/crates/team-agent/src/state/repository/tests.rs

@@ -1,3 +1,4 @@
+
 use super::{reapply_scope, ReapplyScope, StateWriteIntent};
 
 #[test]

package/crates/team-agent/src/state/repository.rs

@@ -1,3 +1,4 @@
+//!
 //! StateRepository facade.
 //!
 //! Ref:
@@ -73,16 +74,19 @@ pub struct StateRepository<'a> {
 }
 
 impl<'a> StateRepository<'a> {
+    ///
     /// Construct a repository bound to a workspace root.
     pub fn new(workspace: &'a Path) -> Self {
         Self { workspace }
     }
 
+    ///
     /// Load the raw workspace state document.
     pub fn load_workspace(&self) -> Result<Value, StateError> {
         helper_load_workspace(self.workspace)
     }
 
+    ///
     /// Load the canonical workspace document without running read-time
     /// migrations. `None` preserves the legacy raw-reader distinction between
     /// a missing file and a present empty/default document.
@@ -96,6 +100,7 @@ impl<'a> StateRepository<'a> {
         serde_json::from_str(&text).map(Some).map_err(StateError::from)
     }
 
+    ///
     /// Resolve a team-scoped projection using the existing projection selector.
     /// `team_key = None` selects the ambient team the same way as pre-S1a.
     pub fn load_team(&self, team_key: Option<&str>) -> Result<Value, StateError> {
@@ -110,6 +115,7 @@ impl<'a> StateRepository<'a> {
         })
     }
 
+    ///
     /// Persist `state` under the supplied intent. S1a dispatch is a pure
     /// forward call to the same legacy helper family that the caller used
     /// before S1a; the intent selects the family, not the merge semantics.
@@ -117,6 +123,7 @@ impl<'a> StateRepository<'a> {
         route_direct(self.workspace, intent, state)
     }
 
+    ///
     /// Persist `state` and let `reapply` re-materialize the write on
     /// SaveConflict, matching the pre-S1a `_reapplying_after_conflict` helper
     /// behavior for reapply-shaped intents.

package/crates/team-agent/src/state/selector.rs

@@ -1,3 +1,4 @@
+//!
 //! Active team workspace selector.
 
 use std::path::{Path, PathBuf};

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

@@ -146,6 +146,45 @@ fn backend_with_stdin(
     )
 }
 
+#[test]
+fn a21_spawn_command_too_long_is_structured_before_transport() {
+    let (backend, recorded) = backend_with(MockResp::Out(ok("%0\n")), Vec::new());
+    let session = SessionName::new("a21-session");
+    let window = WindowName::new("worker-long-role");
+    let argv = vec!["codex".to_string(), "x".repeat(20_000)];
+
+    let error = backend
+        .spawn_first(
+            &session,
+            &window,
+            &argv,
+            Path::new("/tmp/a21-workspace"),
+            &BTreeMap::new(),
+        )
+        .expect_err("oversized spawn must fail before tmux transport");
+    let text = error.to_string();
+    assert!(
+        text.contains("command_too_long"),
+        "structured error: {text}"
+    );
+    assert!(
+        text.contains("worker-long-role"),
+        "seat must be named: {text}"
+    );
+    assert!(
+        text.contains("actual_bytes="),
+        "actual length must be visible: {text}"
+    );
+    assert!(
+        text.contains("limit_bytes="),
+        "limit must be visible: {text}"
+    );
+    assert!(
+        recorded.lock().unwrap().is_empty(),
+        "tmux must not be called: {text}"
+    );
+}
+
 fn svec(items: &[&str]) -> Vec<String> {
     items.iter().map(|s| (*s).to_string()).collect()
 }

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

@@ -1,3 +1,4 @@
+//!
 //! Concrete tmux `Transport` backend (SKELETON) — the real executor that runs `tmux <argv>`.
 //!
 //! step 9 shipped the [`crate::transport::Transport`] trait + the pure tmux argv-builders
@@ -77,6 +78,11 @@ const COMMAND_TIMEOUT: Duration = Duration::from_secs(5);
 const SPAWN_IDENTITY_TIMEOUT: Duration = Duration::from_millis(500);
 const SPAWN_IDENTITY_POLL_INTERVAL: Duration = Duration::from_millis(25);
 
+/// Keep the final tmux argv below the ~16 KiB command envelope observed on macOS.
+/// This is checked after shell quoting and socket arguments are applied, before
+/// the external tmux process is called.
+pub const TMUX_SPAWN_COMMAND_LIMIT_BYTES: usize = 16_000;
+
 impl CommandRunner for RealCommandRunner {
     fn run(&self, argv: &[String]) -> Result<CommandOutput, std::io::Error> {
         self.run_inner(argv, None)
@@ -390,6 +396,27 @@ impl TmuxBackend {
         if self.socket.is_none() {
             return;
         }
+        // A server-level kill is only safe after the caller has removed every
+        // resource it owns.  A non-empty server may carry a pre-existing team
+        // (or a leader owned by another launcher), so fail closed instead of
+        // turning an endpoint cleanup into a shared-server teardown.  An
+        // inconclusive probe is also not proof of ownership.
+        let server_is_empty = match self.list_targets() {
+            Ok(targets) => targets.is_empty(),
+            Err(_) => false,
+        };
+        if !server_is_empty {
+            if let Some(workspace) = &self.event_workspace {
+                let _ = crate::event_log::EventLog::new(workspace).write(
+                    "tmux.kill_server_skipped_nonempty_or_unknown",
+                    serde_json::json!({
+                        "reason": "server_ownership_not_proven",
+                        "endpoint": self.tmux_endpoint(),
+                    }),
+                );
+            }
+            return;
+        }
         let argv = self.tmux_argv(&["tmux".to_string(), "kill-server".to_string()]);
         let _ = self.runner.run(&argv);
     }
@@ -787,6 +814,16 @@ impl TmuxBackend {
         first: bool,
     ) -> Result<SpawnResult, TransportError> {
         let spawn_argv = tmux_spawn_argv(session, window, command, first);
+        self.validate_spawn_command(
+            &spawn_argv,
+            if first {
+                "tmux.new-session"
+            } else {
+                "tmux.new-window"
+            },
+            session,
+            window,
+        )?;
         let output = self.run_spawn(&spawn_argv)?;
         let pane = output.stdout.trim();
         if pane.is_empty() {
@@ -897,6 +934,7 @@ impl TmuxBackend {
             "-lc".to_string(),
             command,
         ];
+        self.validate_spawn_command(&split_argv, "tmux.split-window", session, window)?;
         let output = self.run_spawn(&split_argv)?;
         let pane = output.stdout.trim();
         if pane.is_empty() {
@@ -932,6 +970,31 @@ impl TmuxBackend {
         }
     }
 
+    fn validate_spawn_command(
+        &self,
+        argv: &[String],
+        segment: &str,
+        session: &SessionName,
+        window: &WindowName,
+    ) -> Result<(), TransportError> {
+        let final_argv = self.tmux_argv(argv);
+        let actual_bytes = final_argv
+            .iter()
+            .map(|arg| arg.len().saturating_add(1))
+            .sum::<usize>();
+        if actual_bytes > TMUX_SPAWN_COMMAND_LIMIT_BYTES {
+            return Err(TransportError::CommandTooLong {
+                backend: BackendKind::Tmux,
+                segment: segment.to_string(),
+                session: session.as_str().to_string(),
+                window: window.as_str().to_string(),
+                actual_bytes,
+                limit_bytes: TMUX_SPAWN_COMMAND_LIMIT_BYTES,
+            });
+        }
+        Ok(())
+    }
+
     fn run_spawn(&self, argv: &[String]) -> Result<CommandOutput, TransportError> {
         let argv = self.tmux_argv(argv);
         let output = self

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

@@ -399,6 +399,9 @@ fn append_worker_pane_binding_issues(
     let Some(agents) = state.get("agents").and_then(Value::as_object) else {
         return;
     };
+    if agents.is_empty() {
+        return;
+    }
     let Ok(live_targets) = backend.list_targets() else {
         return;
     };

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

@@ -1,3 +1,4 @@
+//!
 //! step 9 · transport — 控制面 trait + typed payload(ROUND-0 SKELETON).
 //!
 //! 设计真相源:`docs/phase0/transport-backend-design.md` §1(Rust 草图:Target /
@@ -486,6 +487,20 @@ pub enum TransportError {
         code: Option<i32>,
         stderr: String,
     },
+    /// The final tmux spawn argv is too large for the transport command envelope.
+    /// Keep this separate from `Subprocess` so callers do not have to parse a
+    /// provider-sized argv dump to learn the actionable limit.
+    #[error(
+        "command_too_long: backend={backend:?}; segment={segment}; session={session}; window={window}; actual_bytes={actual_bytes}; limit_bytes={limit_bytes}"
+    )]
+    CommandTooLong {
+        backend: BackendKind,
+        segment: String,
+        session: String,
+        window: String,
+        actual_bytes: usize,
+        limit_bytes: usize,
+    },
     /// wezterm mux 连不上 / tmux server 不在。
     #[error("mux unavailable on {backend:?}: {detail}")]
     MuxUnavailable {

package/package.json

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