From 96bfc3c1f7ff0650882811866b506886f600c5d4 Mon Sep 17 00:00:00 2001
From: Nathan Herald <me@nathanherald.com>
Date: Thu, 30 Jul 2026 23:48:17 +0200
Subject: [PATCH] docs: mark cross-host presence experimental

---
 src/main.rs            |  6 ++++++
 tests/status_agents.rs | 25 +++++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/src/main.rs b/src/main.rs
index 907bceb6..938dfa93 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -253,6 +253,12 @@ enum Command {
     },
     /// List every agent in the catalog with presence and retirement state. `--json [--enrich]` is
     /// the stable machine-readable roster.
+    ///
+    /// EXPERIMENTAL: Cross-host presence is best-effort. Ordinary catalog replication may be
+    /// delayed, stale, or asymmetric. A remote `unknown` means no fresh observation, not proof that
+    /// an agent or host is unhealthy. Cross-host presence never gates local work or triggers
+    /// restart, teardown, reconciliation, or a global-fleet health conclusion. Host-local runtime
+    /// and service evidence remains authoritative for lifecycle decisions.
     Agents {
         /// The catalog folder (like `st2 ls`/`up`). Falls back to `--root`/`$CATALOG`.
         #[arg(conflicts_with = "catalog_path")]
diff --git a/tests/status_agents.rs b/tests/status_agents.rs
index 474facf4..2a130f7a 100644
--- a/tests/status_agents.rs
+++ b/tests/status_agents.rs
@@ -33,6 +33,31 @@ fn retired_agent_kdl(identity: &str, host: &str) -> String {
     )
 }
 
+#[test]
+fn agents_help_marks_cross_host_presence_experimental_and_non_authoritative() {
+    let output = Command::new(env!("CARGO_BIN_EXE_st2"))
+        .args(["agents", "--help"])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let help = String::from_utf8(output.stdout).unwrap();
+    for required in [
+        "EXPERIMENTAL: Cross-host presence is best-effort",
+        "delayed, stale, or asymmetric",
+        "A remote `unknown` means no fresh observation",
+        "not proof that an agent or host is unhealthy",
+        "never gates local work or triggers restart, teardown, reconciliation",
+        "or a global-fleet health conclusion",
+        "Host-local runtime and service evidence remains authoritative",
+    ] {
+        assert!(help.contains(required), "missing {required:?} in:\n{help}");
+    }
+}
+
 /// The roster enumerates every catalog agent by bus id (sorted), projects each one's presence, and —
 /// with enrich data — its inbox count and last-activity.
 #[test]