hive-sh4re + docs: extract AgentMeta wire-shape prose (#717 batch 8)

docs/conventions.md

@@ -196,6 +196,39 @@ transitions the row to `ApprovalStatus::Cancelled` and fires
 `ApprovalResolved { status: "cancelled" }` so the dashboard pulls
 the card out of the pending pane.
 
+### Agent metadata
+
+`AgentRequest::GetAgentMeta { name }` returns identity + status for
+an agent. Self-introspection when `name = None` (replaces the older
+`Whoami` request); target query when `name = Some`. The
+manager-flavour mirror has the same shape.
+
+Response is `AgentMeta { name, role, running, hyperhive_rev,
+status_text, status_set_at, hive_name, swarm_name }`:
+
+- `role`: best-effort — `"manager"` for the manager agent,
+  `"agent"` for everyone else. Reflects the responding daemon's
+  view (the host-side flavour can't always introspect the target's
+  config).
+- `hyperhive_rev`: `None` only when the configured flake URL has
+  no canonical path. Otherwise carries the rev the target is
+  currently pinned at.
+- `running`: whether the target's container is currently up. When
+  `false`, the host clears `status_text` / `status_set_at` —
+  on-disk values from before the stop are stale snapshots and
+  shouldn't be shown as live status. Defaults to `true` on the
+  wire (older harnesses never serialised it, and the host only
+  knew how to ask about live containers — keeps backwards-compat
+  with pre-running-field payloads).
+- `status_text` / `status_set_at`: last value written via
+  `SetStatus`, plus its unix timestamp. Both `None` when the
+  target has never set a status, when the agent name is unknown,
+  or when `running = false` (see above).
+- `hive_name` / `swarm_name`: display names read from
+  `HYPERHIVE_HIVE_NAME` / `HYPERHIVE_SWARM_NAME` env (sourced from
+  `services.hyperhive.hiveName` / `services.hyperhive.swarmName`).
+  Both `None` when the options aren't configured.
+
 ## Async forms
 
 Dashboard + per-agent mutating forms carry `data-async`; a delegated

hive-sh4re/src/lib.rs

@@ -389,15 +389,9 @@ pub enum AgentRequest {
     /// to `{state_dir}/hyperhive-status` so it survives harness restarts.
     /// Pass an empty string to clear the status.
     SetStatus { text: String },
-    /// Fetch metadata for an agent: identity (name + role + hyperhive
-    /// rev) and current status. When `name` is `None` the caller's own
-    /// identity is returned (self-introspection — replaces the old
-    /// `Whoami` request). When `name` is `Some`, the target agent's
-    /// status fields are populated but `role`/`hyperhive_rev` reflect
-    /// the responding daemon's view (`role` is best-effort: `"manager"`
-    /// for the manager agent, `"agent"` for everyone else).
-    /// `status_text` / `status_set_at` are `None` when the target has
-    /// never set a status or the agent name is unknown.
+    /// Fetch identity + status for an agent. `name = None` =
+    /// self-introspection; `Some(<agent>)` = target query. See
+    /// `docs/conventions.md::Agent metadata`.
     GetAgentMeta {
         #[serde(default, skip_serializing_if = "Option::is_none")]
         name: Option<String>,
@@ -446,18 +440,8 @@ pub enum AgentResponse {
     PendingRemindersCount { count: u64 },
     /// `ReminderRollup` result: reminder activity stats for the agent.
     ReminderRollup(ReminderStats),
-    /// `GetAgentMeta` result: identity + status metadata for an agent.
-    /// `role` is `"agent"` for sub-agents and `"manager"` for the
-    /// manager. `hyperhive_rev` is `None` only when the configured
-    /// flake URL has no canonical path. `running` reflects whether the
-    /// target's container is currently up (#432); when it's false,
-    /// `status_text` / `status_set_at` are intentionally cleared by the
-    /// host because the on-disk values are stale snapshots from before
-    /// the stop. `status_text` is the last value written via
-    /// `SetStatus`, or `None` when none has been set or the agent name
-    /// is unknown. `status_set_at` is a Unix timestamp (seconds since
-    /// epoch) of when the status was last written; `None` when no
-    /// status is set.
+    /// `GetAgentMeta` result. Per-field semantics + serde defaults
+    /// live in `docs/conventions.md::Agent metadata`.
     AgentMeta {
         name: String,
         role: String,
@@ -469,24 +453,16 @@ pub enum AgentResponse {
         status_text: Option<String>,
         #[serde(default, skip_serializing_if = "Option::is_none")]
         status_set_at: Option<i64>,
-        /// Hive display name (#701 / #710) — e.g. `"pr1ma"`. Host
-        /// reads from its own `HYPERHIVE_HIVE_NAME` env (set by
-        /// `services.hyperhive.hiveName`); `None` when the option
-        /// isn't configured.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         hive_name: Option<String>,
-        /// Swarm display name (#701 / #710) — e.g. `"constellat1on"`.
-        /// Source mirrors `hive_name` (`HYPERHIVE_SWARM_NAME` env /
-        /// `services.hyperhive.swarmName`).
         #[serde(default, skip_serializing_if = "Option::is_none")]
         swarm_name: Option<String>,
     },
 }
 
-/// Serde default for the `running` field on legacy wire payloads that
-/// predate #432 — older harnesses never serialised it, and `true`
-/// matches the historical assumption (the host only knew how to ask
-/// about live containers).
+/// Serde default for the `running` field; keeps wire backwards-compat
+/// with pre-running-field payloads. See
+/// `docs/conventions.md::Agent metadata`.
 fn default_true() -> bool {
     true
 }
@@ -744,8 +720,7 @@ pub enum ManagerRequest {
     /// Mirror of `AgentRequest::SetStatus` on the manager surface.
     SetStatus { text: String },
     /// Mirror of `AgentRequest::GetAgentMeta` on the manager surface.
-    /// `None` returns the manager's own identity (replaces the old
-    /// `Whoami` request).
+    /// See `docs/conventions.md::Agent metadata`.
     GetAgentMeta {
         #[serde(default, skip_serializing_if = "Option::is_none")]
         name: Option<String>,
@@ -950,11 +925,7 @@ pub enum ManagerResponse {
     /// `ReminderRollup` result: reminder activity stats for the manager.
     ReminderRollup(ReminderStats),
     /// Mirror of `AgentResponse::AgentMeta` on the manager surface.
-    /// `role` is `"manager"` for the manager and `"agent"` for any
-    /// sub-agent looked up by name. `running` is false when the
-    /// target's container is stopped (#432) — in that case
-    /// `status_text` / `status_set_at` are cleared by the host so
-    /// stale pre-stop values don't leak through.
+    /// See `docs/conventions.md::Agent metadata`.
     AgentMeta {
         name: String,
         role: String,
@@ -966,13 +937,8 @@ pub enum ManagerResponse {
         status_text: Option<String>,
         #[serde(default, skip_serializing_if = "Option::is_none")]
         status_set_at: Option<i64>,
-        /// Hive display name (#701 / #710), same source + semantics
-        /// as on `AgentResponse::AgentMeta`. Read from the host's
-        /// `HYPERHIVE_HIVE_NAME` env so manager + agent surfaces
-        /// return the same view.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         hive_name: Option<String>,
-        /// Swarm display name (#701 / #710), mirror of `hive_name`.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         swarm_name: Option<String>,
     },