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