Stopping workers¶
Sometimes you want a team's workers to stop picking up new work, or to save what they are doing and hand off. A stop signal does that. It covers one worker, a whole team or every worker on a host, and a person sets it and lifts it. Setting one can be refused, because a stop signal needs something on the worker's machine that can type the stop notice to it: the server refuses while a worker it would cover has nothing that can receive stop notices. This page explains what a stop signal is for, who may set one, what is law and what is how the shipped command-line tools behave today, so you know what a refusal means when you meet one.
Only people do this. Nobody sets these controls by prompting an agent: the agent-team MCP tools were disabled (hadron-server#3208, part of hadron-server#2937), and the controls live in the CLI, the GraphQL API and the portal. The portal has a Stops page for the App where a manager sets and lifts stop signals (hadron-portal#1406). If you want an agent to type a CLI command for you, Working through an agent says what that involves.
Pausing a worker's own wakes is a separate, older control and is described in What wakes a worker. A stop signal is set on a worker by someone else, and it does not replace that pause. Hadron once had a second control, an isolation for one worker; it was retired (hadron-server#2130, ruling A), and nothing here depends on it.
Stop signals¶
A stop signal tells covered workers to stop at one of three levels:
| Level | What it stops |
|---|---|
pause-dispatch |
New assignments. |
pause |
New assignments, and also ticks and stall time. |
halt |
Everything pause stops, plus an interrupt telling the worker to save its work and hand off. |
A signal's scope is one worker, a team (a head worker and the whole reporting tree under it, named by its head), or a host, which covers the workers registered on that machine. It lasts until it is lifted, or until an end time you give it.
Signals are independent. Setting one never replaces another, and lifting one never ends another. A worker covered by two signals stays covered until both are gone, so lifting the one you set may change nothing you can see.
Who may set and lift one¶
Whoever manages the App may set any level and scope, and lift any signal
(setting is Decided; who may lift is Proposed, as the next section says). A
host key may set a halt on its own host and lift it, and nothing else. A
worker's session has only the worker's own rights, so it is refused unless
the person who holds the worker has told it to act and that person manages the
App; the act is then recorded naming both. The CLI sends no such instruction,
so for the CLI a worker's session is refused. The server decides who may do
what and refuses the rest, so a command that comes back refused has not
changed anything.
What happens to a stop notice¶
Setting a signal records a stop notice for each covered worker. The
server's rules about notices are law, and they cite cor:agt:090:04:
- No notice interrupts, a
halt's included. Ahalt's notice is an ordinary notice typed into a verified-empty input, with no interrupt key. - A
haltnever discards a human's unsent draft. The notice is held, an event goes to the coordinator, and it is retried when the input is empty. - Notices skip the batching window and are never withheld by the daily wake budget.
- Setting a signal is refused with
STOP_SIGNAL_UNAVAILABLEuntil every worker it would cover is on a lane whose notice consumer declared itself within the last 600 seconds. A signal that is already set stays in effect if its consumer later lapses. The refusal lifts once every covered lane has a consumer; it is not a permanent block. - Listing and lifting signals always work, because neither stops anyone.
Typing the notice is done by the host's poller, hadron team host run, and
the law leaves that half to the tool: how a consumer types a notice, retries a
failed typing and acknowledges it is the host consumer's own contract, not yet
specified (hadron-server#2169). So the lines below are how the shipped CLI
behaves, not guarantees of the platform. They were checked against CLI
v0.44.0 (internal/delivery/wake.go, stop_outbox.go and
stop_reporter.go, and the hadron team host run and report-stops help).
The typing consumer first shipped in v0.37.0 (hadron-cli#1630, #1671).
- The poller types a notice only into an empty input. It writes one line
that starts
[hadron stop]. It does not type over a draft, and ahaltsends no interrupt key. - Delivery is at most once. The poller records a notice it typed before it acknowledges it, and does not type a recorded notice again. A notice it has not typed stays due.
- A
haltthe poller cannot type is reported, not typed. When the input holds a draft or a question, the screen is not recognized, the terminal has changed or there is no terminal, the poller logs the drop and writes it to a local outbox, and does not acknowledge the notice.hadron team host report-stopsthen posts one team-chat message per dropped notice, tagging the halted worker's reporting line (or the person holding it when it has none). That post is at most once per notice and is not exactly-once; run the command from a timer every few minutes. Apauseorpause-dispatchnotice that cannot be typed is not reported this way; it stays due and is typed on a later poll.
What has not been shown yet:
- Only scripted terminal proof exists. The consumer is live on the
orca1 host (rolled out 2026-11-05, per
cor:agt:090as read on 2026-11-13), but no real worker has been halted by it, and no real droppedhalthas been exercised. Read the limits above as behavior the tests and a scripted terminal show, not as something a livehalthas demonstrated. - A stored signal is not proof that a worker stopped or resumed. This page makes no promise that a worker obeys a notice; what the server keeps is the record of what was set, and a stop notice is a line typed to the worker.
How firm each rule is¶
The behavior above is built. How firmly each rule is settled differs, and this page keeps them apart. Citations are to the product specs; "unminted" means a draft not yet in the corpus.
- Decided (
cor:agt:090:06): an App manager sets any level and scope; a host key sets ahalton its own host only; a worker's session is refused. - Proposed (
cor:agt:090:06): that an App manager may lift any signal, that a host key may also lift its ownhalt, the typed refusal when a lift is not allowed, and the check made at write time. Read these as how the server behaves now. - Conditional, per
cor:agt:090:04:STOP_SIGNAL_UNAVAILABLEapplies only until every covered worker is on a lane with a recent notice-consumer declaration. It is not a permanent block. - Open: how a host consumer types, retries and acknowledges a notice is its own contract, not yet specified (hadron-server#2169), and what a worker does with a notice is up to the worker. No rule here promises that a worker obeys.
Commands¶
hadron team stop list, set and lift work with stop signals, in CLI
v0.33.0 and later. Their options are in the
CLI reference. The same operations are
the GraphQL teamStopSignals query and the setTeamStopSignal and
liftTeamStopSignal mutations. The host side, hadron team host run and
hadron team host report-stops, is in the
CLI reference.
Related¶
- What wakes a worker, the wakes these controls hold back, and the ticker templates that decide a new worker's schedule.
- Teams, workers, and sessions, on what a worker, a holder and a team are.
- Working through an agent.
hadron team stop, the stop signal commands.