# Persistence and config changes

What survives what, and how a change to an agent's config reaches it.

## Persistence

The short answer to "does anything disappear": **destroying an agent
keeps its state, purging it doesn't.**

- **`DESTR0Y`** (the default action) stops and removes the container
  but keeps everything on disk — config history, claude login, `/state/`
  notes, harness data. The agent shows up as a tombstone (the K3PT ST4T3
  tab of the dashboard); `swarmctl agent create` with the same name and hive
  recreates it from the kept state, **no re-login needed**.
- **`PURG3`** (opt-in, from the dashboard or `hivectl agent <name>
destroy --purge`) is `DESTR0Y` plus wiping all of it — config
  history, claude credentials, `/state/` notes, everything. **No
  undo.** Only reach for this when you actually want the agent gone
  for good. The agent's matrix encryption keys go with the state dir,
  but an account whose key backup is on (see
  [matrix](../swarm/matrix.md)) gets them back from its
  homeserver when it next comes up, so its encrypted history stays
  readable.

Beyond that:

- **Broker messages**: acked ones vacuum after 30 days; anything
  undelivered or delivered-but-not-yet-acked is always kept, however
  old.
- **An agent's own `/state/` notes and claude login survive every
  restart and rebuild** — only an explicit purge (or a hive
  `--purge`-style host operation, or the agent's own choices) touches
  them.
- The **root/bootstrap agent has no guard**: destroying ruth is as final as
  for any agent, and she stays gone until you create her again from the
  swarm dashboard.

The tables, state directories, mounts and migrations behind this are in
[`persistence.md`](../../4-implementation/agent-state/persistence.md).

## Config changes

A config change is a pull request on the agent's config repo,
`agent-configs/<name>`. No tool exists for it: opening the PR is the request.

1. The agent clones its config repo, edits it (`agent.nix` is the entry point),
   pushes a branch and opens the PR with `hive-forge`. Branch protection lets it
   push branches but not `main`, so it **can't merge its own config PR**. An agent
   can propose a change to another agent's config the same way.
2. You review the PR on the forge, with its diff, comments and CI status, and
   merge it there. Merging needs membership of the `operators` team in
   `agent-configs`. The team starts empty: add each operator by hand in the forge
   UI.
3. The merge deploys. The swarm controller finds the hive that runs the agent and
   tells it to rebuild.

A merge runs **no evaluation check**. A merged config that doesn't evaluate or
build fails the rebuild, and the agent's rebuilds keep failing until a fix
merges. A failed rebuild shows on the hive like any other. A merge whose webhook
never reaches the controller deploys nothing.

You create a brand-new agent at swarm level (`swarmctl agent create`, or the
swarm UI), not from a hive. The controller seeds its config repo with a default
`agent.nix`, and every later change is a PR like any other. An agent created
from an [archetype](../swarm/archetypes.md) gets no config repo: the swarm builds
it from the archetype's module.

The full path, the meta flake, deploy markers, startup migrations, the root
container, the `system` messages hive-c0re sends and autoupdate:
[`config-changes.md`](../../4-implementation/agent-state/config-changes.md).