id: e-stop title: An operator can halt the swarm when nothing else is working status: open crates: [didbot-serve, didbot-pds] dependsOn: [] exitCriterion: > A signed-in operator halts all provisioning and every token this server checks, from the dashboard or from a shell, and can see what is being refused. #

e-stop #

Two settings, because they answer different questions. Pause refuses every token, new or already issued, and all provisioning, and ends nothing: releasing it lets every token work again. Revoke refuses the same and ends every token already issued, which releasing it does not undo. A service-auth token is the exception to both: either setting refuses every new one and every proxied call, but one already minted works at the service it names until its exp, at most an hour, or a minute for the ones the proxy mints.

The reason this is its own epic is immediacy, not mechanism. Policy lives in the operator's repository and arrives on a poll, so a policy-level stop waits for a network, a server somebody else runs, and an interval. That is correct for a rule and useless for an emergency. The stop is local state, and it is the only control that is.

One way to throw it, reached two ways: an operator signs in and presses it, from the dashboard or from a shell, both over the same route. A host-level stop is systemctl stop, which stops strictly more.

• Scope it narrower than everything. The latch has one setting for the whole deployment. What exists beside it: a lock on an account (didbot_pds::lockout) stops that account, including creating beneath itself; deleting the operator's record for a root pauses the root and everything beneath it at the next poll after the grace window; and stopping one app is app-allowlist's, a policy edit consulted in process at every pushed authorization request. Whether any of those belongs on this latch, with its immediacy, is open.

Done #

• One way to throw it, reached two ways. didbot_pds::Estop is the latch; POST /dashboard/api/estop/throw and .../release are the route, behind the operator sign-in in didbot_serve::operator, and didbot estop --pause|--revoke|--release is the same route from a shell. The throw checks ServerPolicy::may_halt, so a server that has not finished arriving still refuses one.
• A latch both gates read, at issuance and at the write. didbot_pds::Estop::check_issue gates POST /oauth/token and bot.did.createAccount; Estop::check_use gates every repository write route and uploadBlob, checked fresh on every request rather than cached.
• Say what it is refusing. Estop::status reports tokens, operations and accounts refused since the latch last engaged, reset when it clears, and Cause says whether an operator threw it or the server did.
• Log each throw and release. One info line per change to a latch, naming the mode and whose latch it is; the dashboard's routes, which didbot estop calls too, add the operator's DID through a span.
• Tell agents distinctly. A halted request answers 503 Halted with a message naming whose latch it is. An operator's stop is not a transient failure, and retrying will not help. This server's own pause names the operator's missing record and clears when it is back: didbot_pds::Halted carries the Cause, and its ApiError mapping words the message by it.
• Pause and Revoke as distinct settings, with Pause refusing every token until it is released and ending none, and Revoke ending them, so releasing a Revoke does not resurrect what it ended (Mode and revoke_hook in crates/didbot-pds/src/estop.rs, and crates/didbot-serve/tests/write_gates.rs).
• A restart comes back to the latch the operator left. A --data run writes both latches to pds.estop on every throw and release, before a Revoke's teardown starts, and a restored Revoke runs its teardown again — Estop::kept_in and crates/didbot-pds/tests/estop_restart.rs.