swarm: named scheduled prompts for one or more agents, fired in each agent

swarm-controller keeps every scheduled prompt (id, name, agents, body,
anchor, interval, paused) as one document under one key of a new
`schedule-definitions` KV bucket, so each change is a single
compare-and-set and a prompt exists for all of its agents or none. It
writes each agent's key of a new `agent-schedules` bucket as the prompts
naming that agent, without names or other agents, after every change and
on a one-minute reconcile pass. It is the only writer of both, behind
GET/POST /api/schedules and PATCH/DELETE /api/schedules/{id}.
`swarmctl schedule add|list|edit|pause|resume|rm` drives those routes over
the controller socket.

An agent's own queue credential is granted one more subject, the direct
get of its own key in `agent-schedules`. A KV watch is not granted: its
consumer create subject carries no key, so it would cover every agent's.

hive-agent's new schedule ticker reads that key every 10 seconds and fires
due slots as the same `schedule:<id>` todo hive-c0re's worker pushes. Fire
times are anchor + k*interval; the last fired slot per schedule id is kept
in the state db, so a body edit or list refresh never moves or refires a
slot, downtime fires the latest missed slot once, a restart refires
nothing, a one-shot fires once, and paused slots are skipped.

Refs #4914

docs/tools/swarmctl-cli.md

@@ -9,6 +9,13 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl agent create`↴](#swarmctl-agent-create)
 * [`swarmctl agent mint-identity`↴](#swarmctl-agent-mint-identity)
 * [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token)
+* [`swarmctl schedule`↴](#swarmctl-schedule)
+* [`swarmctl schedule add`↴](#swarmctl-schedule-add)
+* [`swarmctl schedule list`↴](#swarmctl-schedule-list)
+* [`swarmctl schedule edit`↴](#swarmctl-schedule-edit)
+* [`swarmctl schedule pause`↴](#swarmctl-schedule-pause)
+* [`swarmctl schedule resume`↴](#swarmctl-schedule-resume)
+* [`swarmctl schedule rm`↴](#swarmctl-schedule-rm)
 * [`swarmctl user`↴](#swarmctl-user)
 * [`swarmctl user add`↴](#swarmctl-user-add)
 * [`swarmctl user reset-password`↴](#swarmctl-user-reset-password)
@@ -27,6 +34,7 @@ swarm-level operator CLI
 ###### **Subcommands:**
 
 * `agent` — Manage agents across the swarm
+* `schedule` — Manage scheduled prompts
 * `user` — Manage subjects in the swarm's SSO provider
 * `forge` — Manage human accounts on the swarm's forge
 * `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
@@ -129,6 +137,143 @@ Queues and returns, the same way `agent create` does — watch the swarm UI's jo
 
 
 
+## `swarmctl schedule`
+
+Manage scheduled prompts.
+
+The swarm keeps each prompt, and every agent it names fires it in its own container. Fire times are the schedule's start time plus whole intervals: changing the body never moves them, and an agent that was down fires the latest missed one once.
+
+**Usage:** `swarmctl schedule <COMMAND>`
+
+###### **Subcommands:**
+
+* `add` — Add a scheduled prompt and print it with its new id
+* `list` — List scheduled prompts, one row each, with their agents and next fire time
+* `edit` — Change a scheduled prompt
+* `pause` — Stop a scheduled prompt firing. Times that pass while it's paused aren't fired when it resumes
+* `resume` — Let a paused scheduled prompt fire again, from its next time on
+* `rm` — Remove a scheduled prompt from every agent it names
+
+
+
+## `swarmctl schedule add`
+
+Add a scheduled prompt and print it with its new id.
+
+Without `--every` it fires once. Without `--at` its first fire is now.
+
+**Usage:** `swarmctl schedule add [OPTIONS] --name <TEXT> --agent <AGENT> --body <TEXT>`
+
+###### **Options:**
+
+* `--name <TEXT>` — The prompt's title
+* `--agent <AGENT>` — Agent to fire it in. Repeatable; at least one
+* `--body <TEXT>` — The prompt, delivered to each agent verbatim
+* `--at <TIME>` — First fire time: an RFC 3339 time with its offset, such as `2026-10-05T09:00:00+02:00`, or unix seconds. Defaults to now
+* `--every <DURATION>` — Time between fires: a count with a unit of `s`, `m`, `h` or `d`, such as `1h` or `7d`. Leave out for a one-shot
+* `--paused` — Add it paused
+* `--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 schedule list`
+
+List scheduled prompts, one row each, with their agents and next fire time
+
+**Usage:** `swarmctl schedule list [OPTIONS]`
+
+###### **Options:**
+
+* `--agent <AGENT>` — Show only the prompts that fire in this agent
+* `--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 schedule edit`
+
+Change a scheduled prompt.
+
+Only the flags given change, and the id stays. `--at` and `--every` move the fire times; `--name`, `--body` and the agent flags don't.
+
+**Usage:** `swarmctl schedule edit [OPTIONS] <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — The prompt's id, as `schedule list` shows it
+
+###### **Options:**
+
+* `--name <TEXT>` — New title
+* `--body <TEXT>` — New prompt text
+* `--at <TIME>` — New first fire time, in the form `schedule add --at` takes
+* `--every <DURATION>` — New time between fires, in the form `schedule add --every` takes
+* `--once` — Make it a one-shot
+* `--add-agent <AGENT>` — Agent to start firing it in. Repeatable
+* `--remove-agent <AGENT>` — Agent to stop firing it in. Repeatable. Fails if the agent isn't a target, or if no agent would remain
+* `--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 schedule pause`
+
+Stop a scheduled prompt firing. Times that pass while it's paused aren't fired when it resumes
+
+**Usage:** `swarmctl schedule pause [OPTIONS] <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — The prompt's id, as `schedule list` shows it
+
+###### **Options:**
+
+* `--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 schedule resume`
+
+Let a paused scheduled prompt fire again, from its next time on
+
+**Usage:** `swarmctl schedule resume [OPTIONS] <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — The prompt's id, as `schedule list` shows it
+
+###### **Options:**
+
+* `--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 schedule rm`
+
+Remove a scheduled prompt from every agent it names
+
+**Usage:** `swarmctl schedule rm [OPTIONS] <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — The prompt's id, as `schedule list` shows it
+
+###### **Options:**
+
+* `--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 user`
 
 Manage subjects in the swarm's SSO provider