@team-agent/installer 0.2.11 → 0.3.1

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

@@ -0,0 +1,209 @@
+//! 私有内部 helpers (status wire / envelope 校验 / scheduled kind 解析 / activity 信号
+//! 解析 / id 生成 / MessageStatusShadow 占位)。跨子模块/测试可见者升 `pub(crate)`。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use rusqlite::{params, OptionalExtension};
+
+use crate::message_store::MessageStore;
+
+use super::{
+    ActivityStatus, AgentActivity, DeliveryOutcome, DeliveryRefusal, DeliveryStatus,
+    MessagingError, ScheduledKind,
+};
+
+/// **PLACEHOLDER** — step 7 `messages.status` 行态 enum (`message_store` lane 的 `MessageStatus`)。
+/// step 7 已落地 core 但尚未导出该 enum (当前用裸 `&str`);本 lane 不猜其精确 variant 集,
+/// 用本地最小占位让 [`DeliveryOutcome::message_status`] 编得过。leader 集成时换成 step 7 的
+/// 权威 `MessageStatus`(`accepted`/`target_resolved`/`injected`/`visible`/`submitted`/
+/// `submitted_unverified`/`delivered`/`acknowledged`/`failed`/`queued_*` …)。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MessageStatusShadow(pub String);
+
+static RESULT_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+pub(crate) fn status_wire(status: DeliveryStatus) -> &'static str {
+    match status {
+        DeliveryStatus::Delivered => "delivered",
+        DeliveryStatus::Failed => "failed",
+        DeliveryStatus::Queued => "queued",
+        DeliveryStatus::Blocked => "blocked",
+        DeliveryStatus::Refused => "refused",
+        DeliveryStatus::RetryScheduled => "retry_scheduled",
+        DeliveryStatus::TrustAutoAnswerExhausted => "trust_auto_answer_exhausted",
+        DeliveryStatus::AlreadyDelivered => "already_delivered",
+        DeliveryStatus::FallbackLog => "fallback_log",
+        DeliveryStatus::BroadcastDelivered => "broadcast_delivered",
+        DeliveryStatus::BroadcastPartial => "broadcast_partial",
+        DeliveryStatus::FanoutDelivered => "fanout_delivered",
+        DeliveryStatus::FanoutPartial => "fanout_partial",
+    }
+}
+
+pub(crate) fn message_exists(store: &MessageStore, message_id: &str) -> Result<bool, MessagingError> {
+    let conn = crate::db::schema::open_db(store.db_path())?;
+    let found: Option<String> = conn
+        .query_row(
+            "select message_id from messages where message_id = ?1",
+            params![message_id],
+            |row| row.get(0),
+        )
+        .optional()?;
+    Ok(found.is_some())
+}
+
+pub(crate) fn next_result_id() -> String {
+    let n = RESULT_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |d| d.as_nanos());
+    format!("res_{:012x}", (nanos ^ u128::from(n)) & 0xFFFF_FFFF_FFFF)
+}
+
+pub(crate) fn next_run_id() -> String {
+    let id = next_result_id();
+    id.chars().filter(|c| *c != '_').take(12).collect()
+}
+
+pub(crate) fn required_str<'a>(value: &'a serde_json::Value, key: &str) -> Result<&'a str, MessagingError> {
+    value
+        .get(key)
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| MessagingError::Validation(format!("missing required field: {key}")))
+}
+
+pub(crate) fn validate_result_envelope(envelope: &serde_json::Value) -> Result<(), MessagingError> {
+    let schema = required_str(envelope, "schema_version")?;
+    if schema != "result_envelope_v1" {
+        return Err(MessagingError::Validation(format!(
+            "unsupported schema_version: {schema}"
+        )));
+    }
+    for key in ["task_id", "agent_id", "status", "summary"] {
+        let _ = required_str(envelope, key)?;
+    }
+    for key in ["changes", "tests", "risks", "artifacts", "next_actions"] {
+        if !envelope.get(key).is_some_and(serde_json::Value::is_array) {
+            return Err(MessagingError::Validation(format!("missing required array field: {key}")));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn parse_scheduled_kind(kind: &str) -> Result<ScheduledKind, MessagingError> {
+    match kind {
+        "send" => Ok(ScheduledKind::Send),
+        "health_ping" => Ok(ScheduledKind::HealthPing),
+        "trust_retry" => Ok(ScheduledKind::TrustRetry),
+        other => Err(MessagingError::Validation(format!(
+            "unknown scheduled event kind: {other}"
+        ))),
+    }
+}
+
+pub(crate) fn working_seconds(scrollback: &str) -> Option<u64> {
+    let lower = scrollback.to_ascii_lowercase();
+    let start = lower.find("working (")?;
+    let rest = scrollback.get(start + "Working (".len()..)?;
+    let seconds = rest.split_once('s')?.0;
+    seconds.parse::<u64>().ok()
+}
+
+pub(crate) fn non_provider_command(command: &str) -> Option<&str> {
+    let base = command.rsplit('/').next().unwrap_or(command);
+    let normalized = base.to_ascii_lowercase();
+    match normalized.as_str() {
+        "" | "codex" | "claude" | "gemini" | "openai" | "team-agent" => None,
+        _ => Some(base),
+    }
+}
+
+pub(crate) fn latest_prompt_signal(scrollback: &str) -> Option<AgentActivity> {
+    let lower = scrollback.to_ascii_lowercase();
+    let idle_pos = latest_idle_prompt_pos(scrollback);
+    let working_pos = ["working", "thinking", "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        .iter()
+        .filter_map(|needle| lower.rfind(needle))
+        .max();
+    match (idle_pos, working_pos) {
+        (Some(i), Some(w)) if i > w => Some(idle_activity()),
+        (Some(_), None) => Some(idle_activity()),
+        (_, Some(_)) => Some(AgentActivity {
+            status: ActivityStatus::Working,
+            confidence: 0.9,
+            rationale: "working_indicator".to_string(),
+        }),
+        (None, None) => None,
+    }
+}
+
+fn latest_idle_prompt_pos(scrollback: &str) -> Option<usize> {
+    scrollback
+        .match_indices('❯')
+        .map(|(idx, _)| idx)
+        .chain(scrollback.match_indices('›').map(|(idx, _)| idx))
+        .max()
+}
+
+fn idle_activity() -> AgentActivity {
+    AgentActivity {
+        status: ActivityStatus::Idle,
+        confidence: 0.9,
+        rationale: "idle_prompt".to_string(),
+    }
+}
+
+/// `_fail_leader_delivery` (`leader.py:394`) — **diagnostic ONLY** (#230 I-4 退化):
+/// 历史上返回 `ok=True/status=FallbackLog/channel="fallback_inbox"` 被上游误读为
+/// "已交付的 fallback log"。现新 leader-delivery primitive(`leader_receiver::send_to_leader_receiver`)
+/// 不再调本函数。本函数保留只供老代码路径(scheduler / 兼容旧测试)使用,且其
+/// outcome **不被视为 success**(I-3 反向断言要求 `leader_receiver.rs` 源文件不得含
+/// `DeliveryStatus::FallbackLog` 或 `fallback_inbox` 字面量,所以本函数从 `leader_receiver.rs`
+/// 搬到本 helpers 模块,字面量在此被允许)。
+pub fn fail_leader_delivery(
+    workspace: &std::path::Path,
+    payload: &serde_json::Value,
+    reason: DeliveryRefusal,
+    error: Option<&str>,
+) -> Result<DeliveryOutcome, MessagingError> {
+    let store = MessageStore::open(workspace)?;
+    let sender = payload.get("sender").and_then(serde_json::Value::as_str).unwrap_or("system");
+    let content = payload.get("content").and_then(serde_json::Value::as_str).unwrap_or("");
+    let task_id = payload.get("task_id").and_then(serde_json::Value::as_str);
+    let message_id = match payload.get("message_id").and_then(serde_json::Value::as_str) {
+        Some(existing) => existing.to_string(),
+        None => store.create_message(task_id, sender, "leader", content, None, false, None)?,
+    };
+    store.mark(&message_id, "failed", error)?;
+    crate::event_log::EventLog::new(workspace).write(
+        "leader_receiver.delivery_failed",
+        serde_json::json!({"message_id": message_id, "reason": serde_json::to_value(reason).ok(), "error": error}),
+    )?;
+    Ok(DeliveryOutcome {
+        ok: true,
+        status: DeliveryStatus::FallbackLog,
+        message_status: MessageStatusShadow("failed".to_string()),
+        message_id: Some(message_id),
+        verification: None,
+        stage: None,
+        reason: Some(reason),
+        channel: Some("fallback_inbox".to_string()),
+    })
+}
+
+pub(crate) fn recent_rfc3339(ts: &str, max_age_seconds: i64) -> bool {
+    let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(ts) else {
+        return false;
+    };
+    let age = chrono::Utc::now().signed_duration_since(parsed.with_timezone(&chrono::Utc));
+    age.num_seconds() <= max_age_seconds
+}
+
+pub(crate) fn stale_rfc3339(ts: &str, min_age_seconds: i64) -> bool {
+    let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(ts) else {
+        return false;
+    };
+    let age = chrono::Utc::now().signed_duration_since(parsed.with_timezone(&chrono::Utc));
+    age.num_seconds() >= min_age_seconds
+}

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

@@ -0,0 +1,329 @@
+//! leader.py — leader pane 注入边界 + 恰好一次去重门 (card §21/§72)。
+
+use std::path::Path;
+
+use serde_json::Value;
+
+use crate::event_log::EventLog;
+use crate::message_store::{MessageStore, NotificationClaimParams};
+use crate::model::ids::{OwnerEpoch, TaskId};
+use crate::transport::Transport;
+
+use super::helpers::MessageStatusShadow;
+use super::{DeliveryOutcome, DeliveryStatus, MessagingError};
+
+/// `_send_to_leader_receiver` (`leader.py:69`) — **N31/N32 funnel primitive**:所有 leader-bound
+/// caller(send_message(to=leader) / report_result / request_human / idle reminder /
+/// broadcast-to-leader / peer-mirror / worker.abnormal_exit)统一经过这里。
+///
+/// 职责 = create_message + leader_notification_log dedup(result_id 时)+ audit + emit
+/// `deliver_to_leader.submit`(funnel 指纹,契约 grep 用)。**不**预 claim:状态留 `accepted`,
+/// 让后续 `deliver_pending_messages` 同一管道做物理 inject(MUST-13 单注入点,leader/worker 同路径
+/// → #229 step2-gate 的 trust-defer 对 leader pane 自然适用)。**不**调 `fail_leader_delivery`
+/// 走 fallback inbox 假绿:无可用 leader pane → 返 `Blocked + channel=rebind_required`(I-4)。
+#[allow(clippy::too_many_arguments)]
+pub fn send_to_leader_receiver(
+    workspace: &Path,
+    state: &serde_json::Value,
+    leader_id: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    sender: &str,
+    requires_ack: bool,
+    result_id: Option<&str>,
+    event_log: &EventLog,
+) -> Result<DeliveryOutcome, MessagingError> {
+    let store = MessageStore::open(workspace)?;
+    let owner_team = active_team_key(workspace, state);
+    if requires_ack {
+        event_log.write(
+            "leader_receiver.no_ack_forced",
+            serde_json::json!({"sender": sender, "leader_id": leader_id, "result_id": result_id}),
+        )?;
+    }
+    let message_id = store.create_message(
+        task_id.map(TaskId::as_str),
+        sender,
+        leader_id,
+        content,
+        None,
+        false,
+        Some(&owner_team),
+    )?;
+    // #231 exactly-once across rebind: insert the leader_notification_log PK BEFORE the
+    // unbound-pane check. That way, if the result row gets blocked (I-4) and later the
+    // leader rebinds + reclaim replays this row, the dedup PK still gates any second
+    // report_result attempt with the same result_id (no duplicate notification).
+    if let Some(result_id) = result_id {
+        let claim = store.claim_leader_notification_delivery(NotificationClaimParams {
+            result_id,
+            owner_team_id: Some(&owner_team),
+            owner_epoch: owner_epoch_i64(state),
+            leader_session_uuid: leader_session_uuid(state),
+            proposed_message_id: &message_id,
+            envelope_hash: "",
+            pane_id: leader_pane_id(state),
+        })?;
+        if claim.status != "claimed_by_you" {
+            // Duplicate result_id: keep first winner's notified_message_id, drop this row
+            // by marking failed (deliver_pending will then skip it on its claim guard).
+            store.mark(&message_id, "failed", Some("already_notified_by"))?;
+            event_log.write(
+                "deliver_to_leader.submit",
+                serde_json::json!({
+                    "message_id": claim.notified_message_id,
+                    "leader_id": leader_id,
+                    "owner_team_id": owner_team,
+                    "result_id": result_id,
+                    "dedup": "already_notified_by",
+                }),
+            )?;
+            return Ok(DeliveryOutcome {
+                ok: true,
+                status: DeliveryStatus::AlreadyDelivered,
+                message_status: MessageStatusShadow("already_notified".to_string()),
+                message_id: Some(claim.notified_message_id),
+                verification: None,
+                stage: None,
+                reason: None,
+                channel: Some("leader_receiver".to_string()),
+            });
+        }
+    }
+    // #230 funnel fingerprint: deliver_to_leader.submit is emitted on EVERY funnel call,
+    // including the I-4 unbound case below — the worker's intent IS to submit to leader,
+    // the rebind path will replay this row through deliver_pending once the leader pane
+    // is bound. Emitting submit only on bound would skew the funnel audit and miss the
+    // exactly-once guarantee for blocked-then-reclaimed deliveries.
+    event_log.write(
+        "deliver_to_leader.submit",
+        serde_json::json!({
+            "message_id": message_id,
+            "leader_id": leader_id,
+            "owner_team_id": owner_team,
+            "sender": sender,
+            "result_id": result_id,
+        }),
+    )?;
+    event_log.write(
+        "leader_receiver.queued",
+        serde_json::json!({
+            "message_id": message_id,
+            "leader_id": leader_id,
+            "owner_team_id": owner_team,
+            "result_id": result_id,
+        }),
+    )?;
+    Ok(DeliveryOutcome {
+        ok: true,
+        status: DeliveryStatus::Queued,
+        message_status: MessageStatusShadow("accepted".to_string()),
+        message_id: Some(message_id),
+        verification: None,
+        stage: None,
+        reason: None,
+        channel: Some("leader_receiver".to_string()),
+    })
+}
+
+/// `claim_leader_receiver` (`leader.py:348`):认领/接管 leader pane + `owner_epoch++`。身份判定
+/// 借 step 10 原语 (`_target_matches_owner_identity`/`_leader_command_looks_usable`)。
+pub fn claim_leader_receiver(
+    workspace: &Path,
+    state: &mut serde_json::Value,
+    candidate: &serde_json::Value,
+    event_log: &EventLog,
+    confirm: bool,
+    expected_epoch: Option<OwnerEpoch>,
+) -> Result<serde_json::Value, MessagingError> {
+    if !confirm {
+        return Ok(serde_json::json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "confirm_required",
+            "action": "team-agent claim-leader --confirm",
+        }));
+    }
+    if let Some(expected) = expected_epoch {
+        if owner_epoch(state).is_some_and(|current| current != expected.0) {
+            let owner_epoch = owner_epoch(state).unwrap_or(0);
+            let bound_pane_id = leader_pane_id(state).map(ToString::to_string);
+            let value = serde_json::json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "owner_epoch_advanced",
+                "owner_epoch": owner_epoch,
+                "bound_pane_id": bound_pane_id,
+            });
+            event_log.write("leader_receiver.claim_refused", value.clone())?;
+            return Ok(value);
+        }
+    }
+    let candidate_pane = candidate.get("pane_id").and_then(Value::as_str);
+    if candidate_pane.is_some() && candidate_pane == leader_pane_id(state) {
+        return Ok(serde_json::json!({
+            "ok": true,
+            "status": "already_bound",
+            "pane_id": candidate_pane,
+            "owner_epoch": owner_epoch(state).unwrap_or(0),
+        }));
+    }
+    let next_epoch = owner_epoch(state).unwrap_or(0).saturating_add(1);
+    let Some(root) = state.as_object_mut() else {
+        return Err(MessagingError::Routing("runtime state root is not an object".to_string()));
+    };
+    let owner = root
+        .entry("team_owner")
+        .or_insert_with(|| serde_json::json!({}));
+    if let Some(owner) = owner.as_object_mut() {
+        owner.insert("owner_epoch".to_string(), serde_json::json!(next_epoch));
+    }
+    let receiver = root
+        .entry("leader_receiver")
+        .or_insert_with(|| serde_json::json!({}));
+    if let Some(receiver) = receiver.as_object_mut() {
+        receiver.insert("mode".to_string(), serde_json::json!("direct_tmux"));
+        receiver.insert("owner_epoch".to_string(), serde_json::json!(next_epoch));
+        copy_candidate_field(receiver, candidate, "pane_id");
+        copy_candidate_field(receiver, candidate, "provider");
+        copy_candidate_field(receiver, candidate, "leader_session_uuid");
+        if let Some(socket) = candidate
+            .get("tmux_socket")
+            .and_then(Value::as_str)
+            .filter(|socket| std::path::Path::new(socket).is_absolute())
+            .map(str::to_string)
+            .or_else(crate::tmux_backend::socket_name_from_tmux_env)
+        {
+            receiver.insert("tmux_socket".to_string(), serde_json::json!(socket));
+        }
+    }
+    crate::state::persist::save_runtime_state(workspace, state)?;
+    event_log.write(
+        "leader_receiver.claimed",
+        serde_json::json!({"owner_epoch": next_epoch, "candidate": candidate}),
+    )?;
+    let receiver = state
+        .get("leader_receiver")
+        .cloned()
+        .unwrap_or_else(|| candidate.clone());
+    Ok(serde_json::json!({
+        "ok": true,
+        "status": "claimed",
+        "leader_receiver": receiver,
+        "owner_epoch": next_epoch,
+    }))
+}
+
+/// `_mirror_peer_message_to_leader` (`leader.py:31`):peer→peer 消息镜像到 leader receiver。
+pub fn mirror_peer_message_to_leader(
+    workspace: &Path,
+    state: &serde_json::Value,
+    sender: &str,
+    recipient: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    event_log: &EventLog,
+) -> Result<(), MessagingError> {
+    let _ = send_to_leader_receiver(
+        workspace,
+        state,
+        "leader",
+        content,
+        task_id,
+        sender,
+        false,
+        None,
+        event_log,
+    )?;
+    let _ = recipient;
+    Ok(())
+}
+
+pub(crate) fn active_team_key(workspace: &Path, state: &Value) -> String {
+    state
+        .get("active_team_key")
+        .and_then(Value::as_str)
+        .filter(|team| !team.is_empty())
+        .map(ToString::to_string)
+        .or_else(|| workspace.file_name().map(|name| name.to_string_lossy().to_string()))
+        .unwrap_or_else(|| "current".to_string())
+}
+
+fn owner_epoch(state: &Value) -> Option<u64> {
+    receiver_or_owner_field(state, "team_owner", "owner_epoch")
+        .and_then(Value::as_u64)
+        .or_else(|| receiver_or_owner_field(state, "leader_receiver", "owner_epoch").and_then(Value::as_u64))
+}
+
+fn receiver_or_owner_field<'a>(state: &'a Value, record: &str, field: &str) -> Option<&'a Value> {
+    state
+        .get(record)
+        .and_then(|v| v.get(field))
+        .or_else(|| {
+            let active = state.get("active_team_key").and_then(Value::as_str)?;
+            state
+                .get("teams")
+                .and_then(Value::as_object)
+                .and_then(|teams| teams.get(active))
+                .and_then(|team| team.get(record))
+                .and_then(|v| v.get(field))
+        })
+}
+
+fn leader_record_field<'a>(state: &'a Value, field: &str) -> Option<&'a Value> {
+    receiver_or_owner_field(state, "leader_receiver", field)
+        .or_else(|| receiver_or_owner_field(state, "team_owner", field))
+}
+
+fn owner_epoch_i64(state: &Value) -> Option<i64> {
+    owner_epoch(state).and_then(|epoch| i64::try_from(epoch).ok())
+}
+
+fn leader_session_uuid(state: &Value) -> Option<&str> {
+    leader_record_field(state, "leader_session_uuid").and_then(Value::as_str)
+}
+
+pub(crate) fn leader_pane_bound_but_not_live(workspace: &Path, state: &Value) -> bool {
+    leader_pane_id(state)
+        .is_some_and(|pane_id| !leader_pane_is_live(workspace, state, pane_id))
+}
+
+fn leader_pane_is_live(workspace: &Path, state: &Value, pane_id: &str) -> bool {
+    if let Some(socket) = leader_tmux_socket(state) {
+        return crate::tmux_backend::TmuxBackend::for_tmux_endpoint(socket)
+            .list_targets()
+            .unwrap_or_default()
+            .iter()
+            .any(|target| target.pane_id.as_str() == pane_id);
+    }
+    let mut targets = crate::tmux_backend::TmuxBackend::for_workspace(workspace)
+        .list_targets()
+        .unwrap_or_default();
+    targets.extend(
+        crate::tmux_backend::TmuxBackend::new()
+            .list_targets()
+            .unwrap_or_default(),
+    );
+    targets.iter().any(|target| target.pane_id.as_str() == pane_id)
+}
+
+fn leader_pane_id(state: &Value) -> Option<&str> {
+    leader_record_field(state, "pane_id").and_then(Value::as_str)
+}
+
+fn leader_tmux_socket(state: &Value) -> Option<&str> {
+    leader_record_field(state, "tmux_socket")
+        .and_then(Value::as_str)
+        .filter(|socket| !socket.is_empty())
+        .filter(|socket| std::path::Path::new(socket).is_absolute())
+}
+
+fn copy_candidate_field(
+    out: &mut serde_json::Map<String, Value>,
+    candidate: &Value,
+    key: &str,
+) {
+    if let Some(value) = candidate.get(key) {
+        out.insert(key.to_string(), value.clone());
+    }
+}

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

