@team-agent/installer 0.5.60 → 0.5.62

package/crates/team-agent/src/messaging/watchers.rs

@@ -5,12 +5,13 @@ use std::path::Path;
 use rusqlite::{params, OptionalExtension};
 
 use crate::event_log::EventLog;
+use crate::leader::LeaderIncident;
 use crate::message_store::{MessageStore, NotificationClaimParams};
 use crate::model::ids::{TaskId, TeamKey};
 use crate::transport::PaneId;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RecoveryIncident {
+pub(crate) struct RecoveryIncident {
     pub incident_id: String,
     pub occurred_at: String,
 }
@@ -20,7 +21,7 @@ use super::{MessagingError, WatcherNotice, RESULT_DELIVERY_MAX_ATTEMPTS};
 /// `notify_result_watchers` (`result_delivery.py:38`):匹配 + 去重 + (有界) 投递 result 给 leader
 /// watcher。**恰好一次** (Gap 32/38):同 result_id 多 watcher → 1 次注入,余 `superseded`。
 /// 去重唯一原语 = [`MessageStore::claim_leader_notification_delivery`]。`collect`/coordinator tick 调。
-pub fn notify_result_watchers(
+pub(crate) fn notify_result_watchers(
     workspace: &Path,
     result: &serde_json::Value,
     event_log: &EventLog,
@@ -475,20 +476,25 @@ pub fn requeue_after_claim_leader(
 
 pub fn recover_watchers_for_incident(
     workspace: &Path,
-    store: &MessageStore,
     event_log: &EventLog,
     owner_team_id: &TeamKey,
     claimed_pane_id: &PaneId,
-    incident: &RecoveryIncident,
+    incident: LeaderIncident,
 ) -> Result<Vec<WatcherNotice>, MessagingError> {
-    requeue_after_claim_leader(
-        workspace,
-        store,
-        event_log,
-        owner_team_id,
-        claimed_pane_id,
-        Some(&incident.occurred_at),
-    )
+    match incident {
+        LeaderIncident::LeaderAttached => Ok(Vec::new()),
+        LeaderIncident::LeaderClaimed => {
+            let store = MessageStore::open(workspace)?;
+            requeue_after_claim_leader(
+                workspace,
+                &store,
+                event_log,
+                owner_team_id,
+                claimed_pane_id,
+                None,
+            )
+        }
+    }
 }
 
 /// 0.5.5 gate054 round-2: attach-leader (and claim-leader) requeue for leader messages
@@ -529,6 +535,11 @@ pub(crate) fn requeue_blocked_leader_messages(
                     "blocked_leader_unbound": counts.blocked_leader_unbound,
                     "queued_until_leader_attach": counts.queued_until_leader_attach,
                 },
+                "attach_window_failures": {
+                    "reason": "leader_not_attached",
+                    "count": counts.blocked_leader_unbound,
+                    "status": "requeued_pending_physical_retry",
+                },
             }),
         )?;
     }
