@team-agent/installer 0.5.60 → 0.5.62

package/crates/team-agent/src/leader/tests/terminal_and_replay_vs_rerender_invariants_red.rs

@@ -0,0 +1,417 @@
+//! RED contract — 0.5.57 typed-state car · batch F
+//! Terminal-state immutability + framework-replay vs provider-re-render
+//! diagnostic separation.
+//!
+//! LINEAGE:
+//! - Baseline: 5b847e4 (0.5.56 tested tip).
+//! - Distillation §1.4 "两种历史消息重现必须分诊" and §3.3#5
+//!   "Submitted→Delivered 后任何 claim/attach/restart 都不可逆".
+//! - Storm remote-control export proved that `delivered` was never
+//!   re-injected (attempts / delivered_at unchanged); the provider
+//!   re-rendered the historical transcript on `codex resume`. Any
+//!   diagnostic that conflates the two will misattribute
+//!   provider-side redraw as a framework replay.
+//!
+//! TEETH (RED at 5b847e4):
+//!   1. `delivered_row_immutable_under_any_transition`
+//!      — a `delivered` row's `delivered_at`, `delivery_attempts`,
+//!      `status` and delivery token must be BYTE-STABLE across any
+//!      claim/attach/requeue call from the typed-state surface.
+//!      Baseline: passes (invariant lock) → green.
+//!   2. `acknowledged_row_immutable_under_generic_mark`
+//!      — an `acknowledged` row must not be overwritten by a generic
+//!      `store.mark` call that could regress it to a delivery status.
+//!      Baseline: distillation §1.2 acknowledged row notes "current
+//!      guard still allows other status to overwrite; typed car needs
+//!      to tighten." → red.
+//!   3. `consumed_row_immutable_under_any_transition`
+//!      — a `consumed` row must not re-enter any recovery arm.
+//!      Baseline: source scan — no explicit exclusion. → red.
+//!   4. `typed_event_carries_replay_vs_rerender_kind`
+//!      — the framework must emit a typed marker distinguishing
+//!      `framework_replay` (new attempt) from `provider_rerender`
+//!      (transcript redraw, no new attempt). Baseline: no such
+//!      marker; every `send.injected` looks the same regardless of
+//!      whether it is a fresh submit or a resume redraw. → red.
+//!   5. `restart_never_marks_delivered_as_accepted`
+//!      — a restart / resume path must not translate a re-rendered
+//!      transcript token into a new `messages.status = 'accepted'`
+//!      write for an already-`delivered` row. Baseline (invariant
+//!      lock, storm proved): green.
+//!
+//! POSITIVE CONTROL:
+//!   6. `delivered_to_acknowledged_transition_still_allowed` — the
+//!      legitimate business terminal transition (delivered →
+//!      acknowledged via the ack API) must remain functional.
+//!
+//! NEGATIVE CONTROL:
+//!   7. `stray_ack_call_does_not_promote_pending_row_to_acknowledged`
+//!      — a mis-scoped ack call must not skip a row's delivery lifecycle
+//!      and jump straight from `accepted` to `acknowledged`.
+//!
+//! FROZEN by verifier — do NOT modify without a new SHA256 signature.
+
+#![cfg(unix)]
+#![allow(clippy::expect_used, clippy::panic, clippy::unwrap_used)]
+
+use crate as team_agent;
+
+#[path = "rehomed_env.rs"]
+mod rehomed_env;
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use rusqlite::params;
+use serial_test::serial;
+use team_agent::event_log::EventLog;
+use team_agent::leader::{claim_lease_no_incident, LeaseStatus};
+use team_agent::message_store::MessageStore;
+use team_agent::messaging::enqueue_leader_mailbox_until_attach;
+use team_agent::messaging::watchers::requeue_after_claim_leader;
+use team_agent::model::enums::PaneLiveness;
+use team_agent::model::ids::TeamKey;
+use team_agent::state::owner_gate::PaneLivenessProbe;
+use team_agent::transport::PaneId;
+
+const TEAM: &str = "current";
+const PANE: &str = "%leader";
+
+struct LiveCaller;
+impl PaneLivenessProbe for LiveCaller {
+    fn liveness(&self, pane_id: &str) -> PaneLiveness {
+        if pane_id == PANE {
+            PaneLiveness::Live
+        } else {
+            PaneLiveness::Dead
+        }
+    }
+}
+
+fn bound_state() -> serde_json::Value {
+    serde_json::json!({
+        "session_name": "team-terminal-inv",
+        "team_owner": {
+            "pane_id": PANE, "provider": "codex", "owner_epoch": 7,
+            "claimed_at": "2026-07-24T00:00:00Z", "claimed_via": "claim-leader"
+        },
+        "leader_receiver": {
+            "pane_id": PANE, "provider": "codex", "owner_epoch": 7, "status": "attached"
+        }
+    })
+}
+
+struct TermCase {
+    _env: rehomed_env::RehomedTestEnv,
+    workspace: PathBuf,
+    store: MessageStore,
+    event_log: EventLog,
+}
+
+impl TermCase {
+    fn new(tag: &str) -> Self {
+        static N: AtomicU64 = AtomicU64::new(0);
+        let env = rehomed_env::RehomedTestEnv::enter(tag);
+        let workspace = env.workspace(&format!(
+            "057f-term-{tag}-{}",
+            N.fetch_add(1, Ordering::Relaxed)
+        ));
+        let store = MessageStore::open(&workspace).unwrap();
+        let event_log = EventLog::new(&workspace);
+        Self {
+            _env: env,
+            workspace,
+            store,
+            event_log,
+        }
+    }
+
+    fn seed(&self, content: &str, status: &str, delivered_at: Option<&str>) -> String {
+        let mid = enqueue_leader_mailbox_until_attach(
+            &self.workspace,
+            TEAM,
+            content,
+            None,
+            "leader",
+            &self.event_log,
+        )
+        .unwrap()
+        .message_id
+        .expect("mailbox enqueue");
+        let conn = team_agent::db::schema::open_db(self.store.db_path()).unwrap();
+        conn.execute(
+            "update messages set status = ?2, delivered_at = ?3, delivery_attempts = 1
+             where message_id = ?1",
+            params![mid, status, delivered_at],
+        )
+        .unwrap();
+        mid
+    }
+
+    fn full(&self, mid: &str) -> (String, Option<String>, i64) {
+        let conn = team_agent::db::schema::open_db(self.store.db_path()).unwrap();
+        conn.query_row(
+            "select status, delivered_at, delivery_attempts from messages where message_id = ?1",
+            params![mid],
+            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
+        )
+        .unwrap()
+    }
+
+    fn claim_and_requeue(&self) -> LeaseStatus {
+        let team = TeamKey::new(TEAM.to_string());
+        let pane = PaneId::new(PANE);
+        let mut state = bound_state();
+        let result = claim_lease_no_incident(
+            &self.workspace,
+            &mut state,
+            None,
+            &team,
+            &pane,
+            true,
+            &self.event_log,
+            &LiveCaller,
+        )
+        .unwrap();
+        if result.ok {
+            let _ = requeue_after_claim_leader(
+                &self.workspace,
+                &self.store,
+                &self.event_log,
+                &team,
+                result.bound_pane_id.as_ref().expect("pane"),
+                None,
+            )
+            .unwrap();
+        }
+        result.status
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 1 — delivered row is byte-stable across claim (invariant lock)
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn delivered_row_immutable_under_any_transition() {
+    let case = TermCase::new("delivered-lock");
+    let mid = case.seed(
+        "delivered canary",
+        "delivered",
+        Some("2026-07-21T12:00:00Z"),
+    );
+    let before = case.full(&mid);
+    let _ = case.claim_and_requeue();
+    let after = case.full(&mid);
+    assert_eq!(
+        before, after,
+        "delivered row must be byte-stable across any typed-state transition; \
+         a re-enqueue would create a second physical submit for a message the \
+         framework already saw succeed. §3.3#5 + storm proof."
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 2 — acknowledged row cannot be regressed by generic mark
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn acknowledged_row_immutable_under_generic_mark() {
+    let case = TermCase::new("ack-lock");
+    let mid = case.seed("acked canary", "acknowledged", Some("2026-07-21T12:00:00Z"));
+    let before = case.full(&mid);
+    // Baseline weakness (distillation §1.2 acknowledged note): a generic
+    // `store.mark(mid, "target_resolved", None)` currently succeeds and
+    // silently regresses the row. Typed refactor MUST make this a
+    // hard-refused transition (typed error).
+    let mark_result = case.store.mark(&mid, "target_resolved", None);
+    let after = case.full(&mid);
+    assert!(
+        mark_result.is_err() || after == before,
+        "acknowledged row was regressed by a generic mark call: before={:?} \
+         after={:?} mark_result={:?}. §1.2 requires terminal states to refuse \
+         any downgrade from a non-ack API; typed refactor must return a typed \
+         error rather than silently overwrite.",
+        before,
+        after,
+        mark_result
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 3 — consumed row is untouchable by any recovery arm
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn consumed_row_immutable_under_any_transition() {
+    let case = TermCase::new("consumed-lock");
+    let mid = case.seed("consumed canary", "consumed", None);
+    let before = case.full(&mid);
+    // A generic mark attempt should also refuse to regress a `consumed`
+    // row. Baseline: the same generic mark path applies, distillation
+    // §1.2 already flags this. Also verify claim/requeue does not touch
+    // it.
+    let mark_result = case.store.mark(&mid, "accepted", None);
+    let _ = case.claim_and_requeue();
+    let after = case.full(&mid);
+    assert!(
+        (mark_result.is_err() || after.0 == "consumed") && after.0 == "consumed",
+        "consumed row was affected: before={:?} after={:?} mark_result={:?}. \
+         §1.2 consumed is a terminal disposition; typed refactor must refuse \
+         any downgrade or requeue.",
+        before,
+        after,
+        mark_result
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 4 — typed event carries framework_replay vs provider_rerender kind
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn typed_event_carries_replay_vs_rerender_kind() {
+    // Source-shape probe: the delivery + acceptance event schemas must
+    // include a typed `redisplay_kind` (or equivalent) enum with at
+    // least the two values.
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let src = manifest.join("src");
+    let mut has_marker = false;
+    fn walk(dir: &std::path::Path, has_marker: &mut bool) {
+        let Ok(es) = std::fs::read_dir(dir) else {
+            return;
+        };
+        for e in es.flatten() {
+            let p = e.path();
+            if p.is_dir() {
+                walk(&p, has_marker);
+            } else if p.extension().and_then(|s| s.to_str()) == Some("rs") {
+                if let Ok(t) = std::fs::read_to_string(&p) {
+                    if (t.contains("framework_replay") && t.contains("provider_rerender"))
+                        || t.contains("RedisplayKind::FrameworkReplay")
+                        || t.contains("RedisplayKind::ProviderRerender")
+                    {
+                        *has_marker = true;
+                    }
+                }
+            }
+        }
+    }
+    walk(&src, &mut has_marker);
+    assert!(
+        has_marker,
+        "no typed redisplay-kind marker found (framework_replay / provider_rerender). \
+         §1.4 requires diagnostics to distinguish framework replay (new attempt) from \
+         provider re-render (transcript redraw, no new attempt). Baseline: every \
+         'send.injected' event looks identical."
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 5 — restart never marks delivered as accepted (invariant lock)
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn restart_never_marks_delivered_as_accepted() {
+    // Source-scan: no file may contain a SQL literal that translates a
+    // `delivered` row to `accepted`. We check for the substring
+    // `set status = 'accepted'` inside any block that also mentions
+    // `delivered`. This is a coarse guard; the more precise test lives
+    // in tooth 1 (behavioral). Both are cheap and complementary.
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let src = manifest.join("src");
+    let mut violations: Vec<PathBuf> = Vec::new();
+    fn walk(dir: &std::path::Path, out: &mut Vec<PathBuf>) {
+        let Ok(es) = std::fs::read_dir(dir) else {
+            return;
+        };
+        for e in es.flatten() {
+            let p = e.path();
+            if p.is_dir() {
+                if p.file_name().and_then(|s| s.to_str()) == Some("tests") {
+                    continue;
+                }
+                walk(&p, out);
+            } else if p.extension().and_then(|s| s.to_str()) == Some("rs") {
+                if let Ok(t) = std::fs::read_to_string(&p) {
+                    let lines: Vec<&str> = t.lines().collect();
+                    for (i, l) in lines.iter().enumerate() {
+                        if l.contains("set status = 'accepted'") {
+                            let start = i.saturating_sub(20);
+                            let end = (i + 20).min(lines.len());
+                            let window = lines[start..end].join("\n");
+                            // Trigger only if `delivered` (not
+                            // `delivered_at` alone) is treated as
+                            // eligible.
+                            if window.contains("status = 'delivered'")
+                                || window.contains("'delivered'")
+                            {
+                                out.push(p.clone());
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    walk(&src, &mut violations);
+    // 0.5.55 storm proved this invariant held (delivered was untouched).
+    // Green at baseline; locked here.
+    assert!(
+        violations.is_empty(),
+        "regression: SQL that flips a `delivered` row to `accepted` found: {:?}. \
+         §3.3#5 storm proof — delivered must be irreversibly terminal.",
+        violations
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 6 — positive control: delivered→acknowledged is still supported
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn delivered_to_acknowledged_transition_still_allowed() {
+    let case = TermCase::new("pos-ack");
+    let mid = case.seed("business ack", "delivered", Some("2026-07-24T00:01:00Z"));
+    // Business ack path: mark the row acknowledged via the store API.
+    let r = case.store.mark(&mid, "acknowledged", None);
+    let (status, _, _) = case.full(&mid);
+    assert!(
+        r.is_ok() && status == "acknowledged",
+        "delivered → acknowledged legitimate business transition must remain \
+         functional (mark_result={:?}, status={})",
+        r,
+        status
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tooth 7 — negative control: stray ack cannot leapfrog delivery
+// ---------------------------------------------------------------------------
+
+#[test]
+#[serial(env)]
+fn stray_ack_call_does_not_promote_pending_row_to_acknowledged() {
+    let case = TermCase::new("neg-stray-ack");
+    let mid = case.seed("pending row", "accepted", None);
+    let mark_result = case.store.mark(&mid, "acknowledged", None);
+    let (status, _, _) = case.full(&mid);
+    // Baseline weakness: generic mark permits a jump. Typed refactor
+    // must refuse. If mark succeeds today, this tooth is red; if it
+    // refuses, tooth stays green.
+    assert!(
+        mark_result.is_err() || status != "acknowledged",
+        "generic mark leap-frogged an accepted row directly to acknowledged \
+         (mark_result={:?}, status={}). §1.2 acknowledged transition must be \
+         enforced through the ack API's lifecycle guard, not permitted by \
+         any writer.",
+        mark_result,
+        status
+    );
+}

package/crates/team-agent/src/leader/tests/wake_start_owner.rs

@@ -1,94 +1,5 @@
 use super::*;
 
-// =====================================================================
-// 4. wake 层纯函数(unimplemented → RED)。golden:probe_leader.py 5 分支 + boundary。
-// =====================================================================
-
-#[test]
-fn should_reread_no_file_when_current_mtime_none() {
-    // current_mtime is None → {reread:false, no_file}(wake.py:31-32)。
-    let d = should_reread(None, None, None, 100.0, 60.0);
-    assert!(!d.reread);
-    assert_eq!(d.reason, RereadReason::NoFile);
-}
-
-#[test]
-fn should_reread_never_classified() {
-    // last_classified_mtime is None → {reread:true, never_classified}。
-    let d = should_reread(None, Some(10.0), None, 100.0, 60.0);
-    assert!(d.reread);
-    assert_eq!(d.reason, RereadReason::NeverClassified);
-}
-
-#[test]
-fn should_reread_file_changed() {
-    // current != last_classified → {reread:true, file_changed}。
-    let d = should_reread(Some(5.0), Some(20.0), Some(10.0), 100.0, 60.0);
-    assert!(d.reread);
-    assert_eq!(d.reason, RereadReason::FileChanged);
-}
-
-#[test]
-fn should_reread_quiescent_already_classified_at_and_past_debounce() {
-    // current==last_classified 且 silent_for >= debounce → quiescent(不再重读)。
-    // silent_for = max(0, now-current_mtime) = 100-10 = 90 >= 60。
-    let d = should_reread(Some(10.0), Some(10.0), Some(10.0), 100.0, 60.0);
-    assert!(!d.reread);
-    assert_eq!(d.reason, RereadReason::QuiescentAlreadyClassified);
-    // 边界:silent_for 恰 == debounce(now-current=60)→ 仍 quiescent(>= 比较)。
-    let b = should_reread(Some(40.0), Some(40.0), Some(40.0), 100.0, 60.0);
-    assert!(!b.reread);
-    assert_eq!(b.reason, RereadReason::QuiescentAlreadyClassified);
-}
-
-#[test]
-fn should_reread_unchanged_within_debounce() {
-    // current==last_classified 且 silent_for < debounce → unchanged。
-    // now-current = 100-95 = 5 < 60。注:last_mtime 在 Python body 中未被使用。
-    let d = should_reread(Some(10.0), Some(95.0), Some(95.0), 100.0, 60.0);
-    assert!(!d.reread);
-    assert_eq!(d.reason, RereadReason::Unchanged);
-}
-
-#[test]
-fn on_file_changed_adds_node_sorted_and_records_mtime() {
-    // golden probe_leader.py:add b → pending ["b"];add a → sorted ["a","b"]。
-    let s0 = on_file_changed(None, "b", 1.0);
-    assert_eq!(s0.pending, vec!["b".to_string()]);
-    assert_eq!(s0.mtimes.get("b"), Some(&1.0));
-    let s1 = on_file_changed(Some(&s0), "a", 2.0);
-    assert_eq!(
-        s1.pending,
-        vec!["a".to_string(), "b".to_string()],
-        "pending 必须 sorted"
-    );
-    assert_eq!(s1.mtimes.get("a"), Some(&2.0));
-    // 重复 add b:pending 仍是 set(不重复),mtime 被更新到 3.0。
-    let s2 = on_file_changed(Some(&s1), "b", 3.0);
-    assert_eq!(s2.pending, vec!["a".to_string(), "b".to_string()]);
-    assert_eq!(s2.mtimes.get("b"), Some(&3.0));
-}
-
-#[test]
-fn take_pending_drains_sorted_and_clears_pending_but_keeps_mtimes() {
-    // golden probe_leader.py:drain → (["a","b"], state{pending:[], mtimes 保留})。
-    let mut st = on_file_changed(None, "b", 3.0);
-    st = on_file_changed(Some(&st), "a", 2.0);
-    let (drained, after) = take_pending(Some(&st));
-    assert_eq!(drained, vec!["a".to_string(), "b".to_string()]);
-    assert!(after.pending.is_empty());
-    // mtimes 不被 drain 清空。
-    assert_eq!(after.mtimes.get("a"), Some(&2.0));
-    assert_eq!(after.mtimes.get("b"), Some(&3.0));
-    // 再 drain → 空。
-    let (drained2, _after2) = take_pending(Some(&after));
-    assert!(drained2.is_empty());
-    // drain None → ([], default state)。
-    let (none_drained, none_state) = take_pending(None);
-    assert!(none_drained.is_empty());
-    assert!(none_state.pending.is_empty());
-}
-
 // =====================================================================
 // 5. leader_session_name — sha1 派生 + 文件夹消毒(unimplemented → RED)
 // =====================================================================
@@ -194,28 +105,33 @@ fn owner_bind_refused_event_name_is_owner_bind_refused() {
     assert_eq!(LeaderEvent::OwnerBindRefused.name(), "owner.bind_refused");
 }
 
-// emit_owner_bound_event:成功绑定 hook(owner.bound_from_caller_pane;leader_binding.py:162-183)。
+// bind_owner_from_caller_pane:成功绑定后调用 owner.bound_from_caller_pane 审计 hook
+// (leader_binding.py:162-183)。
 // 强化(no-full-uuid-leak 命门):事件只写 derived_uuid_prefix == derived[:12](12 hex),
 // old uuid 为 None → old_uuid_prefix == ""(空串,非缺省);全 32 hex uuid 绝不出现在任何字段。
 // unimplemented → RED。
 #[test]
 fn emit_owner_bound_event_logs_prefix_only_never_full_uuid() {
+    let _lock = ENV_LOCK.lock().unwrap();
     let ws = std::env::temp_dir().join(format!("ta_rs_emit_{}", std::process::id()));
     std::fs::create_dir_all(&ws).unwrap();
-    let caller = PaneId::new("%7");
-    let derived = uuid("fp", "/ws", "u", "default");
-    let full = derived.as_str().to_string();
+    let _env = EnvGuard::apply(&[
+        ("TMUX_PANE", Some("%7")),
+        ("TEAM_AGENT_MACHINE_FINGERPRINT", Some("fp")),
+        ("TEAM_AGENT_LEADER_PROVIDER", Some("codex")),
+        ("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE", None),
+    ]);
+    let result = bind_owner_from_caller_pane(&ws, &TeamKey::new("default"), None).unwrap();
+    assert!(result.ok, "caller pane should produce an owner binding");
+    let owner = result.owner.as_ref().expect("successful bind has owner");
+    let full = owner
+        .leader_session_uuid
+        .as_ref()
+        .expect("successful bind has leader session uuid")
+        .as_str()
+        .to_string();
     assert_eq!(full.len(), 32, "derive 产 32 hex");
     let prefix12 = full[..12].to_string();
-    emit_owner_bound_event(
-        &ws,
-        &caller,
-        "codex",
-        &derived,
-        &TeamKey::new("default"),
-        None,
-    )
-    .unwrap();
     // 读回审计事件:恰一条 owner.bound_from_caller_pane。
     let events = crate::event_log::EventLog::new(&ws).tail(50).unwrap();
     let ev = events
@@ -223,7 +139,10 @@ fn emit_owner_bound_event_logs_prefix_only_never_full_uuid() {
         .find(|e| e["event"] == serde_json::json!("owner.bound_from_caller_pane"))
         .expect("必写 owner.bound_from_caller_pane");
     assert_eq!(ev["caller_pane_id"], serde_json::json!("%7"));
-    assert_eq!(ev["caller_current_command"], serde_json::json!("codex"));
+    assert_eq!(
+        ev["caller_current_command"],
+        serde_json::json!(result.caller_current_command)
+    );
     assert_eq!(ev["team_id"], serde_json::json!("default"));
     // derived_uuid_prefix == derived[:12](只前缀,12 hex)。
     assert_eq!(ev["derived_uuid_prefix"], serde_json::json!(prefix12));

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

@@ -1,3 +1,4 @@
+//!
 //! leader 数据层 — lease/owner/incident 枚举 + struct + 错误 + cross-lane 占位/trait + 锁名常量。
 
 use std::collections::BTreeMap;
@@ -472,34 +473,6 @@ pub enum LeaderError {
     Messaging(#[from] crate::messaging::MessagingError),
 }
 
-// ===========================================================================
-// CROSS-LANE PLACEHOLDERS — 其他并行 lane 的 typed 依赖,leader 集成时 reconcile。
-// (本骨架定义 MINIMAL 本地占位,不猜对方精确命名;见 cross_deps_or_placeholders。)
-// ===========================================================================
-
-/// 命名互斥锁句柄占位(step 11 messaging / runtime 的 `_runtime_lock(workspace, name)`)。
-/// `LEADER_OWNERSHIP_LOCK = "send"`:attach/claim/takeover/autobind 共享同一临界区。
-/// **PLACEHOLDER**:真锁类型(文件锁 / RAII guard)在 runtime/messaging lane 落地。
-pub struct RuntimeLockGuard {
-    pub _name: String,
-}
-
-/// MessageStore 占位引用(step 7 已有 `message_store::MessageStore`,但 requeue 方法
-/// `requeue_delivery_exhausted_watchers` / `requeue_after_claim_leader` 属 step 11 messaging)。
-/// **PLACEHOLDER**:claim/attach 后 requeue exhausted result watchers 的接口签名,
-/// 由 messaging lane 落地。
-pub struct RequeueOutcome {
-    pub watcher_ids: Vec<String>,
-}
-
-/// `_resolve_leader_pane` 返回的 pane 信息占位(step 9 transport `PaneInfo` 的相邻产物)。
-/// `__init__.py:276` 调 `runtime._resolve_leader_pane` 返 `(pane_info, discovery)`。
-/// **PLACEHOLDER**:实际 pane_info 字段映射到 `transport::PaneInfo`,resolve 逻辑在 step 9/11。
-pub struct ResolvedLeaderPane {
-    pub pane_info: Value,
-    pub discovery: Discovery,
-}
-
 // ===========================================================================
 // 常量 / 锁名
 // ===========================================================================

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

@@ -35,6 +35,9 @@
 //! provider client crate,测试断言 mock 调用计数 = 0。
 
 // step 2 (model) — typed bedrock。其余 step 落地时在此挂载。
+#[cfg(test)]
+extern crate self as team_agent;
+
 pub mod model;
 
 // step 3 (db) — team.db SQLite schema/migration(rusqlite bundled)。
@@ -50,6 +53,10 @@ pub mod state;
 // step 6 (compiler) — TEAM.md + agents/*.md → 规范 team.spec dict(doc→spec 纯变换)。
 pub mod compiler;
 
+// Official communication-mode catalog. Configuration compilation and every
+// future projection consumer must use this typed single source of truth.
+pub mod communication_mode;
+
 // step 7 (message_store) — team.db 上的核心消息生命周期(create/claim/mark/通知去重)。
 // unit-10 (Stage 4) compat shim. Physical home is now `crate::db::message_store`.
 pub use crate::db::message_store;

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

@@ -1,3 +1,4 @@
+//!
 //! lifecycle::display —— 能力门 / 后端解析 / 开关 / rebind 后重建。
 //!
 //! 0.5.39 Slice 1 (tmux-server-death-locate §7 Slice 1): all tmux
@@ -19,6 +20,7 @@ use super::*;
 
 // ── lifecycle::display —— 能力门 / 后端解析 / 开关 / rebind 后重建 ────────────
 
+///
 /// `resolve_display_backend(requested, recorded, source)`(`display/backend.py`)。默认
 /// adaptive;显式 none 是逃生口。
 pub fn resolve_display_backend(
@@ -32,6 +34,7 @@ pub fn resolve_display_backend(
     }
 }
 
+///
 /// `probe_display_capabilities(...)`(`display/adaptive.py:31`,C13)。能力探测,分支只看
 /// 结果不看 `cfg!(target_os)`;Windows/WSL → `NotImplementedThisPlatform`。
 pub fn probe_display_capabilities(_workspace: &Path) -> Result<DisplayProbe, LifecycleError> {
@@ -68,10 +71,11 @@ pub fn probe_display_capabilities(_workspace: &Path) -> Result<DisplayProbe, Lif
     })
 }
 
+///
 /// `open_worker_displays(workspace, session_name, jobs, backend, capability_probe)`
 /// (`display/worker_window.py`)。按后端分派 adaptive / ghostty_workspace / ghostty_window;
 /// 显示失败**不阻塞** team readiness(C14)。
-pub fn open_worker_displays(
+pub(crate) fn open_worker_displays(
     workspace: &Path,
     session_name: &SessionName,
     backend: DisplayBackend,
@@ -91,6 +95,7 @@ pub fn open_worker_displays(
     Ok(OpenDisplaysReport { backend, displays })
 }
 
+///
 /// `close_team_display_backends(state, event_log)`(`display/close.py`,C9)。按 state
 /// 记录的后端关显示;adaptive 只删带 team tag 的窗口(C2 leader pane 安全)+ orphan 清理。
 pub fn close_team_display_backends(
@@ -100,6 +105,7 @@ pub fn close_team_display_backends(
     close_adaptive_displays(workspace, session_name)
 }
 
+///
 /// `rebuild_adaptive_display_after_rebind(...)`(`display/rebuild.py`,C12)。restart 在
 /// leader rebind **之后**重建 adaptive 窗口(读 `leader_receiver.rebind_applied` 事件)。
 pub fn rebuild_adaptive_display_after_rebind(