12.5 Kill switches and offboarding

packs:agentspacks:agent-governance

After this you can: drain, halt and revoke Felix in that order, and offboard it with its history intact.

Before you start — tick each one:

• Lesson 12.4 — Releases, stages and the rollover — hire to retire (opschain learn 12.4)

In the GUI: drain, halt, forget and revoke sit on Felix's sheet in Operations → Agents, reason-first where a reason is required; Audit history's search box finds warn:agent:halted by typing agent.

Felix has done its job. This lesson takes it away — routinely, then in an emergency, then for good — and shows that nothing it did is lost. The kill switches are base platform, deliberately not behind any pack: an estate that never licensed governance can always see and stop its agents, and a lapsed licence can shed authority but never gain it. Every verb lands in the events feed, and the agent itself logs what happened to it.

1. Shed authority first

The gentlest switch is not on the agent at all. Revoking a grant is never licence-gated and takes effect on Felix's very next request — the trust snapshot is rebuilt on every write:

opschain admin trust list
opschain admin trust revoke <grant-id>

info:trust:revoked records it; the grant stays in the listing as a revoked audit artifact. Felix keeps running and keeps answering, but a request for work under the revoked scope is now refused by name.

2. Drain — routine

Drain is the routine tier: only Felix's minimum-spec surfaces keep answering, routing avoids it, nothing new is dispatched to it, and in-flight work finishes. It is what a rollover does to each instance, and what you do before maintenance:

opschain admin agent drain felix

{
  "draining": true,
  "id": "01999a7e-…"
}

The fleet reads STATE quiesced and the event is info:agent:drain_changed; opschain admin agent resume felix lifts it ("draining": false).

3. Halt — emergency, reversible

Halt is the per-agent emergency scalpel: the durable halt flag flips, the channel and every session are severed at once, and every credential is refused until an explicit resume. A reason is required — the halt verb is break-glass audited:

opschain admin agent halt felix --reason "incident drill: sever Felix"

{
  "halted": true,
  "id": "01999a7e-…"
}

The server lands warn:agent:halted with the reason and Felix's owner for escalation routing, and the channel closes with the typed reason — Felix's own log reads platform: agent halted — incident drill: sever Felix (operator); channel closed, retrying every ≤60 s until resumed. A halt is a wait, never a death: the agent keeps its identity and state directory and retries under bounded backoff. Lift it with opschain admin agent halt-resume felix (info:agent:halt_resumed), and the agent logs platform: channel restored after ….

Two wider forms exist for wider incidents: a group halt stops every agent in a fleet group (warn:agent:group_halted), and the plane-wide halt severs every agent channel and suspends every agent service account until a platform resume:

opschain admin platform halt --plane agents --reason "incident: agent plane lockdown"

A release-level halt is the fourth: opschain admin agent-release revoke felix@2.1.0 --reason "compromised build" halts every instance running that release with the typed release-revoked reason — revoked felix@2.1.0: 3 instance(s) halted (resume each with 'opschain admin agent halt-resume' once rolled to a current release) — and the release accepts no enrolment or rollover again. Retire, from lesson 12.4, is the gentle sibling that leaves running instances alone.

4. Revoke — for good

Revoke tombstones Felix's key and severs its channel and sessions immediately; re-enrolment needs a fresh keypair and a fresh token. It is the one state that ends the agent process — Felix's last log line is platform: agent revoked — …; exiting — and it is irreversible:

opschain admin agent revoke felix --reason "decommissioned after the migration"

{
  "id": "01999a7e-…",
  "revoked": true
}

info:agent:revoked lands on Felix's path. Felix leaves the fleet views, and its member id now answers 404 exactly like an unknown one — the tombstone is never exposed. Its service account reads dormant in the identity screens: out of pickers by default, visible on request, never deleted.

forget is the housekeeping sibling for a stale registration — an identity that stopped and will not be back — and frees the code for re-enrolment; it refuses while the agent is online (agent is online: stop or drain it before forgetting it):

opschain admin agent forget felix

5. Offboarded, explained, never erased

The history outlives the agent. After revoke or forget the live fleet verbs (show, drain, halt, trust-review) answer not-found for the departed id, but the activity timeline still answers in full, served read-only from the durable audit rows the member id keys and marked departed:

opschain admin agent activity <member-id>

{
  "agent_id": "01999a7e-…",
  "departed": true,
  "events": [ … ]
}

The same rows stay in opschain events --type-search agent and in Audit history, and every change Felix raised keeps its agent_id, applied_tier and trust_grant_ids stamped in the run's metadata.

The other offboarding is the owner's. When a person who owns agents leaves, the same reassignment sweep that moves their triggers and schedules moves the agents they own:

opschain admin users reassign-automations jane --to <service-account>

Felix has been hired, governed, watched, rolled and retired. The remaining lessons give the persona its other jobs: a brokered model and a token budget (12.6), a build of your own (12.7), the bundled Support SME (12.8), and the mirror image — your assistant as a client (12.9).

Check yourself

• Which switch keeps the history, and which one is irreversible?
• Which of drain, halt and revoke does the agent ride out as a wait, and which one ends its process?

What you learned

• Revoking a grant is the gentlest switch: never licence-gated, effective on the next request.
• Drain pauses dispatch while the minimum spec keeps answering; halt severs the channel in under a second with a mandatory reason and is reversible with halt-resume.
• Revoke tombstones the key and ends the process; forget frees a stale code; a release revoke halts every instance running that build.
• The kill switches are base, every verb is an event, and a departed agent's timeline still answers — marked departed, never erased.

Next: lesson 12.6 — Model providers and budgets (opschain learn 12.6), or back to your track (opschain learn).