@team-agent/installer 0.5.61 → 0.5.63

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.
@@ -212,14 +219,6 @@ pub enum StateWriteIntent<'a> {
     CoordinatorConptyShim {
         team_key: Option<&'a str>,
     },
-    /// 0.5.36 (`.team/artifacts/supermarket-api-error-recovery-locate.md` §7.3):
-    /// post-save recovery step writes back the recovery intent outcome
-    /// (attempts / status / last_error / blocked_reason). Distinct intent
-    /// so future S1b migration can route it deliberately.
-    CoordinatorApiErrorRecovery {
-        team_key: Option<&'a str>,
-        agent_id: Option<&'a str>,
-    },
     McpAssignTask {
         team_key: Option<&'a str>,
         task_id: &'a str,
@@ -399,11 +398,6 @@ fn route_direct(
         // CoordinatorConptyShim -> root save
         // (coordinator/conpty_shim.rs:426/674).
         StateWriteIntent::CoordinatorConptyShim { .. } => helper_write_root(workspace, state),
-        // 0.5.36 CoordinatorApiErrorRecovery -> root save. The recovery
-        // intent lives under `coordinator.abnormal_api_error_recovery`, a
-        // root-scoped bookkeeping namespace that must survive across team
-        // boundaries; use the same helper family as CoordinatorConptyShim.
-        StateWriteIntent::CoordinatorApiErrorRecovery { .. } => helper_write_root(workspace, state),
         // McpAssignTask uses the reapply variant today; direct save routes
         // to the root helper for parity.
         StateWriteIntent::McpAssignTask { .. } => helper_write_root(workspace, state),

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/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.61",
+  "version": "0.5.63",
   "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.61",
-    "@team-agent/cli-darwin-x64": "0.5.61",
-    "@team-agent/cli-linux-x64": "0.5.61"
+    "@team-agent/cli-darwin-arm64": "0.5.63",
+    "@team-agent/cli-darwin-x64": "0.5.63",
+    "@team-agent/cli-linux-x64": "0.5.63"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

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

@@ -1,33 +0,0 @@
-//! leader::inject — `push_idle_reminder` no-op shim.
-//!
-//! #236 nag_removal (N35): the framework no longer auto-pings the leader pane based on
-//! idle-classification inferences. `push_idle_reminder` used to emit the
-//! `idle_takeover.reminder` event AND route a "leader takeover may be appropriate"
-//! message through the N31/N32 funnel; both were nag outputs synthesized from
-//! time/state, not from a real delivery obligation. They are deleted by design —
-//! ownership / handover changes only via explicit `claim-leader` / `takeover` commands.
-//!
-//! The function signature is preserved (callers in coordinator/tick.rs and lifecycle
-//! tests still resolve) but the body is a strict no-op: no event, no primitive call,
-//! no state mutation. The `_` discards keep clippy quiet and document that the
-//! arguments are intentionally ignored under N35.
-
-use std::path::Path;
-
-use serde_json::Value;
-
-use super::{LeaderError, TakeoverReminderResult};
-
-/// #236 nag_removal: was the take-over reminder injector; now a true no-op. Delivery
-/// primitives (`report_result` / `send_to_leader` / N31/N32 funnel / `request_human` /
-/// broadcast-leader) continue to flow through their own callsites — only the
-/// time/state-inferred nag output that lived in this helper is gone.
-pub fn push_idle_reminder(
-    workspace: &Path,
-    state: &Value,
-    event_log: &crate::event_log::EventLog,
-    result: &TakeoverReminderResult,
-) -> Result<(), LeaderError> {
-    let _ = (workspace, state, event_log, result);
-    Ok(())
-}

package/crates/team-agent/src/provider/command.rs

@@ -1,80 +0,0 @@
-//! unit-7 (Stage 3) — provider command-assembly boundary.
-//!
-//! The provider/adapter.rs monolith mixes three concerns:
-//!   1. The `ProviderAdapter` TRAIT and facade dispatch (the public API).
-//!   2. Per-provider COMMAND ASSEMBLY (argv plan, base/resume flags,
-//!      --session-id injection — adapter.rs:409-508 region).
-//!   3. SESSION SCANNING (capture polling + transcript scanning —
-//!      adapter.rs:511-546, 969-1078).
-//!
-//! This module CREATES the dedicated home for #2 so future work can
-//! migrate command-assembly fns here in small, behavior-neutral commits.
-//! Today it only carries the documented intent and a small typed helper —
-//! the bulk of the assembly fns are still in adapter.rs and reachable
-//! through the existing pub(crate) surface.
-//!
-//! Why incremental: every command-assembly fn touches multiple internal
-//! constants (`--session-id`, `--resume`, MCP-config-path conventions) and
-//! per-provider quirks. Moving them blindly is high-risk. The boundary
-//! exists so the next commit (or any contributor) has a documented target
-//! for relocations.
-
-use crate::provider::Provider;
-
-/// Lightweight tag for command-plan branches in the existing adapter
-/// (`Base` vs `Resume`). Distinct type so command-assembly code reads
-/// clearly even when it lives next to adapter dispatch.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum CommandPlanKind {
-    /// Initial spawn — `--session-id <uuid>` predetermined.
-    Base,
-    /// Resume an existing session — `--resume <sid>`, no fresh
-    /// `--session-id` injected.
-    Resume,
-}
-
-/// Returns true when the provider's command plan honors `--session-id`
-/// for fresh spawns. Mirrors the existing adapter logic but lives next to
-/// where future command-assembly fns will land.
-pub fn honors_session_id_for_base_spawn(provider: Provider) -> bool {
-    matches!(
-        provider,
-        Provider::Claude | Provider::ClaudeCode | Provider::Copilot
-    )
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn fake_provider_does_not_honor_session_id() {
-        assert!(!honors_session_id_for_base_spawn(Provider::Fake));
-    }
-
-    #[test]
-    fn provider_matrix_for_base_spawn_session_id_support() {
-        let cases = [
-            (Provider::Claude, true),
-            (Provider::ClaudeCode, true),
-            (Provider::Copilot, true),
-            (Provider::Codex, false),
-            (Provider::GeminiCli, false),
-            (Provider::Fake, false),
-        ];
-        for (provider, expected) in cases {
-            assert_eq!(
-                honors_session_id_for_base_spawn(provider),
-                expected,
-                "{provider:?}"
-            );
-        }
-    }
-
-    #[test]
-    fn command_plan_kind_is_copy() {
-        let a = CommandPlanKind::Base;
-        let b = a;
-        assert_eq!(a, b);
-    }
-}