@team-agent/installer 0.5.8 → 0.5.10

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

@@ -0,0 +1,402 @@
+//! Phase-DX E7 (0.5.9 host-leader-registry-design): file-per-leader discovery index.
+//!
+//! Location: `~/.team-agent/leaders/<workspace_hash>__<team_key>.json`.
+//!
+//! Registry entries are a **derived** discovery index — never a source of
+//! authority. Read paths must always canonical-validate a resolved entry
+//! against the target workspace's runtime state (leader_receiver,
+//! owner_epoch, transport_kind) before delivering. Ambiguous short names
+//! are refused (`name_ambiguous`) rather than resolved by any priority
+//! heuristic.
+//!
+//! Design constraints (host-leader-registry-design.md §§3, 9):
+//! - No shared/global relational store (file-per-team on the host filesystem).
+//! - No identity writes on read/send paths — write only happens from
+//!   `claim-leader`/`attach-leader`/`takeover`/`attach-app-server-leader`
+//!   canonical success hooks and shutdown/unregister on canonical success.
+//! - Registry write failure never fails the underlying binding command;
+//!   it is discoverability degradation, not binding failure.
+
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::transport::Transport;
+
+/// Current file schema_version for `~/.team-agent/leaders/*.json`.
+pub const REGISTRY_SCHEMA_VERSION: u32 = 1;
+
+/// Event name emitted after a successful atomic temp+rename write.
+pub const EVENT_REGISTERED: &str = "leader_registry.registered";
+
+/// Event name emitted when the write step (fs::write / rename / dir create)
+/// failed — the binding command still returns ok, but discoverability
+/// degrades until the next successful canonical hook.
+pub const EVENT_WRITE_FAILED: &str = "leader_registry.write_failed";
+
+/// Event name emitted when a canonical shutdown/unbind removed the entry.
+pub const EVENT_UNREGISTERED: &str = "leader_registry.unregistered";
+
+/// v1 file schema. Fields are copied verbatim from `LeaderRegistryEntry`
+/// during atomic writes; readers deserialize the same shape then validate
+/// against canonical state before using any field for routing.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LeaderRegistryEntry {
+    pub schema_version: u32,
+    /// Default delivery name — the runtime `team_key`. Never the display or
+    /// spec name (host-leader-registry-design.md §5.1).
+    pub delivery_name: String,
+    /// Human-friendly qualified name: `<workspace_short>/<team_key>`.
+    pub qualified_name: String,
+    /// Stable qualified name: `<workspace_hash>/<team_key>`. Always accepted
+    /// by resolvers even when the human form is ambiguous.
+    pub stable_qualified_name: String,
+    /// Explicit aliases attached at binding time. Alias collisions follow
+    /// the same `name_ambiguous` rule as delivery_name collisions.
+    pub aliases: Vec<String>,
+    pub workspace: PathBuf,
+    /// sha256-prefix of canonical realpath workspace; used only as a file
+    /// name component and stable identifier — never an authority key.
+    pub workspace_hash: String,
+    pub workspace_short: String,
+    pub team_key: String,
+    pub transport_kind: String,
+    pub channel: serde_json::Value,
+    pub owner_epoch: u64,
+    pub attached_at: String,
+    pub updated_at: String,
+    pub source: String,
+    pub status: String,
+}
+
+impl LeaderRegistryEntry {
+    /// Ambiguous-name refusal semantics (host-leader-registry-design.md §5.2):
+    /// two entries with the same `delivery_name` remain visible in
+    /// `leaders` under `ambiguous_names`, and `send --to-leader <short>`
+    /// refuses `name_ambiguous`. Callers surface the ambiguity via
+    /// candidates rather than choosing a winner. The design explicitly
+    /// forbids priority heuristics based on write order, modification
+    /// time, or ambient state — see host-leader-registry-design.md §5.2
+    /// for the enumerated exclusions.
+    #[must_use]
+    pub fn short_name_collision_refuses() -> &'static str {
+        "ambiguous"
+    }
+}
+
+/// Payload key for the list of short-name collisions surfaced by
+/// `team-agent leaders` — kept as a top-level constant so both `leaders`
+/// and `send --to-leader` refer to the same wire name.
+pub const AMBIGUOUS_NAMES_FIELD: &str = "ambiguous_names";
+
+/// Wire reason used by both `leaders` and `send --to-leader` when a name
+/// resolves to multiple canonical-live entries. Candidates carry
+/// `workspace_hash` + `stable_qualified_name` so the caller can retry with
+/// a fully-qualified form.
+pub const REASON_AMBIGUOUS: &str = "name_ambiguous";
+
+/// Absolute path to `~/.team-agent/leaders`. Returns `None` when the
+/// caller has no HOME (e.g. some CI shells) — callers should treat this as
+/// "no registry" rather than an error, since registry is derived.
+#[must_use]
+pub fn registry_dir() -> Option<PathBuf> {
+    let home = std::env::var_os("HOME").map(PathBuf::from)?;
+    Some(home.join(".team-agent").join("leaders"))
+}
+
+/// Compute the sha256 hex prefix (12 chars) of a canonical workspace path.
+/// The canonical form is used so equivalent paths (symlinks, `.`, etc.)
+/// map to the same discovery id. If canonicalize fails the input path is
+/// used verbatim — the hash is a stable label, not an authority key.
+#[must_use]
+pub fn workspace_hash(workspace: &Path) -> String {
+    let canonical = std::fs::canonicalize(workspace).unwrap_or_else(|_| workspace.to_path_buf());
+    let mut hasher = Sha256::new();
+    hasher.update(canonical.to_string_lossy().as_bytes());
+    let digest = hasher.finalize();
+    digest[..6]
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect()
+}
+
+/// Compute the discovery-visible short label for a workspace path —
+/// basename by default, "workspace" when the path has no name component.
+#[must_use]
+pub fn workspace_short(workspace: &Path) -> String {
+    workspace
+        .file_name()
+        .and_then(|s| s.to_str())
+        .map(str::to_string)
+        .unwrap_or_else(|| "workspace".to_string())
+}
+
+/// Assemble a schema-v1 entry from canonical binding fields. Callers use
+/// this from the binding-command success hooks; the entry then flows into
+/// [`write_entry_best_effort`].
+#[must_use]
+#[allow(clippy::too_many_arguments)]
+pub fn build_entry(
+    workspace: &Path,
+    team_key: &str,
+    transport_kind: &str,
+    channel: serde_json::Value,
+    owner_epoch: u64,
+    source: &str,
+    now_rfc3339: String,
+) -> LeaderRegistryEntry {
+    let hash = workspace_hash(workspace);
+    let short = workspace_short(workspace);
+    LeaderRegistryEntry {
+        schema_version: REGISTRY_SCHEMA_VERSION,
+        delivery_name: team_key.to_string(),
+        qualified_name: format!("{short}/{team_key}"),
+        stable_qualified_name: format!("{hash}/{team_key}"),
+        aliases: Vec::new(),
+        workspace: std::fs::canonicalize(workspace).unwrap_or_else(|_| workspace.to_path_buf()),
+        workspace_hash: hash,
+        workspace_short: short,
+        team_key: team_key.to_string(),
+        transport_kind: transport_kind.to_string(),
+        channel,
+        owner_epoch,
+        attached_at: now_rfc3339.clone(),
+        updated_at: now_rfc3339,
+        source: source.to_string(),
+        status: "attached".to_string(),
+    }
+}
+
+fn entry_filename(entry: &LeaderRegistryEntry) -> String {
+    format!("{}__{}.json", entry.workspace_hash, entry.team_key)
+}
+
+/// Registry write is best-effort. Writes to `.<file>.tmp-<pid>-<counter>`
+/// first, then atomically renames to `<workspace_hash>__<team_key>.json`.
+/// Returns the final path when the write succeeded, `None` otherwise —
+/// the binding command must never fail on registry errors.
+pub fn write_entry_best_effort(entry: &LeaderRegistryEntry) -> Option<PathBuf> {
+    let dir = registry_dir()?;
+    if let Err(_error) = std::fs::create_dir_all(&dir) {
+        return None;
+    }
+    let final_path = dir.join(entry_filename(entry));
+    let tmp_name = format!(
+        ".{}.tmp-{}-{}",
+        entry_filename(entry),
+        std::process::id(),
+        rand_suffix()
+    );
+    let tmp_path = dir.join(tmp_name);
+    let serialized = serde_json::to_string_pretty(entry).ok()?;
+    if std::fs::write(&tmp_path, serialized).is_err() {
+        let _ = std::fs::remove_file(&tmp_path);
+        return None;
+    }
+    if std::fs::rename(&tmp_path, &final_path).is_err() {
+        let _ = std::fs::remove_file(&tmp_path);
+        return None;
+    }
+    Some(final_path)
+}
+
+fn rand_suffix() -> String {
+    // Non-cryptographic uniqueness: a process-local monotonic counter is
+    // enough because the tmp name only needs to be unique within one
+    // process lifetime (we also embed the pid).
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let n = COUNTER.fetch_add(1, Ordering::Relaxed);
+    format!("{n:x}")
+}
+
+/// Remove the registry entry for `(workspace, team_key)` if it exists.
+/// Called from shutdown/unbind success hooks after canonical state
+/// reflects the leader as no longer bound. Missing files are treated as
+/// success — the invariant is "no registry entry after unbind", not
+/// "must have found something to delete".
+pub fn unregister_entry(workspace: &Path, team_key: &str) -> Option<PathBuf> {
+    let dir = registry_dir()?;
+    let hash = workspace_hash(workspace);
+    let path = dir.join(format!("{hash}__{team_key}.json"));
+    if path.exists() {
+        std::fs::remove_file(&path).ok()?;
+        return Some(path);
+    }
+    None
+}
+
+/// Read and deserialize every `*.json` file under the registry directory.
+/// Skips unreadable / malformed files silently (returns fewer entries) —
+/// registry is a derived discovery index and unreadable files are the
+/// "STALE / UNREADABLE" dirty class rather than an error.
+#[must_use]
+pub fn read_all_entries() -> Vec<(PathBuf, LeaderRegistryEntry)> {
+    let Some(dir) = registry_dir() else {
+        return Vec::new();
+    };
+    let Ok(read_dir) = std::fs::read_dir(&dir) else {
+        return Vec::new();
+    };
+    let mut out = Vec::new();
+    for entry in read_dir.flatten() {
+        let path = entry.path();
+        if path
+            .file_name()
+            .and_then(|s| s.to_str())
+            .is_some_and(|name| name.starts_with('.'))
+        {
+            continue;
+        }
+        if path.extension().and_then(|s| s.to_str()) != Some("json") {
+            continue;
+        }
+        let Ok(text) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(entry) = serde_json::from_str::<LeaderRegistryEntry>(&text) else {
+            continue;
+        };
+        out.push((path, entry));
+    }
+    out.sort_by(|a, b| a.0.cmp(&b.0));
+    out
+}
+
+/// Validate a registry entry against its canonical workspace state.
+/// Returns the wire status label — LIVE when canonical `leader_receiver`
+/// matches, STALE otherwise. This is the pruning gate for GC and the
+/// per-entry classification the `leaders` CLI reports.
+#[must_use]
+pub fn classify(entry: &LeaderRegistryEntry) -> (&'static str, Option<String>) {
+    let Ok(state) = crate::state::persist::load_runtime_state(&entry.workspace) else {
+        return ("STALE", Some("workspace_no_state".to_string()));
+    };
+    let team = state
+        .get("teams")
+        .and_then(|v| v.as_object())
+        .and_then(|teams| teams.get(&entry.team_key));
+    let team = match team {
+        Some(t) => t,
+        None => return ("STALE", Some("team_key_not_found".to_string())),
+    };
+    // Team status must indicate liveness. Empty / missing counts as
+    // alive for pre-status states; explicit down/stopped/archived is
+    // terminal STALE.
+    let team_status = team
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("alive");
+    if team_status == "down" || team_status == "stopped" || team_status == "archived" {
+        return ("STALE", Some("team_not_alive".to_string()));
+    }
+    let receiver = team.get("leader_receiver");
+    let receiver = match receiver {
+        Some(r) if !r.is_null() => r,
+        _ => return ("STALE", Some("leader_not_attached".to_string())),
+    };
+    let canonical_epoch = receiver
+        .get("owner_epoch")
+        .and_then(|v| v.as_u64())
+        .or_else(|| team.get("owner_epoch").and_then(|v| v.as_u64()))
+        .unwrap_or(0);
+    if canonical_epoch != entry.owner_epoch {
+        return (
+            "STALE",
+            Some(format!(
+                "owner_epoch_mismatch:registry={},canonical={}",
+                entry.owner_epoch, canonical_epoch
+            )),
+        );
+    }
+    // Verify the recorded leader pane is actually live on its recorded
+    // tmux endpoint. A killed tmux session (test's kill_session) means
+    // the receiver is stale even though the state hasn't been updated.
+    let pane_id = receiver.get("pane_id").and_then(|v| v.as_str());
+    let socket = receiver.get("tmux_socket").and_then(|v| v.as_str());
+    if let (Some(pane), Some(sock)) = (pane_id, socket) {
+        if !tmux_pane_live(sock, pane) {
+            return ("STALE", Some("leader_pane_dead".to_string()));
+        }
+    }
+    ("LIVE", None)
+}
+
+fn tmux_pane_live(socket: &str, pane_id: &str) -> bool {
+    // Best-effort tmux liveness check via the same transport factory the
+    // main runtime uses. On error we treat the pane as NOT live so a
+    // send never routes through a socket we could not verify.
+    let backend = crate::transport_factory::tmux_endpoint_transport(socket);
+    match backend.list_targets() {
+        Ok(targets) => targets.iter().any(|t| t.pane_id.as_str() == pane_id),
+        Err(_) => false,
+    }
+}
+
+/// Return the canonical state's `leader_receiver` value for the entry's
+/// team, if one exists. Send/leaders paths use this so they never route
+/// through a stale registry channel — canonical state is the truth.
+#[must_use]
+pub fn canonical_receiver(entry: &LeaderRegistryEntry) -> Option<serde_json::Value> {
+    let state = crate::state::persist::load_runtime_state(&entry.workspace).ok()?;
+    let team = state
+        .get("teams")
+        .and_then(|v| v.as_object())
+        .and_then(|teams| teams.get(&entry.team_key))?;
+    team.get("leader_receiver").cloned()
+}
+
+/// Read all entries, classify each, and prune terminal-stale entries
+/// (`workspace_no_state`, `team_key_not_found`). Live entries are never
+/// touched. Returns the surviving (LIVE + STALE-not-yet-pruned) entries
+/// classified for the `leaders` command output.
+///
+/// Design §14 step 6: "Successful scoped shutdown removes matching registry
+/// entry. Failed/degraded shutdown leaves entry STALE, not deleted."
+/// The pruning here is the GC arm — it only removes entries whose
+/// canonical workspace/team has no state at all, i.e. the target has been
+/// permanently removed. Leader-detached-but-team-alive stays STALE and
+/// visible so the operator can decide.
+#[must_use]
+pub fn list_validated_with_gc() -> Vec<(LeaderRegistryEntry, &'static str, Option<String>)> {
+    let mut out = Vec::new();
+    for (path, entry) in read_all_entries() {
+        let (status, reason) = classify(&entry);
+        // Terminal stale reasons that indicate the entry can never be
+        // useful again: canonical workspace/team gone, or the leader
+        // binding has been fully released (no receiver at all). These
+        // are safe to prune; leader-attached-with-dead-pane and
+        // epoch-mismatch stay visible so the operator can see them.
+        if status == "STALE"
+            && reason.as_deref().is_some_and(|r| {
+                r == "workspace_no_state"
+                    || r == "team_key_not_found"
+                    || r == "leader_not_attached"
+                    || r == "team_not_alive"
+            })
+        {
+            let _ = std::fs::remove_file(&path);
+            continue;
+        }
+        out.push((entry, status, reason));
+    }
+    out
+}
+
+/// Same as `list_validated_with_gc` but preserves all entries. `send
+/// --to-leader` needs to see stale entries so it can refuse with
+/// `registry_stale` (and never silently fall through to
+/// `leader_name_not_found` just because GC ran first).
+#[must_use]
+pub fn list_validated_no_gc() -> Vec<(LeaderRegistryEntry, &'static str, Option<String>)> {
+    read_all_entries()
+        .into_iter()
+        .map(|(_path, entry)| {
+            let (status, reason) = classify(&entry);
+            (entry, status, reason)
+        })
+        .collect()
+}

