swarmctl: agent set-state declares an agent's wanted state

Wraps PUT /api/hives/{hive}/agents/{agent}/state, the route the swarm UI's
state menu uses. States come from swarm_wire::wanted::AgentState; destroyed
needs --yes.

Closes #6159

docs/2-handbook/reference/swarmctl-cli.md

@@ -8,6 +8,7 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl agent`↴](#swarmctl-agent)
 * [`swarmctl agent create`↴](#swarmctl-agent-create)
 * [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token)
+* [`swarmctl agent set-state`↴](#swarmctl-agent-set-state)
 * [`swarmctl agent inference`↴](#swarmctl-agent-inference)
 * [`swarmctl agent inference get`↴](#swarmctl-agent-inference-get)
 * [`swarmctl agent inference set`↴](#swarmctl-agent-inference-set)
@@ -72,6 +73,7 @@ Manage agents across the swarm
 
 * `create` — Queue creation of a new agent on a hive in this swarm
 * `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
+* `set-state` — Declare the state a hive converges an agent to: `up`, `offline`, `paused` or `destroyed`
 * `inference` — Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models
 * `permissions` — Show or change the permissions the swarm grants an agent
 * `agents-md` — Show an agent's AGENTS.md, or edit it with a diff
@@ -132,6 +134,33 @@ Queues and returns, the same way `agent create` does — watch the swarm UI's jo
 
 
 
+## `swarmctl agent set-state`
+
+Declare the state a hive converges an agent to: `up`, `offline`, `paused` or `destroyed`.
+
+Writes the swarm's declaration for the agent, the one the swarm UI's state menu writes, and returns once the controller has published it; the hive converges on its own clock. The swarm must already know the agent on `--hive`: this never creates one.
+
+`destroyed` can't be undone, so it needs `--yes`.
+
+No approval gate guards this: the caller is root on the controller's host, or logged in through the swarm domain's SSO gate.
+
+**Usage:** `swarmctl agent set-state [OPTIONS] --hive <HIVE> <AGENT> <STATE>`
+
+###### **Arguments:**
+
+* `<AGENT>` — Agent name
+* `<STATE>` — The state to declare: `up`, `offline`, `paused` or `destroyed`
+
+###### **Options:**
+
+* `--hive <HIVE>` — The hive that runs the agent
+* `--yes` — Confirm `destroyed`, which can't be undone
+* `--controller-socket <PATH>` — swarm-controller's unix socket.
+
+   Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
+
+
+
 ## `swarmctl agent inference`
 
 Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models.