@team-agent/installer 0.2.11 → 0.3.0

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

@@ -0,0 +1,99 @@
+//! step 10 · leader — ownership lease / leader-session binding / idle-takeover wiring
+//! (ROUND-0 SKELETON: types + fn/method SURFACE only, all bodies `unimplemented!()`).
+//!
+//! Card: `docs/phase0/subsystems/10-leader.md`
+//! (owned data/types table §16-37, public API §41-53, locks/rules §95-99).
+//! Truth source (READ-ONLY snapshot `team-agent-public` @ v0.2.11 / `439bef8`):
+//!   - `leader/__init__.py` (926 lines) — the five lease paths
+//!     (attach / start / claim / autobind / readopt) + leader identity context
+//!     + dual-state write + audit events.
+//!   - `leader_binding.py` (183) — Family A positive-source owner binding
+//!     (`bind_owner_from_caller_pane` / `derive_leader_session_uuid` / `emit_owner_bound_event`).
+//!   - `idle_takeover.py` (facade re-export) / `idle_takeover_wiring.py`
+//!     (`build_idle_nodes` / `push_idle_reminder`) / `wake.py`
+//!     (`should_reread` / `on_file_changed` / `take_pending`).
+//!   - `messaging/leader_panes.py` (`_leader_command_looks_usable` /
+//!     `_leader_command_provider` / `_target_leader_session_uuid`).
+//!
+//! 职责(card §职责):拥有「谁是 leader、消息投到哪个 pane」这一身份事实,当成租约(lease)
+//! 管理。pane id 即权威路由/授权身份,`owner_epoch` 做 CAS/去重,确定派生的
+//! `leader_session_uuid` + 注入 env 作兼容/审计元数据。统一 attach/claim/takeover/autobind/
+//! readopt 五条路径到同一把锁(`LEADER_OWNERSHIP_LOCK = "send"`)同一组安全门,双写
+//! workspace-level + team-level 两份 state 不分叉,每个 acquire/rebind/refusal 写结构化审计。
+//!
+//! 铁律(card §bug/陷阱 §80-89):
+//!   - **unknown ≠ idle**:turn state 用 `provider::TurnState` 穷尽 match,`Unknown` 显式
+//!     block ping,**绝不** `_ => idle`。
+//!   - **bug-085 None 漏穿**:`rollout_path` 用 `Option<RolloutPath>`,`None` 走 `Unknown`
+//!     分支并记 diagnostics;`_leader_node` path/provider 缺则省略 leader 节点而非猜 idle。
+//!   - **pane 即身份(C2/C10)**:授权是 pane id 等值,owner liveness 要求候选 pane 携带 owner
+//!     的 `leader_session_uuid`,不只看「leader-looking 命令名」。cwd 比对两边 realpath 后子树
+//!     包含,禁 basename/startswith/子串/反推。
+//!   - **死 owner 不锁活 caller(C4)**:liveness 探针失败 = 未确认活 → fail-safe 不据 stale
+//!     record 拒新 caller;模糊信号(命令错/cwd 错但 pane 在)要 `--confirm`。
+//!   - **TOCTOU epoch race(C3/C15)**:precheck 后在锁内 revalidate epoch + liveness,真 CAS。
+//!   - **双写不分叉(C17/C18)**:同一锁内写 workspace state.json + team/<session> snapshot;
+//!     发现分叉写 `state_divergence_repaired`。多候选 claim 分支也必须双写。
+//!   - **claude_code 归一**:`provider::Provider` 单一归一,穷尽 match,编译期堵死。
+//!   - **wake 不轮询/不解析**:`wake` 层纯决策何时重读,provider-neutral。
+//!
+//! ROUND-0:仅类型 + fn/method 签名;fallible 操作返 `Result`/`Option`(§10 实现层禁
+//! unwrap/expect/panic,故签名先 fallible)。daemon-path(tick/idle push)返 `Result`。
+//! `#![deny(...)]` 由 leader 在 integration 时统一加,本骨架不加。
+
+// ROUND-0 skeleton:fn body 全 unimplemented!() → import/field/method 暂未被用;P2 porter 落实现时移除。
+#![allow(dead_code, unused_imports)]
+// §10:lease / owner-bind / idle-takeover / tick 路径,实现层禁 unwrap/expect/panic(未 port 的
+// unimplemented! stub 不算 —— 那些待各自 contract+port)。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use thiserror::Error;
+
+// ── REUSE: 既有 typed 地基(不重定义)──────────────────────────────────────────
+// model::ids — leader 身份/owner epoch newtypes(§3)。
+use crate::model::ids::{LeaderSessionUuid, OwnerEpoch, TeamKey};
+// provider — turn state 穷尽枚举(unknown≠idle 命门)+ provider 归一 + bug-085 None 漏穿。
+use crate::provider::{Provider, RolloutPath, TurnState};
+// transport — pane 寻址 / 后端无关 PaneInfo(身份/rebind 地基)。
+use crate::transport::{PaneId, SessionName, Target, WindowName};
+// state — owner-gate caller 身份 + first-time binding + identity 派生 + projection。
+use crate::state::owner_gate::CallerIdentity;
+use crate::state::StateError;
+
+// ── REUSE-by-reference(签名引用,实际复用既有自由函数,不在此重声明)──────────────
+// state::identity::{apply_first_time_leader_binding, leader_env_exports,
+//                   validate_leader_uuid_from_targets, caller_identity_from_env,
+//                   identity_machine_fingerprint, identity_os_user}
+// state::projection::{team_state_key, select_runtime_state}
+// state::owner_gate::{check_team_owner, workspace_paths_match, PaneLivenessProbe}
+// model::ids::LeaderSessionUuid::derive  (== Python derive_leader_session_uuid)
+// event_log::EventLog (write/tail)
+
+// ── submodules(by responsibility) ──────────────────────────────────────────
+mod helpers;
+pub mod inject;
+pub mod lease;
+pub mod owner_bind;
+pub mod rediscover;
+pub mod start;
+pub mod takeover;
+pub mod types;
+
+// ── RE-EXPORT INVARIANT:每个先前 root-visible 项原路径不变 ────────────────────
+pub use inject::*;
+pub use lease::*;
+pub use owner_bind::*;
+pub use rediscover::*;
+pub use start::*;
+pub use takeover::*;
+pub use types::*;
+// 私有 helper(原 module-private,现 pub(crate) 跨子模块复用)按原可达性再导出。
+pub(crate) use helpers::*;
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,292 @@
+//! leader::owner_bind — Family A 正源 owner 绑定(bind_owner_from_caller_pane / emit_owner_bound_event)
+//! + leader 身份上下文派生(override / state / derive)。
+
+use std::path::Path;
+
+use serde_json::{json, Value};
+
+use crate::model::ids::{LeaderSessionUuid, OwnerEpoch, TeamKey};
+use crate::provider::Provider;
+use crate::tmux_backend::TmuxBackend;
+use crate::transport::{PaneField, PaneId, Target, Transport};
+
+use super::helpers::{get_path_str, now_ts, prefix, resolve_workspace_for_hash};
+use super::{
+    ClaimedVia, LeaderError, LeaderEvent, LeaderIdentity, LeaderSessionUuidSource, LeaseReason,
+    OwnerBindResult, TeamOwner,
+};
+
+// ── leader::identity — leader_identity / 身份上下文 ──
+
+/// `leader_identity`(card §47;`__init__.py:355`)。`team-agent identity` 入口。
+/// 返回 uuid_prefix + 身份字段(JSON dict,CLI 直出)。
+pub fn leader_identity(workspace: &Path, team: Option<&str>) -> Result<Value, LeaderError> {
+    let state = crate::state::persist::load_runtime_state(workspace)?;
+    let identity = leader_identity_context(workspace, team, Some(&state))?;
+    Ok(json!({
+        "ok": true,
+        "uuid_prefix": prefix(identity.leader_session_uuid.as_str(), 12),
+        "machine_fingerprint": identity.machine_fingerprint,
+        "workspace_abspath": identity.workspace_abspath.to_string_lossy(),
+        "os_user": identity.os_user,
+        "team_id": identity.team_id.as_str(),
+        "current_pane_id": std::env::var("TEAM_AGENT_LEADER_PANE_ID")
+            .ok()
+            .filter(|v| !v.is_empty())
+            .or_else(|| std::env::var("TMUX_PANE").ok().filter(|v| !v.is_empty())),
+        "last_seen_at": get_path_str(&state, &["leader_receiver", "attached_at"])
+            .or_else(|| get_path_str(&state, &["leader_receiver", "last_seen_at"])),
+        "source": serde_json::to_value(identity.leader_session_uuid_source)?,
+    }))
+}
+
+/// `_leader_identity_context`(`__init__.py:192`)。派生 leader 身份上下文(override / state / derive)。
+pub fn leader_identity_context(
+    workspace: &Path,
+    team: Option<&str>,
+    state: Option<&Value>,
+) -> Result<LeaderIdentity, LeaderError> {
+    let team_id = TeamKey::new(match team {
+        Some(t) => t.to_string(),
+        None => state
+            .map(crate::state::projection::team_state_key)
+            .unwrap_or_else(|| "current".to_string()),
+    });
+    let workspace_abspath = resolve_workspace_for_hash(workspace);
+    let machine_fingerprint = state
+        .and_then(|s| get_path_str(s, &["team_owner", "machine_fingerprint"]))
+        .or_else(|| std::env::var("TEAM_AGENT_MACHINE_FINGERPRINT").ok())
+        .unwrap_or_default();
+    let os_user = std::env::var("USER")
+        .or_else(|_| std::env::var("USERNAME"))
+        .unwrap_or_default();
+    if let Ok(raw) = std::env::var("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") {
+        if !raw.is_empty() {
+            return Ok(LeaderIdentity {
+                leader_session_uuid: serde_json::from_value(Value::String(raw))?,
+                leader_session_uuid_source: LeaderSessionUuidSource::Override,
+                machine_fingerprint,
+                workspace_abspath,
+                os_user,
+                team_id,
+            });
+        }
+    }
+    if let Some(state_uuid) = state
+        .and_then(|s| get_path_str(s, &["team_owner", "leader_session_uuid"]))
+        .or_else(|| state.and_then(|s| get_path_str(s, &["leader_receiver", "leader_session_uuid"])))
+    {
+        return Ok(LeaderIdentity {
+            leader_session_uuid: serde_json::from_value(Value::String(state_uuid))?,
+            leader_session_uuid_source: LeaderSessionUuidSource::Derived,
+            machine_fingerprint,
+            workspace_abspath,
+            os_user,
+            team_id,
+        });
+    }
+    let leader_session_uuid = LeaderSessionUuid::derive(
+        &machine_fingerprint,
+        &workspace_abspath.to_string_lossy(),
+        &os_user,
+        team_id.as_str(),
+    )?;
+    Ok(LeaderIdentity {
+        leader_session_uuid,
+        leader_session_uuid_source: LeaderSessionUuidSource::Derived,
+        machine_fingerprint,
+        workspace_abspath,
+        os_user,
+        team_id,
+    })
+}
+
+// ── leader::binding — Family A 正源 owner 绑定 + derive_leader_session_uuid ──
+
+/// `bind_owner_from_caller_pane`(card §49;`leader_binding.py:46`)。Family A 正源 owner 绑定:
+/// 身份只来自 `$TMUX_PANE` + 一次定向 `tmux display-message` 查 `pane_current_command`。
+/// 缺 `$TMUX_PANE` → refuse + `owner.bind_refused`(`reason=caller_pane_missing`)。
+pub fn bind_owner_from_caller_pane(
+    workspace: &Path,
+    team_id: &TeamKey,
+    override_uuid: Option<&LeaderSessionUuid>,
+) -> Result<OwnerBindResult, LeaderError> {
+    let event_log = crate::event_log::EventLog::new(workspace);
+    let Some(pane) = std::env::var("TMUX_PANE").ok().filter(|p| !p.is_empty()) else {
+        let hint = "run team-agent from inside your leader pane (the tmux pane you want to own this team).";
+        event_log.write(
+            LeaderEvent::OwnerBindRefused.name(),
+            json!({
+                "reason": serde_json::to_value(LeaseReason::CallerPaneMissing)?,
+                "caller_pane_id": "",
+                "caller_current_command": "",
+                "team_id": team_id.as_str(),
+                "hint": hint,
+            }),
+        )?;
+        return Ok(OwnerBindResult {
+            ok: false,
+            owner: None,
+            caller_pane_id: PaneId::new(""),
+            caller_current_command: String::new(),
+            team_id: team_id.clone(),
+            reason: Some(LeaseReason::CallerPaneMissing),
+            hint: Some(hint.to_string()),
+        });
+    };
+    let caller_current_command = tmux_pane_current_command(workspace, &pane).unwrap_or_default();
+    let provider = bind_provider_from_env_or_command(&caller_current_command);
+    let machine_fingerprint = std::env::var("TEAM_AGENT_MACHINE_FINGERPRINT").unwrap_or_default();
+    let os_user = std::env::var("USER")
+        .or_else(|_| std::env::var("USERNAME"))
+        .unwrap_or_default();
+    let identity = family_a_identity(workspace, team_id, override_uuid, &machine_fingerprint, &os_user)?;
+    let owner = TeamOwner {
+        pane_id: PaneId::new(pane.clone()),
+        provider,
+        machine_fingerprint: machine_fingerprint.clone(),
+        leader_session_uuid: Some(identity.leader_session_uuid),
+        owner_epoch: OwnerEpoch::FIRST,
+        claimed_at: now_ts(),
+        claimed_via: ClaimedVia::ClaimLeader,
+        os_user: Some(os_user),
+    };
+    Ok(OwnerBindResult {
+        ok: true,
+        owner: Some(owner),
+        caller_pane_id: PaneId::new(pane),
+        caller_current_command,
+        team_id: team_id.clone(),
+        reason: None,
+        hint: None,
+    })
+}
+
+/// `emit_owner_bound_event`(`leader_binding.py:162`)。成功绑定后的审计 hook
+/// (`owner.bound_from_caller_pane`;只写 uuid 短前缀,不泄全 uuid)。
+pub fn emit_owner_bound_event(
+    workspace: &Path,
+    caller_pane_id: &PaneId,
+    caller_current_command: &str,
+    derived_leader_session_uuid: &LeaderSessionUuid,
+    team_id: &TeamKey,
+    old_leader_session_uuid: Option<&LeaderSessionUuid>,
+) -> Result<(), LeaderError> {
+    crate::event_log::EventLog::new(workspace).write(
+        LeaderEvent::OwnerBoundFromCallerPane.name(),
+        json!({
+            "caller_pane_id": caller_pane_id.as_str(),
+            "caller_current_command": caller_current_command,
+            "derived_uuid_prefix": prefix(derived_leader_session_uuid.as_str(), 12),
+            "old_uuid_prefix": old_leader_session_uuid.map_or("", |u| prefix(u.as_str(), 12)),
+            "team_id": team_id.as_str(),
+        }),
+    )?;
+    Ok(())
+}
+
+fn bind_provider_from_env_or_command(command: &str) -> Provider {
+    std::env::var("TEAM_AGENT_LEADER_PROVIDER")
+        .ok()
+        .and_then(|raw| super::helpers::parse_provider(&raw))
+        .unwrap_or_else(|| provider_from_command(command))
+}
+
+fn provider_from_command(command: &str) -> Provider {
+    match exact_command_name(command).as_deref() {
+        Some("claude") | Some("claude.exe") => Provider::Claude,
+        Some("codex") => Provider::Codex,
+        Some("fake") => Provider::Fake,
+        _ => Provider::Codex,
+    }
+}
+
+fn exact_command_name(command: &str) -> Option<String> {
+    let last = command
+        .split_whitespace()
+        .next()
+        .unwrap_or(command)
+        .rsplit(['/', '\\'])
+        .next()?;
+    let lower = last.to_ascii_lowercase();
+    if lower.is_empty() { None } else { Some(lower) }
+}
+
+pub fn owner_bind_provider_wire(command: &str) -> &'static str {
+    if let Ok(raw) = std::env::var("TEAM_AGENT_LEADER_PROVIDER") {
+        return match raw.as_str() {
+            "claude" => "claude",
+            "claude_code" => "claude_code",
+            "codex" => "codex",
+            "gemini_cli" => "gemini_cli",
+            "fake" => "fake",
+            _ => "",
+        };
+    }
+    match exact_command_name(command).as_deref() {
+        Some("claude") | Some("claude.exe") => "claude",
+        Some("codex") => "codex",
+        Some("fake") => "fake",
+        _ => "",
+    }
+}
+
+fn family_a_identity(
+    workspace: &Path,
+    team_id: &TeamKey,
+    override_uuid: Option<&LeaderSessionUuid>,
+    machine_fingerprint: &str,
+    os_user: &str,
+) -> Result<LeaderIdentity, LeaderError> {
+    if let Some(uuid) = override_uuid {
+        return Ok(LeaderIdentity {
+            leader_session_uuid: uuid.clone(),
+            leader_session_uuid_source: LeaderSessionUuidSource::Override,
+            machine_fingerprint: machine_fingerprint.to_string(),
+            workspace_abspath: resolve_workspace_for_hash(workspace),
+            os_user: os_user.to_string(),
+            team_id: team_id.clone(),
+        });
+    }
+    if let Ok(raw) = std::env::var("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") {
+        if !raw.is_empty() {
+            return Ok(LeaderIdentity {
+                leader_session_uuid: serde_json::from_value(Value::String(raw))?,
+                leader_session_uuid_source: LeaderSessionUuidSource::Override,
+                machine_fingerprint: machine_fingerprint.to_string(),
+                workspace_abspath: resolve_workspace_for_hash(workspace),
+                os_user: os_user.to_string(),
+                team_id: team_id.clone(),
+            });
+        }
+    }
+    let workspace_abspath = resolve_workspace_for_hash(workspace);
+    let leader_session_uuid = LeaderSessionUuid::derive(
+        machine_fingerprint,
+        &workspace_abspath.to_string_lossy(),
+        os_user,
+        team_id.as_str(),
+    )?;
+    Ok(LeaderIdentity {
+        leader_session_uuid,
+        leader_session_uuid_source: LeaderSessionUuidSource::Derived,
+        machine_fingerprint: machine_fingerprint.to_string(),
+        workspace_abspath,
+        os_user: os_user.to_string(),
+        team_id: team_id.clone(),
+    })
+}
+
+fn tmux_pane_current_command(workspace: &Path, pane: &str) -> Result<String, LeaderError> {
+    TmuxBackend::for_workspace(workspace)
+        .query(
+            &Target::Pane(PaneId::new(pane)),
+            PaneField::PaneCurrentCommand,
+        )
+        .map(|value| value.unwrap_or_default())
+        .map_err(|e| LeaderError::Tmux(e.to_string()))
+}
+
+// NOTE: `derive_leader_session_uuid`(`leader_binding.py:146`)已由
+// `model::ids::LeaderSessionUuid::derive` 字节对齐实现(含 NUL 拒绝 + golden 测试)——
+// 此 lane REUSE 之,不重声明。