@team-agent/installer 0.5.105 → 0.5.107

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

@@ -74,6 +74,7 @@ use crate::transport::{
 };
 
 pub const PANE_BINDING_NONCE_METADATA_KEY: &str = "TEAM_AGENT_PANE_BINDING_NONCE";
+pub(crate) const KEEPALIVE_WINDOW_NAME: &str = "[team-agent keepalive]";
 const TMUX_PANE_BINDING_NONCE_OPTION: &str = "@team_agent_pane_binding_nonce";
 const TMUX_SESSION_OWNER_WORKSPACE_OPTION: &str = "@team_agent_owner_workspace";
 const TMUX_SESSION_OWNER_TEAM_OPTION: &str = "@team_agent_owner_team";
@@ -3875,6 +3876,26 @@ impl Transport for TmuxBackend {
         Ok(output.stdout.trim().parse::<u8>().ok())
     }
 
+    fn pane_is_dead(&self, pane: &PaneId) -> Result<Option<bool>, TransportError> {
+        let argv = self.tmux_argv(&[
+            "tmux".to_string(),
+            "display-message".to_string(),
+            "-p".to_string(),
+            "-t".to_string(),
+            pane.as_str().to_string(),
+            "#{pane_dead}".to_string(),
+        ]);
+        let output = self.runner.run(&argv)?;
+        if !output.success {
+            return Ok(None);
+        }
+        Ok(match output.stdout.trim() {
+            "1" => Some(true),
+            "0" => Some(false),
+            _ => None,
+        })
+    }
+
     fn liveness(&self, pane: &PaneId) -> Result<PaneLiveness, TransportError> {
         let argv = self.tmux_argv(&[
             "tmux".to_string(),
@@ -4087,6 +4108,95 @@ impl Transport for TmuxBackend {
         self.run_ok(&argv)
     }
 
+    fn preserve_session_before_stop(
+        &self,
+        session: &SessionName,
+        targets: &[Target],
+    ) -> Result<(), TransportError> {
+        let list_argv = self.tmux_argv(&[
+            "tmux".to_string(),
+            "list-panes".to_string(),
+            "-s".to_string(),
+            "-t".to_string(),
+            format!("={}", session.as_str()),
+            "-F".to_string(),
+            "#{pane_id}\t#{window_name}".to_string(),
+        ]);
+        let output = self.runner.run(&list_argv)?;
+        if !output.success {
+            return Err(subprocess_error(list_argv, output));
+        }
+        for line in output.stdout.lines() {
+            let Some((pane, window)) = line.split_once('\t') else {
+                return Err(TransportError::Subprocess {
+                    argv: list_argv,
+                    code: output.code,
+                    stderr: "tmux returned an invalid session pane listing".to_string(),
+                });
+            };
+            if !targets.iter().any(|target| match target {
+                Target::Pane(id) => id.as_str() == pane,
+                Target::SessionWindow {
+                    session: owner,
+                    window: name,
+                } => owner == session && name.as_str() == window,
+            }) {
+                return Ok(());
+            }
+        }
+        // An empty listing cannot prove that this is the last worker.
+        if output.stdout.trim().is_empty() {
+            return Err(TransportError::TargetNotFound {
+                target: session.as_str().to_string(),
+            });
+        }
+        // Use a separate, non-worker window: remain-on-exit does not protect a
+        // pane explicitly deleted by kill-pane. Configure by the new pane ID,
+        // not a window name that could resolve to another same-named window.
+        let spawn_argv = tmux_spawn_argv(
+            &SessionName::new(format!("={}", session.as_str())),
+            &WindowName::new(KEEPALIVE_WINDOW_NAME),
+            "exec sleep 86400",
+            false,
+        );
+        let spawned = self.run_spawn(&spawn_argv)?;
+        let pane = spawned.stdout.trim();
+        if !pane.starts_with('%')
+            || pane.len() == 1
+            || !pane[1..].chars().all(|ch| ch.is_ascii_digit())
+        {
+            return Err(TransportError::Subprocess {
+                argv: self.tmux_argv(&spawn_argv),
+                code: spawned.code,
+                stderr: "tmux keepalive spawn returned no valid pane id".to_string(),
+            });
+        }
+        let result = self
+            .run_ok(&[
+                "tmux".to_string(),
+                "set-window-option".to_string(),
+                "-t".to_string(),
+                pane.to_string(),
+                "remain-on-exit".to_string(),
+                "on".to_string(),
+            ])
+            .and_then(|()| {
+                self.run_ok(&[
+                    "tmux".to_string(),
+                    "respawn-pane".to_string(),
+                    "-k".to_string(),
+                    "-t".to_string(),
+                    pane.to_string(),
+                    "exit 0".to_string(),
+                ])
+            });
+        if result.is_err() {
+            // The worker has not been killed yet; remove only our new anchor.
+            let _ = self.kill_pane(&PaneId::new(pane));
+        }
+        result
+    }
+
     fn kill_server(&self) -> Result<(), TransportError> {
         TmuxBackend::kill_server(self);
         Ok(())

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

@@ -29,6 +29,7 @@ struct OfflineState {
     target_snapshots: VecDeque<Vec<PaneInfo>>,
     windows: Vec<WindowName>,
     pane_presence: BTreeMap<String, bool>,
+    dead_panes: BTreeMap<String, bool>,
     spawn_failures: BTreeMap<String, String>,
     spawned_panes_addressable: bool,
     liveness: BTreeMap<String, PaneLiveness>,
@@ -67,6 +68,7 @@ impl Default for OfflineState {
             target_snapshots: VecDeque::new(),
             windows: Vec::new(),
             pane_presence: BTreeMap::new(),
+            dead_panes: BTreeMap::new(),
             spawn_failures: BTreeMap::new(),
             spawned_panes_addressable: true,
             liveness: BTreeMap::new(),
@@ -144,6 +146,13 @@ impl OfflineTransport {
         self
     }
 
+    pub fn with_pane_dead(self, pane: impl Into<String>, dead: bool) -> Self {
+        self.with_state(|state| {
+            state.dead_panes.insert(pane.into(), dead);
+        });
+        self
+    }
+
     pub fn with_spawn_failure(self, window: impl Into<String>, error: impl Into<String>) -> Self {
         self.with_state(|state| {
             state.spawn_failures.insert(window.into(), error.into());
@@ -523,6 +532,13 @@ impl Transport for OfflineTransport {
         Ok(self.with_state(|state| state.pane_current_commands.get(&pane_id).cloned()))
     }
 
+    fn pane_is_dead(&self, pane: &PaneId) -> Result<Option<bool>, TransportError> {
+        Ok(self.with_state(|state| {
+            state.calls.push("pane_is_dead");
+            state.dead_panes.get(pane.as_str()).copied()
+        }))
+    }
+
     fn liveness(&self, pane: &PaneId) -> Result<PaneLiveness, TransportError> {
         Ok(self.with_state(|state| {
             state.calls.push("liveness");
@@ -582,6 +598,25 @@ impl Transport for OfflineTransport {
         Ok(self.with_state(|state| state.session_owner.clone()))
     }
 
+    fn set_session_owner_with_generation(
+        &self,
+        _session: &SessionName,
+        workspace: &Path,
+        team: &str,
+        generation: &str,
+    ) -> Result<(), TransportError> {
+        self.with_state(|state| {
+            state.calls.push("set_session_owner_with_generation");
+            state.session_owner = Some(super::SessionOwner {
+                workspace: workspace.canonicalize().unwrap_or_else(|_| workspace.to_path_buf())
+                    .to_string_lossy().to_string(),
+                team: team.to_string(),
+                generation: generation.to_string(),
+            });
+        });
+        Ok(())
+    }
+
     fn list_windows(&self, _session: &SessionName) -> Result<Vec<WindowName>, TransportError> {
         Ok(self.with_state(|state| {
             state.calls.push("list_windows");

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

@@ -195,32 +195,6 @@ fn session_window_name_transparent_bytes() {
 // contracts-rust-native §2: spawn 返回的稳定 Target,后续 inject/capture 命中同进程。
 // ════════════════════════════════════════════════════════════════════════
 
-#[test]
-fn target_pane_and_session_window_are_distinct_addressings() {
-    // 两种合法寻址不可混传;同名 PaneId vs SessionWindow 不相等。
-    let p = Target::Pane(PaneId::new("%7"));
-    let sw = Target::SessionWindow {
-        session: SessionName::new("team-sess"),
-        window: WindowName::new("%7"),
-    };
-    assert_ne!(p, sw);
-    // Pane 寻址按 PaneId 字节相等。
-    assert_eq!(
-        Target::Pane(PaneId::new("%7")),
-        Target::Pane(PaneId::new("%7"))
-    );
-    // SessionWindow 按 (session,window) 对相等;任一不同即不等。
-    let a = Target::SessionWindow {
-        session: SessionName::new("s"),
-        window: WindowName::new("w"),
-    };
-    let b = Target::SessionWindow {
-        session: SessionName::new("s"),
-        window: WindowName::new("w2"),
-    };
-    assert_ne!(a, b);
-}
-
 #[test]
 fn spawn_first_returns_stable_addressable_target_then_reachable() {
     // contracts-rust-native: spawn_first 返回稳定可寻址 Target,且交回的 pane_id 能
@@ -331,16 +305,6 @@ fn spawn_into_then_list_targets_enumerates_it() {
 // 会卡 trust prompt)。golden /tmp/transport_golden.py: empty_inject_*。
 // ════════════════════════════════════════════════════════════════════════
 
-#[test]
-fn inject_payload_empty_is_typed_distinct_from_empty_text() {
-    // 类型上把空文本与含字符文本分流(InjectPayload::Empty != Text("..."))。
-    assert_ne!(InjectPayload::Empty, InjectPayload::Text(String::new()));
-    assert_eq!(
-        InjectPayload::Text("hi".into()),
-        InjectPayload::Text("hi".into())
-    );
-}
-
 #[test]
 fn inject_empty_payload_reports_empty_text_send_keys_and_turn_not_required() {
     // golden empty_inject_report:
@@ -366,16 +330,45 @@ fn inject_empty_payload_reports_empty_text_send_keys_and_turn_not_required() {
     assert_eq!(report.attempts, 1);
 }
 
+#[cfg(unix)]
+#[test]
+#[ignore = "requires native tmux 3.5+ and python3; owns an isolated socket/session"]
+fn submit_key_protocol_native_tmux_is_return_in_legacy_and_extended_modes() {
+    let fixture = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/submit_key_protocol_probe.py");
+    let output = std::process::Command::new("python3")
+        .arg(fixture)
+        .args([
+            "--submit-key",
+            crate::transport::tmux_submit_key_name(Key::Enter),
+        ])
+        .output()
+        .expect("run isolated raw-PTY submit diagnostic");
+    assert!(
+        output.status.success(),
+        "production submit key is not Return: stdout={} stderr={}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr),
+    );
+    assert!(String::from_utf8_lossy(&output.stdout)
+        .contains("ProductionSubmitReturn=verified-three-modes"));
+}
+
 #[test]
 fn empty_inject_is_single_direct_send_keys_never_buffer() {
     // 命令构造 golden(STEP-9):空文本禁走 buffer,只发一条 send-keys 提交键
     // (tmux_io.py:42 —— tmux 拒空 buffer 会卡 trust prompt)。
-    // golden empty_inject_calls 仅 1 条:send-keys -t %7 C-m（锁定阳性 CR）。
+    // Return 与 Ctrl-M 只在 legacy 模式等价；提交必须保持逻辑 Enter。
     assert_eq!(
         tmux_empty_inject_argv(&PaneId::new("%7"), Key::Enter),
-        vec!["tmux", "send-keys", "-t", "%7", "C-m"]
+        vec!["tmux", "send-keys", "-t", "%7", "Enter"]
     );
-    assert_eq!(crate::transport::tmux_submit_key_name(Key::Enter), "C-m");
+    assert_eq!(
+        crate::transport::tmux_send_submit_argv(&PaneId::new("%7"), Key::Enter),
+        vec!["tmux", "send-keys", "-t", "%7", "Enter"]
+    );
+    assert_eq!(crate::transport::tmux_submit_key_name(Key::Enter), "Enter");
+    assert_eq!(crate::transport::tmux_submit_key_name(Key::Down), "Down");
 }
 
 #[test]
@@ -479,18 +472,6 @@ fn p2_inject_large_text_switches_to_load_buffer_stdin_at_16k() {
 // contracts-rust-native test_key_enum_translation_parity / cancel_mode_noop。
 // ════════════════════════════════════════════════════════════════════════
 
-#[test]
-fn key_enum_variants_are_distinct_and_copy() {
-    // Enter/Up/Down/Left/Right/Char/CtrlC/CancelMode 互不相等;Char 携字符。
-    assert_ne!(Key::Enter, Key::CtrlC);
-    assert_ne!(Key::Up, Key::Down);
-    assert_ne!(Key::Char('1'), Key::Char('2'));
-    assert_eq!(Key::Char('3'), Key::Char('3'));
-    // Copy:可按值传两次。
-    let k = Key::Enter;
-    let _ = (k, k);
-}
-
 #[test]
 fn send_keys_sequence_routes_through_transport() {
     // send_keys 接受 &[Key];RED via stub。
@@ -552,13 +533,6 @@ fn cancel_mode_is_noop_on_non_tmux_backends() {
 // tmux `-S -<N>`(Tail)/ `-S -`(Full);DELIVERY_CAPTURE_LINES=40 是默认 tail。
 // ════════════════════════════════════════════════════════════════════════
 
-#[test]
-fn capture_range_tail_and_full_distinct() {
-    assert_ne!(CaptureRange::Tail(40), CaptureRange::Full);
-    assert_ne!(CaptureRange::Tail(40), CaptureRange::Tail(30));
-    assert_eq!(CaptureRange::Tail(40), CaptureRange::Tail(40));
-}
-
 #[test]
 fn capture_tail_records_range_in_captured_text() {
     // CapturedText 携带它抓取的 range + 出口规范化文本。

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

@@ -13,7 +13,7 @@
 //!     - name: tmux_inject_text_argv
 //!       what: 文本注入三步 argv(装 buffer→paste→删 buffer)的唯一构造点
 //!     - name: tmux_send_submit_argv
-//!       what: 提交键 argv 的唯一构造点,Enter 锁定为 C-m
+//!       what: 提交键 argv 的唯一构造点,Enter 保持逻辑 Return 而非 Ctrl-M
 //!     - name: tmux_capture_argv
 //!       what: capture-pane argv 的唯一构造点
 //!     - name: tmux_query_argv
@@ -994,6 +994,12 @@ pub trait Transport: Send + Sync {
         Ok(None)
     }
 
+    /// Native dead-pane observation. Only Some(true) proves no live pane
+    /// process; a missing/unsupported sample must remain unknown.
+    fn pane_is_dead(&self, _pane: &PaneId) -> Result<Option<bool>, TransportError> {
+        Ok(None)
+    }
+
     /// Cheap direct pane existence check when a backend can prove it. `Ok(None)`
     /// preserves the existing Unknown boundary.
     fn has_pane(&self, pane: &PaneId) -> Result<Option<bool>, TransportError> {
@@ -1085,6 +1091,17 @@ pub trait Transport: Send + Sync {
 
     // —— LIFECYCLE(SL)——
 
+    /// Before stopping a seat, preserve its session if removing these targets
+    /// would otherwise destroy it. This is not called by team shutdown/restart.
+    /// Backends whose sessions outlive their panes need no special handling.
+    fn preserve_session_before_stop(
+        &self,
+        _session: &SessionName,
+        _targets: &[Target],
+    ) -> Result<(), TransportError> {
+        Ok(())
+    }
+
     fn kill_server(&self) -> Result<(), TransportError> {
         Ok(())
     }
@@ -1199,21 +1216,18 @@ pub fn tmux_send_keys_argv(pane: &PaneId, keys: &[Key]) -> Vec<String> {
 
 /// 投递提交键的 tmux 拼写。
 ///
-/// ledger.p0enter 锁定对：`C-j`/LF 5/5 不成回合，`C-m`/CR 5/5 成回合。
-/// `send-keys Enter` 在 raw PTY 上也是 `0d`，但提交路径只发锁定阳性名
-/// `C-m`，避免落到 LF 族。菜单 `send_keys([Down, Enter])` 不走这里。
+/// `Enter` 必须保持逻辑 Return，不能替换成控制组合 `C-m`。
+/// legacy PTY 中两者都是 CR，但启用 extended keys 后 `C-m` 会成为
+/// CSI-u / modifyOtherKeys Ctrl-M，Pi 不把它当提交；`Enter` 仍发送 CR。
 /// ---
-/// purpose: 投递提交键的 tmux 拼写:Enter 锁定为 C-m(CR),其余键回落通用翻译
+/// purpose: 投递提交键复用通用逻辑键翻译,避免协议相关的控制键别名
 /// params:
-///   key: 提交键;只有 Enter 有专门拼写
-/// returns: 提交用键名;非 Enter 与 tmux_key_name 同值(含空串情形)
+///   key: 逻辑提交键
+/// returns: 与 tmux_key_name 同值(含空串情形)
 /// boundary: 只管拼写,不管何时提交、提交是否成功;不发送、不验证
 /// ---
 pub fn tmux_submit_key_name(key: Key) -> &'static str {
-    match key {
-        Key::Enter => "C-m",
-        other => tmux_key_name(other),
-    }
+    tmux_key_name(key)
 }
 
 /// 投递提交：`send-keys -t <pane> <submit-spelling>`。
@@ -1478,7 +1492,7 @@ pub fn tmux_inject_text_argv(
 
 /// 空文本 inject:纯 `send-keys -t <target> <submit_key>`,**禁** buffer 路径
 /// (tmux 拒空 buffer 会卡 trust prompt;tmux_io.py:42)。
-/// `Key::Enter` 在此译成锁定阳性 `C-m`，不是菜单用的 `Enter`。
+/// `Key::Enter` 保持逻辑 `Enter`，不会在 extended keys 下误发 Ctrl-M。
 /// ---
 /// purpose: 空载荷注入(唤醒/ping)的 argv:只发提交键,不碰 buffer
 /// params:

package/package.json

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

package/skills/team-agent/references/recovery-runbook.md

@@ -54,7 +54,7 @@ Diagnosis:
 
 ```bash
 team-agent status --workspace "$WORKSPACE" --json --detail
-team-agent collect --workspace "$WORKSPACE" --json
+team-agent inbox "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" -n 3 --json
 ```
 
 What to look for:
@@ -167,7 +167,7 @@ Validate:
 
 ```bash
 team-agent status --workspace "$WORKSPACE" --json --detail
-team-agent collect --workspace "$WORKSPACE" --json
+team-agent inbox "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" -n 3 --json
 ```
 
 The expected result is `status="restarted"` or an equivalent running projection without duplicate-session errors. Do not treat a partial failure on one worker as permission to reset the whole team.