@@ -596,7 +607,7 @@ pub fn requeue_delivery_exhausted_watchers(
 
 /// `delivered_result_message` (`result_delivery.py:394`):内容级去重 —— 查某 result_id 是否已有
 /// 投递的 leader 通知消息。
-pub fn delivered_result_message(
+pub(crate) fn delivered_result_message(
     store: &MessageStore,
     result_id: &str,
     task_id: Option<&TaskId>,

package/crates/team-agent/src/model/enums.rs

@@ -1,3 +1,4 @@
+//!
 //! §19 散字符串态 → 穷尽 enum。每个 variant 与 Python 字符串**一一对应**(`#[serde]`
 //! rename 到精确字符串),保证 spec/state/event 序列化字节不漂移(§7)。
 //!

package/crates/team-agent/src/model/errors.rs

@@ -1,3 +1,4 @@
+//!
 //! 用户面错误。
 //!
 //! 陷阱 #6(02-model 卡):Python `errors.py` 用自定义 `RuntimeError` **遮蔽**内建

package/crates/team-agent/src/model/ids.rs

@@ -1,3 +1,4 @@
+//!
 //! §3 id newtypes —— Python 把 agent/task/team id 全用裸 `str` 混传(route/owner-gate/
 //! tasks 串台)。newtype 让"混传"编不过。serde `transparent` 保证序列化字节 == 裸字符串。
 

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

@@ -1,3 +1,4 @@
+//!
 //! step 2 · model — typed bedrock (REWRITE_PROMPT.md §6 step 2).
 //!
 //! 纯数据 + 纯函数核心:Python 的散字符串 / `dict[str,Any]` 在此变 §3 id-newtype +
@@ -18,6 +19,7 @@ pub mod ids;
 // cli/send.rs (positional adapter), mcp_server/tools.rs (owner-scoped
 // peer suggestions). Never a routing authority — advisory only.
 pub(crate) mod name_similarity;
+pub mod pane_authority_refusal;
 pub mod paths;
 pub mod permissions;
 pub mod routing;

package/crates/team-agent/src/model/name_similarity.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.5.45 naming-addressing (design §3.2/§4.1) — shared pure name
 //! similarity ranking helper.
 //!

package/crates/team-agent/src/model/pane_authority_refusal.rs

@@ -0,0 +1,359 @@
+//!
+//! Shared typed catalog for ambient tmux pane authority refusals.
+//!
+//! This module owns identities and payload shape only. Launchers and CLI
+//! presenters remain responsible for collecting facts and rendering them.
+
+use std::path::PathBuf;
+
+pub const REASON_FIELD: &str = "reason";
+pub const AVAILABILITY_FIELD: &str = "availability";
+pub const CAUSE_FIELD: &str = "cause";
+pub const ACTION_REQUIRED_FIELD: &str = "action_required";
+pub const HINT_ACTION_FIELD: &str = "hint_action";
+pub const ACTION_FIELD: &str = "action";
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityRefusalField {
+    RequestedWorkspace,
+    ObservedPaneId,
+    ObservedPaneWorkspace,
+    Endpoint,
+    CallerControllingTty,
+    ObservedPaneTty,
+}
+
+impl PaneAuthorityRefusalField {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::RequestedWorkspace => "requested_workspace",
+            Self::ObservedPaneId => "observed_pane_id",
+            Self::ObservedPaneWorkspace => "observed_pane_workspace",
+            Self::Endpoint => "endpoint",
+            Self::CallerControllingTty => "caller_controlling_tty",
+            Self::ObservedPaneTty => "observed_pane_tty",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityRefusalReason {
+    AmbientTmuxEndpointUnavailable,
+    AmbientPaneIdUnavailable,
+    AmbientPaneWorkspaceUnavailable,
+    CallerControllingTtyUnavailable,
+    ObservedPaneTtyUnavailable,
+    PaneTtyMismatch,
+    PaneWorkspaceMismatch,
+}
+
+impl PaneAuthorityRefusalReason {
+    pub const ALL: [Self; 7] = [
+        Self::AmbientTmuxEndpointUnavailable,
+        Self::AmbientPaneIdUnavailable,
+        Self::AmbientPaneWorkspaceUnavailable,
+        Self::CallerControllingTtyUnavailable,
+        Self::ObservedPaneTtyUnavailable,
+        Self::PaneTtyMismatch,
+        Self::PaneWorkspaceMismatch,
+    ];
+
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::AmbientTmuxEndpointUnavailable => "AmbientTmuxEndpointUnavailable",
+            Self::AmbientPaneIdUnavailable => "AmbientPaneIdUnavailable",
+            Self::AmbientPaneWorkspaceUnavailable => "AmbientPaneWorkspaceUnavailable",
+            Self::CallerControllingTtyUnavailable => "CallerControllingTtyUnavailable",
+            Self::ObservedPaneTtyUnavailable => "ObservedPaneTtyUnavailable",
+            Self::PaneTtyMismatch => "PaneTtyMismatch",
+            Self::PaneWorkspaceMismatch => "PaneWorkspaceMismatch",
+        }
+    }
+
+    pub const fn required_fact_fields(self) -> &'static [PaneAuthorityRefusalField] {
+        use PaneAuthorityRefusalField::{
+            CallerControllingTty, Endpoint, ObservedPaneId, ObservedPaneTty, ObservedPaneWorkspace,
+            RequestedWorkspace,
+        };
+
+        match self {
+            Self::AmbientTmuxEndpointUnavailable => &[RequestedWorkspace, Endpoint],
+            Self::AmbientPaneIdUnavailable => &[RequestedWorkspace, ObservedPaneId, Endpoint],
+            Self::AmbientPaneWorkspaceUnavailable => &[
+                RequestedWorkspace,
+                ObservedPaneId,
+                ObservedPaneWorkspace,
+                Endpoint,
+            ],
+            Self::CallerControllingTtyUnavailable => &[
+                RequestedWorkspace,
+                ObservedPaneId,
+                Endpoint,
+                CallerControllingTty,
+            ],
+            Self::ObservedPaneTtyUnavailable => &[
+                RequestedWorkspace,
+                ObservedPaneId,
+                Endpoint,
+                ObservedPaneTty,
+            ],
+            Self::PaneTtyMismatch => &[
+                RequestedWorkspace,
+                ObservedPaneId,
+                Endpoint,
+                CallerControllingTty,
+                ObservedPaneTty,
+            ],
+            Self::PaneWorkspaceMismatch => &[
+                RequestedWorkspace,
+                ObservedPaneId,
+                ObservedPaneWorkspace,
+                Endpoint,
+            ],
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityFactAvailability {
+    Unavailable,
+}
+
+impl PaneAuthorityFactAvailability {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Unavailable => "unavailable",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UnavailablePaneAuthorityFact<C> {
+    pub cause: C,
+}
+
+impl<C> UnavailablePaneAuthorityFact<C> {
+    pub const fn new(cause: C) -> Self {
+        Self { cause }
+    }
+
+    pub const fn availability(&self) -> PaneAuthorityFactAvailability {
+        PaneAuthorityFactAvailability::Unavailable
+    }
+}
+
+macro_rules! unavailable_causes {
+    ($name:ident { $($variant:ident => $wire:literal),+ $(,)? }) => {
+        #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+        pub enum $name {
+            $($variant),+
+        }
+
+        impl $name {
+            pub const fn as_str(self) -> &'static str {
+                match self {
+                    $(Self::$variant => $wire),+
+                }
+            }
+        }
+    };
+}
+
+unavailable_causes!(AmbientTmuxEndpointUnavailableCause {
+    TmuxValueNotUnicode => "tmux_value_not_unicode",
+    TmuxTupleFieldCountInvalid => "tmux_tuple_field_count_invalid",
+    EndpointMissing => "endpoint_missing",
+    EndpointNotAbsolute => "endpoint_not_absolute",
+    ServerPidInvalid => "server_pid_invalid",
+    SessionIndexInvalid => "session_index_invalid",
+});
+
+unavailable_causes!(AmbientPaneIdUnavailableCause {
+    EnvironmentValueMissing => "environment_value_missing",
+    EnvironmentValueEmpty => "environment_value_empty",
+    EnvironmentValueNotUnicode => "environment_value_not_unicode",
+});
+
+unavailable_causes!(AmbientPaneWorkspaceUnavailableCause {
+    PaneQueryFailed => "pane_query_failed",
+    PaneNotFound => "pane_not_found",
+    CurrentPathMissing => "current_path_missing",
+});
+
+unavailable_causes!(CallerControllingTtyUnavailableCause {
+    NoControllingTty => "no_controlling_tty",
+    DeviceIdentityUnresolvable => "device_identity_unresolvable",
+    PlatformUnsupported => "platform_unsupported",
+});
+
+unavailable_causes!(ObservedPaneTtyUnavailableCause {
+    PaneTtyMissing => "pane_tty_missing",
+    PaneTtyUnresolvable => "pane_tty_unresolvable",
+    PaneTtyNotCharacterDevice => "pane_tty_not_character_device",
+});
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AmbientTmuxEndpointUnavailableFacts {
+    pub requested_workspace: PathBuf,
+    pub endpoint: UnavailablePaneAuthorityFact<AmbientTmuxEndpointUnavailableCause>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AmbientPaneIdUnavailableFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: UnavailablePaneAuthorityFact<AmbientPaneIdUnavailableCause>,
+    pub endpoint: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AmbientPaneWorkspaceUnavailableFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: String,
+    pub observed_pane_workspace: UnavailablePaneAuthorityFact<AmbientPaneWorkspaceUnavailableCause>,
+    pub endpoint: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CallerControllingTtyUnavailableFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: String,
+    pub endpoint: String,
+    pub caller_controlling_tty: UnavailablePaneAuthorityFact<CallerControllingTtyUnavailableCause>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ObservedPaneTtyUnavailableFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: String,
+    pub endpoint: String,
+    pub observed_pane_tty: UnavailablePaneAuthorityFact<ObservedPaneTtyUnavailableCause>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PaneTtyMismatchFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: String,
+    pub endpoint: String,
+    pub caller_controlling_tty: u64,
+    pub observed_pane_tty: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PaneWorkspaceMismatchFacts {
+    pub requested_workspace: PathBuf,
+    pub observed_pane_id: String,
+    pub observed_pane_workspace: PathBuf,
+    pub endpoint: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityRefusalFacts {
+    AmbientTmuxEndpointUnavailable(AmbientTmuxEndpointUnavailableFacts),
+    AmbientPaneIdUnavailable(AmbientPaneIdUnavailableFacts),
+    AmbientPaneWorkspaceUnavailable(AmbientPaneWorkspaceUnavailableFacts),
+    CallerControllingTtyUnavailable(CallerControllingTtyUnavailableFacts),
+    ObservedPaneTtyUnavailable(ObservedPaneTtyUnavailableFacts),
+    PaneTtyMismatch(PaneTtyMismatchFacts),
+    PaneWorkspaceMismatch(PaneWorkspaceMismatchFacts),
+}
+
+impl PaneAuthorityRefusalFacts {
+    pub const fn reason(&self) -> PaneAuthorityRefusalReason {
+        match self {
+            Self::AmbientTmuxEndpointUnavailable(_) => {
+                PaneAuthorityRefusalReason::AmbientTmuxEndpointUnavailable
+            }
+            Self::AmbientPaneIdUnavailable(_) => {
+                PaneAuthorityRefusalReason::AmbientPaneIdUnavailable
+            }
+            Self::AmbientPaneWorkspaceUnavailable(_) => {
+                PaneAuthorityRefusalReason::AmbientPaneWorkspaceUnavailable
+            }
+            Self::CallerControllingTtyUnavailable(_) => {
+                PaneAuthorityRefusalReason::CallerControllingTtyUnavailable
+            }
+            Self::ObservedPaneTtyUnavailable(_) => {
+                PaneAuthorityRefusalReason::ObservedPaneTtyUnavailable
+            }
+            Self::PaneTtyMismatch(_) => PaneAuthorityRefusalReason::PaneTtyMismatch,
+            Self::PaneWorkspaceMismatch(_) => PaneAuthorityRefusalReason::PaneWorkspaceMismatch,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityRecoveryHint {
+    AttachLeader,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PaneAuthorityRecoveryAction {
+    OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct PaneAuthorityRecovery {
+    pub action_required: bool,
+    pub hint_action: PaneAuthorityRecoveryHint,
+    pub action: PaneAuthorityRecoveryAction,
+}
+
+impl PaneAuthorityRecovery {
+    pub const REQUIRED: Self = Self {
+        action_required: true,
+        hint_action: PaneAuthorityRecoveryHint::AttachLeader,
+        action:
+            PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane,
+    };
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PaneAuthorityRefusal {
+    pub facts: PaneAuthorityRefusalFacts,
+    pub recovery: PaneAuthorityRecovery,
+}
+
+impl PaneAuthorityRefusal {
+    pub const fn new(facts: PaneAuthorityRefusalFacts) -> Self {
+        Self {
+            facts,
+            recovery: PaneAuthorityRecovery::REQUIRED,
+        }
+    }
+
+    pub const fn reason(&self) -> PaneAuthorityRefusalReason {
+        self.facts.reason()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{PaneAuthorityRefusalField as Field, PaneAuthorityRefusalReason as Reason};
+
+    #[test]
+    fn reason_catalog_is_closed_and_mismatch_requires_all_four_workspace_facts() {
+        assert_eq!(Reason::ALL.len(), 7);
+        assert_eq!(
+            Reason::PaneWorkspaceMismatch.required_fact_fields(),
+            &[
+                Field::RequestedWorkspace,
+                Field::ObservedPaneId,
+                Field::ObservedPaneWorkspace,
+                Field::Endpoint,
+            ]
+        );
+    }
+
+    #[test]
+    fn unavailable_reasons_require_the_fact_they_could_not_observe() {
+        assert!(Reason::AmbientTmuxEndpointUnavailable
+            .required_fact_fields()
+            .contains(&Field::Endpoint));
+        assert!(Reason::AmbientPaneIdUnavailable
+            .required_fact_fields()
+            .contains(&Field::ObservedPaneId));
+        assert!(Reason::AmbientPaneWorkspaceUnavailable
+            .required_fact_fields()
+            .contains(&Field::ObservedPaneWorkspace));
+    }
+}

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

@@ -1,3 +1,4 @@
+//!
 //! `.team/` 布局路径(移植 `paths.py` 的 workspace/team-dir 部分)。
 //!
 //! Python 端 `runtime_dir`/`logs_dir`/`artifacts_dir`/`messages_dir` 把 `.team/<sub>`

package/crates/team-agent/src/model/permissions.rs

@@ -1,3 +1,4 @@
+//!
 //! §19/§3 移植 `permissions.py`:role/provider/alias → 规范化权限矩阵。
 //!
 //! Python 全程裸 `str` + `dict[str, Any]`(`expand_tools`/`resolve_permissions`/
@@ -56,7 +57,7 @@ impl Tool {
 ///
 /// 注:返回**声明序集合**;Python 返回的是 role 字面顺序的 list,但下游 `resolve_*`
 /// 立即过 `expand_tools`(去重+排序),顺序不参与对拍,故此处用 `BTreeSet` 即可。
-pub fn default_tools_for_role(role: &str) -> BTreeSet<Tool> {
+fn default_tools_for_role(role: &str) -> BTreeSet<Tool> {
     use Tool::*;
     let tools: &[Tool] = match role {
         "leader" | "supervisor" => &[FsRead, FsList, McpTeam, ProviderBuiltin],
@@ -175,7 +176,7 @@ pub fn is_canonical_tool(name: &str) -> bool {
 ///
 /// 表里没有的 provider(如 `claude`)= Python 的 `.get(provider, {})` → 空表 →
 /// 每个 tool 再 `.get(tool, "prompt_only")` → 全 `prompt_only`(对拍 `R-unknownprov`)。
-pub fn provider_enforcement(provider: Provider, tool: Tool) -> Enforcement {
+fn provider_enforcement(provider: Provider, tool: Tool) -> Enforcement {
     use Enforcement::{Hard, PromptOnly};
     use Tool::*;
     match provider {

package/crates/team-agent/src/model/routing.rs

@@ -1,3 +1,4 @@
+//!
 //! 移植 `team_agent/routing.py` 的纯函数 `route_task`(真相源 v0.2.11)。
 //!
 //! 操作 spec/task 的 [`yaml::Value`]。返回 [`RouteResult`]{agent_id, reason}。

package/crates/team-agent/src/model/spec.rs

@@ -1,3 +1,4 @@
+//!
 //! spec / result-envelope 校验(`spec.py`)。
 //!
 //! 本 module **操作解析后的 Value**(非 typed struct)——与 Python 一样校验 dict,
@@ -400,6 +401,7 @@ fn check_agent(agent: &Yaml, path: &str, errors: &mut Vec<String>) {
         "preferred_for",
         "avoid_for",
         "output_contract",
+        "communication_mode",
         "paused",
         "auth_mode",
         "profile",
@@ -412,6 +414,21 @@ fn check_agent(agent: &Yaml, path: &str, errors: &mut Vec<String>) {
     if !agent.is_map() {
         return;
     }
+    if let Some(value) = agent.get("communication_mode") {
+        match value.as_str() {
+            Some(raw) if crate::communication_mode::CommunicationMode::parse(raw).is_none() => {
+                errors.push(format!(
+                    "{path}/communication_mode: unknown communication_mode '{raw}'"
+                ));
+            }
+            None => {
+                errors.push(format!(
+                    "{path}/communication_mode: unknown communication_mode"
+                ));
+            }
+            Some(_) => {}
+        }
+    }
     // 0.4.x provider effort MVP step 3: effort syntactic + semantic validation.
     if let Some(raw) = agent.get("effort").and_then(Yaml::as_str) {
         match crate::model::enums::ProviderEffort::parse(raw) {

package/crates/team-agent/src/model/task_graph.rs

@@ -1,3 +1,4 @@
+//!
 //! 移植 `team_agent/task_graph.py` 的三个纯函数:`find_dependency_cycle` /
 //! `ready_tasks` / `update_task_status`(真相源 v0.2.11)。
 //!

package/crates/team-agent/src/model/yaml/tests.rs

@@ -1,3 +1,4 @@
+//!
 #![allow(clippy::unwrap_used)]
 use super::*;
 

package/crates/team-agent/src/model/yaml.rs

@@ -1,3 +1,4 @@
+//!
 //! step 2 · model — `simple_yaml` 方言移植(真相源 `src/team_agent/simple_yaml.py`)。
 //!
 //! Team Agent **不**用标准 YAML:它有一份零依赖、字节级特判的子集 `loads`/`dumps`,