package/crates/team-agent/src/lifecycle/tests/phase_golden.rs

@@ -205,6 +205,7 @@ fn run_phase_golden(spec: PhaseGolden) -> Value {
         message_id: Some("phase-golden-message".to_string()),
         pane: None,
         to_name: None,
+        to_leader: None,
     });
     let collect = cmd_collect(&CollectArgs {
         workspace: workspace.clone(),

package/crates/team-agent/src/mcp_server/normalize.rs

@@ -118,6 +118,84 @@ pub fn normalize_report_envelope(env: &Value) -> NormalizedReportEnvelope {
     }
 }
 
+pub(crate) fn report_result_integrity_warnings(
+    source: &Value,
+    normalized: &NormalizedReportEnvelope,
+) -> Vec<Value> {
+    let mut warnings = source
+        .get("warnings")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+
+    match normalized.status {
+        ResultStatus::Success => {
+            if normalized.tests.is_empty()
+                || normalized
+                    .tests
+                    .iter()
+                    .all(|test| test.status == TestStatus::NotRun)
+            {
+                push_integrity_warning(
+                    &mut warnings,
+                    "result_success_without_executed_tests",
+                    "tests",
+                );
+            }
+            if change_path_missing_description(source.get("changes")) {
+                push_integrity_warning(
+                    &mut warnings,
+                    "result_change_missing_description",
+                    "changes",
+                );
+            }
+        }
+        ResultStatus::Partial | ResultStatus::Blocked => {
+            if normalized.tests.is_empty()
+                || normalized
+                    .tests
+                    .iter()
+                    .any(|test| test.status == TestStatus::NotRun)
+            {
+                push_integrity_warning(&mut warnings, "result_not_verified", "tests");
+            }
+        }
+        ResultStatus::Failed => {}
+    }
+
+    warnings
+}
+
+fn push_integrity_warning(warnings: &mut Vec<Value>, code: &str, field: &str) {
+    let exists = warnings.iter().any(|warning| {
+        warning.get("code").and_then(Value::as_str) == Some(code)
+            && warning.get("field").and_then(Value::as_str) == Some(field)
+    });
+    if !exists {
+        warnings.push(serde_json::json!({
+            "code": code,
+            "field": field,
+            "severity": "warning",
+            "advisory": true
+        }));
+    }
+}
+
+fn change_path_missing_description(value: Option<&Value>) -> bool {
+    items_from_value(value).iter().any(|item| {
+        let Some(obj) = item.as_object() else {
+            return false;
+        };
+        let has_path = ["path", "file", "filepath", "filename"]
+            .iter()
+            .any(|key| obj.get(*key).and_then(text_of_value).is_some());
+        let has_description = ["description", "summary", "detail", "details", "message"]
+            .iter()
+            .any(|key| obj.get(*key).and_then(text_of_value).is_some());
+        has_path && !has_description
+    })
+}
+
 /// `_compact_tool_result` (`normalize.py:6-64`): whitelist-key compaction of a
 /// delegate result. ok vs error use different key sets; `fanout_*` status preserves
 /// `deliveries`/`recipients`; `acknowledged_messages` → `acknowledged_count` (len).
@@ -170,6 +248,7 @@ pub fn compact_tool_result(result: &Value) -> ToolResult {
             "notification_status",
             "notification_channel",
             "notification_event_id",
+            "warnings",
         ]
     };
     for key in keys {

package/crates/team-agent/src/mcp_server/tools.rs

@@ -26,6 +26,7 @@ use super::helpers::{
 };
 use super::normalize::{
     compact_tool_result, normalize_report_envelope, normalize_result_status_observed,
+    report_result_integrity_warnings,
 };
 use super::types::{
     Scope, SendOutcome, ToolError, ToolErrorReason, ToolOk, ToolResult, VisiblePeers,
@@ -399,7 +400,13 @@ impl TeamOrchestratorTools {
             self.note_unknown_result_status(&raw);
         }
         let normalized = normalize_report_envelope(&base);
-        let env_value = normalized_envelope_value(&normalized);
+        let warnings = report_result_integrity_warnings(&base, &normalized);
+        let mut env_value = normalized_envelope_value(&normalized);
+        if !warnings.is_empty() {
+            if let Some(obj) = env_value.as_object_mut() {
+                obj.insert("warnings".to_string(), Value::Array(warnings));
+            }
+        }
         let owner_team = self.canonical_owner_team_key()?;
         messaging::report_result_for_owner_team(
             &self.workspace,

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

@@ -541,3 +541,61 @@ fn render_fallback_pane_message(content: &str, message_id: &str, primary_error:
          [team-agent-token:{message_id}]"
     )
 }
+
+/// E6 (0.5.9 offline-mailbox-toname-design §6.3): enqueue a leader-bound message
+/// row in the TARGET workspace `team.db` with status `queued_until_leader_attach`.
+///
+/// This is a durable "leader mailbox" write, NOT a delivery. Coordinator delivery
+/// never claims this status (§3.3), so the row will not churn or be marked
+/// `failed` while the leader is unattached. When the target owner runs
+/// `attach-leader` / `claim-leader`, the existing `requeue_blocked_leader_messages`
+/// helper flips the same row to `accepted` and the standard delivery pipeline
+/// injects it exactly once.
+///
+/// Safety boundary (§5): only the `messages` table is touched. Owner identity
+/// (`leader_receiver` / `team_owner` / `owner_epoch`) is never written by this
+/// path, and no provider/worker process is spawned.
+pub fn enqueue_leader_mailbox_until_attach(
+    target_workspace: &Path,
+    canonical_team_key: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    sender: &str,
+    event_log: &EventLog,
+) -> Result<DeliveryOutcome, MessagingError> {
+    let store = MessageStore::open(target_workspace)?;
+    let message_id = store.create_message(
+        task_id.map(TaskId::as_str),
+        sender,
+        "leader",
+        content,
+        None,
+        false,
+        Some(canonical_team_key),
+    )?;
+    // The default row status after `create_message` is `accepted`. Flip it to
+    // `queued_until_leader_attach` so it stays out of `claim_for_delivery`
+    // eligible set and out of `deliver_pending_messages` scan until an
+    // attach/claim explicitly requeues it (see requeue_blocked_leader_messages).
+    store.mark(&message_id, "queued_until_leader_attach", None)?;
+    event_log.write(
+        "leader_mailbox.queued_until_attach",
+        serde_json::json!({
+            "message_id": message_id,
+            "owner_team_id": canonical_team_key,
+            "sender": sender,
+            "target_workspace": target_workspace.display().to_string(),
+            "channel": "leader_mailbox",
+        }),
+    )?;
+    Ok(DeliveryOutcome {
+        ok: true,
+        status: DeliveryStatus::Queued,
+        message_status: MessageStatusShadow("queued_until_leader_attach".to_string()),
+        message_id: Some(message_id),
+        verification: None,
+        stage: None,
+        reason: None,
+        channel: Some("leader_mailbox".to_string()),
+    })
+}

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

@@ -83,7 +83,8 @@ pub use delivery::{
 };
 pub use helpers::fail_leader_delivery;
 pub use leader_receiver::{
-    deliver_to_leader_fallback_pane, mirror_peer_message_to_leader, send_to_leader_receiver,
+    deliver_to_leader_fallback_pane, enqueue_leader_mailbox_until_attach,
+    mirror_peer_message_to_leader, send_to_leader_receiver,
     send_to_leader_receiver_with_message_id,
 };
 pub use peers::allow_peer_talk;