@@ -0,0 +1,147 @@
+//! step 11 · messaging — delivery / scheduler / results / collect / report_result /
+//! watchers / leader-receiver / selftest 编排状态机 (ROUND-0 SKELETON).
+//!
+//! Card: `docs/phase0/subsystems/11-messaging.md` (type table §38-53, public API §60-75,
+//! bug/trap §118-132, module map §134-149).
+//! Truth source (READ-ONLY) `team-agent-public` @ v0.2.11 / `439bef8`:
+//!   - `messaging/send.py` · `delivery.py` · `internal_delivery.py` · `scheduler.py`
+//!   - `messaging/results.py` · `result_delivery.py` · `leader.py` · `leader_panes.py`
+//!   - `messaging/idle_alerts.py` · `activity_detector.py` · `trust_auto_answer.py`
+//!   - `messaging/session_drift.py` · `owner_bypass.py` · `routing.py`
+//!   - `diagnose/comms.py` (`run_comms_selftest` / `evaluate_idle_behavior`)
+//!
+//! SCOPE — this is the type/interface LAYER (so RED contracts can NAME these and
+//! compile), NOT the implementation. It mirrors only the CONTRACT-NAMED public
+//! surface; the 18 Python files' internal helpers are deferred (see
+//! `cross_deps_or_placeholders`). Bodies are `unimplemented!("step11 port: …")`.
+//!
+//! REUSE (do NOT redefine): [`MessageStore`] + [`NotificationClaimParams`] (step 7);
+//! [`Transport`] / [`Target`] / [`PaneId`] (step 9); [`Provider`] / [`MessageStatus`]
+//! shadow (step 2 enums); [`worker_sender_bypasses_owner_gate`] (step 5 owner-gate);
+//! [`RouteResult`] / [`route_task`] (step 2 routing); [`ProviderError`] / classifier
+//! types (step 8); [`EventLog`] (step 4).
+//!
+//! 铁律 (card §118-132, Rust 绝不重蹈):
+//!   - **unknown ≠ idle** (bug-071/077/085): [`ActivityStatus`] 穷尽 match,`Uncertain`
+//!     独立分支显式 block,**无 `_ => Idle` 兜底**。
+//!   - **dedup key 不含 leader_session_uuid** (Stage 12): 唯一去重原语 =
+//!     [`MessageStore::claim_leader_notification_delivery`] 的 `INSERT OR IGNORE`;
+//!     `peek` 只读快路径,非去重本身。`notified_message_id` requeue 必须存活 (Gap 32)。
+//!   - **trust 自动应答 fail-safe** (bug-064/082): pane 宽度查询失败时**绝不**返回默认
+//!     宽度 ([`PaneWidthQuery::Failed`]),matcher 退回精确相等;trust 应答只对自己工作
+//!     目录 realpath 全等。重试有界 ([`TRUST_RETRY_MAX_ATTEMPTS`]),终态显式。
+//!   - **scheduled kind 穷尽**: [`ScheduledKind`] 穷尽 match,漏 kind 编不过,无运行时 fallback。
+//!   - **busy → 延后不丢**: [`DeliveryStatus::Queued`] 不 mark failed,留队列等下次 tick。
+//!   - **selftest 零 provider SDK** (§84/MUST-NOT-13): [`run_comms_selftest`] 走 trait
+//!     mock,断言 `{anthropic,openai,httpx} == 0`,见 [`ProviderSdkCalls`]。
+//!
+//! §10:scheduler / result_delivery / leader_receiver / delivery 子路径被 coordinator
+//! daemon (step 12) tick 直接调用 (bug-084 崩溃面) → 所有投递/调度/IO 返
+//! `Result<_, MessagingError>` (thiserror)。`#![deny(unwrap/expect/panic)]` 由 leader
+//! 集成时统一加,本 ROUND-0 skeleton 不加 (与 provider.rs/transport.rs 一致)。
+
+// ROUND-0 skeleton:fn body 全 unimplemented!() → import/field/method 暂未被用;P2 porter 落实现时移除。
+#![allow(dead_code, unused_imports)]
+// §10:scheduler/result_delivery/leader_receiver/delivery 子路径被 coordinator daemon tick 直接调用
+// (bug-084 崩溃面)→ 实现层禁 unwrap/expect/panic(unimplemented!() stub 不被拦);tests 各自 allow。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use thiserror::Error;
+
+// ── REUSE: step 2 model ────────────────────────────────────────────────────
+// 这些模块根级 `use` 保持子模块测试 `use super::*` 的名字解析不变 (TeamKey / PaneId / …)。
+use crate::model::enums::Provider;
+use crate::model::ids::{LeaderSessionUuid, OwnerEpoch, TaskId, TeamKey};
+// route_task 已在 step 2 落地 (model::routing),send 子例程 REUSE,不重定义。
+pub use crate::model::routing::{route_task, RouteResult};
+
+// ── REUSE: step 4 event_log / step 7 message_store / step 9 transport ───────
+use crate::event_log::EventLog;
+use crate::message_store::MessageStore;
+use crate::transport::{PaneId, Target, Transport};
+
+pub mod activity;
+pub mod delivery;
+pub mod helpers;
+pub mod leader_receiver;
+pub mod peers;
+pub mod results;
+pub mod scheduler;
+pub mod selftest;
+pub mod send;
+pub mod trust;
+pub mod types;
+pub mod watchers;
+
+// ── re-export: 保持 `crate::messaging::X` 与 test `super::X` 解析不变 ──────────
+pub use activity::{classify_agent_activity, detect_cross_worker_deadlocks, detect_idle_fallbacks};
+pub use delivery::{
+    deliver_pending_message, deliver_pending_messages, deliver_stored_message, execute_trust_retry,
+    handle_trust_retry_needed, record_turn_open_if_leader_to_worker,
+    retry_injection_after_trust_auto_answer, stamp_first_send_at_if_leader_to_worker,
+    tmux_pane_width,
+};
+pub use helpers::fail_leader_delivery;
+pub use leader_receiver::{
+    claim_leader_receiver, mirror_peer_message_to_leader, send_to_leader_receiver,
+};
+pub use peers::allow_peer_talk;
+pub use results::{collect, collect_results_and_notify_watchers, report_result};
+pub use scheduler::{detect_stuck_agents, fire_due_scheduled_events, stuck_cancel, stuck_list};
+pub use selftest::{evaluate_idle_behavior, run_comms_selftest, CommsSelftestDriver};
+pub use send::{apply_worker_sender_bypass, send_message, session_drift_refusal, MessageTarget, SendOptions};
+pub use trust::{attempt_trust_auto_answer, TrustAnswerOutcome};
+pub use types::{
+    ActivityStatus, AgentActivity, AlertSnapshot, AlertSuppression, AlertType, CheckEvidence,
+    CheckKind, CheckStatus, DeliveryOutcome, DeliveryRefusal, DeliveryStage, DeliveryStatus,
+    IdleEvaluation, LeaderNotificationKey, LeaderReceiver, PaneWidthQuery, ProviderSdkCalls,
+    ReceiverMode, ScheduledKind, SelftestCheck, SelftestReport, SendEventPayload, TrustRetryPayload,
+    WatcherNotice, RESULT_DELIVERY_MAX_ATTEMPTS, SEND_RETRY_MAX_ATTEMPTS, TRUST_RETRY_BACKOFF_SECONDS,
+    TRUST_RETRY_MAX_ATTEMPTS,
+};
+pub use watchers::{
+    delivered_result_message, format_result_watcher_notification, notify_result_watchers,
+    requeue_after_claim_leader, requeue_delivery_exhausted_watchers, result_id_from_text,
+    retry_result_deliveries,
+};
+
+// `MessageStatusShadow` 是 [`DeliveryOutcome::message_status`] 的公有字段类型,原在模块根
+// 可见 (`crate::messaging::MessageStatusShadow`),故 `pub` 再导出保持解析不变。
+pub use helpers::MessageStatusShadow;
+
+// ===========================================================================
+// ERROR (thiserror, lib 边界;daemon tick 经此 Result 退避,§10/bug-084)
+// ===========================================================================
+
+/// messaging 子系统错误。投递/调度/IO 失败一律经此 `Result` 上抛,由 step 12 主循环
+/// catch + 退避;**绝不**在调度/投递循环 panic (bug-084)。
+#[derive(Debug, Error)]
+pub enum MessagingError {
+    #[error("db: {0}")]
+    Db(#[from] crate::db::DbError),
+    #[error("sqlite: {0}")]
+    Sqlite(#[from] rusqlite::Error),
+    #[error("message store: {0}")]
+    Store(#[from] crate::message_store::MessageStoreError),
+    #[error("transport: {0}")]
+    Transport(#[from] crate::transport::TransportError),
+    #[error("state: {0}")]
+    State(#[from] crate::state::StateError),
+    #[error("event log: {0}")]
+    EventLog(#[from] crate::event_log::EventLogError),
+    #[error("provider: {0}")]
+    Provider(String),
+    /// envelope / 输入校验 (validate_result_envelope 等)。
+    #[error("validation: {0}")]
+    Validation(String),
+    /// team 解析 / 路由 / owner-gate 拒绝 (非 IO,语义性失败)。
+    #[error("routing: {0}")]
+    Routing(String),
+    #[error("io: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("json: {0}")]
+    Json(#[from] serde_json::Error),
+}
+
+#[cfg(test)]
+mod tests;