From cb2c90f32ef7ccca74b674108e5e7f4108e2e80c Mon Sep 17 00:00:00 2001 From: atlas Date: Sun, 13 Sep 2026 12:01:58 +0200 Subject: [PATCH] swarm: present tense + no-queue-coordinates wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The queue's payload ceiling was justified by what the queue was about to carry; it carries it now, so the comment says so. The other two sites say "a hive with no queue configured". The swarm has exactly one queue and a hive cannot lack it — only its coordinates, its credential, or its ability to reach it. That wording is already used everywhere else the absence is named; these two predate it. The docs section on the agents' queue coordinates stopped at delivering them and never said what the connection is for. It now names the subject and the degrade rule, which is the part an operator reading an agent's terminal at the swarm needs. Refs #3805 --- docs/swarm/README.md | 14 ++++++++++++++ hive-c0re/src/swarm_agent_status.rs | 2 +- hive-c0re/src/swarm_notices.rs | 4 ++-- nix/host-modules/swarm-nats.nix | 8 ++++---- 4 files changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/swarm/README.md b/docs/swarm/README.md index e67bd379..c09e404e 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -389,6 +389,20 @@ how it gets there. A hive that hasn't been given the queue's address for its agents sets none of the four and each agent logs that it has none; a half-set environment logs an error and the harness keeps serving. +What an agent does with that connection is publish its terminal. Every row its +own web UI renders also goes to `$SWARM.term..`, one subject per +agent, so a swarm-level terminal can follow one agent without subscribing to +the swarm's whole traffic. The `` is the one the agent's client id names, +which is the same string the broker builds its grant from. Publishing only: an +agent talks about itself here and reads nothing. Rows aren't retained — a +subscriber that wasn't listening missed them, the same as on the agent's own +live stream. + +A row too large for the queue's `max_payload` would be refused outright and +take the connection down with it, so the harness drops such a row's body before +sending and leaves a marker in its place; the summary, level and icon still +arrive. A row that's too large even without its body is logged and skipped. + ### Swarm-wide forge webhooks At startup the controller registers two Forgejo hooks pointing at diff --git a/hive-c0re/src/swarm_agent_status.rs b/hive-c0re/src/swarm_agent_status.rs index 2514927c..54dd1777 100644 --- a/hive-c0re/src/swarm_agent_status.rs +++ b/hive-c0re/src/swarm_agent_status.rs @@ -35,7 +35,7 @@ const FAILURES_BEFORE_BANNER: u32 = 3; /// /// Shares its connect gate with [`crate::swarm_status::spawn`] — both read /// `crate::swarm_queue::client()`, which connects once per process — so a -/// hive with no queue configured pays for this decision once, not twice. +/// hive with no queue coordinates pays for this decision once, not twice. /// /// Takes no `Coordinator` handle, unlike its sibling: this task only reads /// agent state that already exists on disk / in the container runtime diff --git a/hive-c0re/src/swarm_notices.rs b/hive-c0re/src/swarm_notices.rs index d2b9ceb4..914fcd70 100644 --- a/hive-c0re/src/swarm_notices.rs +++ b/hive-c0re/src/swarm_notices.rs @@ -13,8 +13,8 @@ //! [`swarm_queue_client::notices`] for the stream this publishes into. //! //! **Best-effort, never fatal to the caller.** A hive with no queue -//! configured is a silent no-op (the ordinary case). A hive whose queue -//! is unreachable loses the swarm's visibility of the notice, not the +//! coordinates is a silent no-op (the ordinary case). A hive that cannot +//! reach the queue loses the swarm's visibility of the notice, not the //! host's — `warn!` fires on every failed attempt regardless, and the //! dashboard banners only after [`FAILURES_BEFORE_BANNER`] consecutive //! misses, the same debounce shape [`crate::swarm_status`] uses and for diff --git a/nix/host-modules/swarm-nats.nix b/nix/host-modules/swarm-nats.nix index 134faf27..4541fef2 100644 --- a/nix/host-modules/swarm-nats.nix +++ b/nix/host-modules/swarm-nats.nix @@ -677,10 +677,10 @@ in # The most a single publish may be, in bytes, before the # server answers `-ERR 'Maximum Payload Violation'` and # closes the connection — not a truncation, a dropped row - # and a reconnect. This queue is about to carry agent - # terminal rows published whole rather than split, so - # upstream's own default is sized to lose one of those - # rather than merely shorten it. Bounded from above by + # and a reconnect. This queue carries agent terminal rows + # published whole rather than split, so upstream's own + # default is sized to lose one of those rather than merely + # shorten it. Bounded from above by # `max_pending`: nats-server refuses to start once this # exceeds it, and widening that ceiling instead costs # memory per connection, so this stays comfortably under it.