A crew rename changes an existing identity. Write an explicit old-to-new mapping first, and read ~/VIBES.md and ~/PROJECT-NAMING.md. Crew names should be believable names or nicknames. Direct names from the reference shelf require an explicitly requested homage.
The 2026-10-11 migration was Zathras to Rivet, Ivanova to Voss, and Franklin to Mercer. Hailey kept her name. The accounts, credentials, endpoint IDs, queue scopes, route targets, and Crush session databases stayed in place.
Inventory and prepare
Record the supervisor names and states with harness --json list. Inspect the worker directories, their env, gitconfig, home/AGENTS.md, and home/crush.json. Inspect configuration without printing credentials.
Resolve each worker's forge user ID, Switchboard agent and endpoint IDs, Cairn token ID, and any owned repositories. Check that the new names do not already belong to someone else. Record active todo claims before stopping a worker; wait for work to finish or arrange recovery of its existing lease. An empty queue makes the cutover simpler.
Back up every file to be changed into a directory with mode 0700. Keep credential files and database backups private. Take a consistent database snapshot with the database's backup mechanism, and record the original identity rows and routing metadata. Save the supervisor's initial state.
Change the identity together
Stop the affected workers with harness stop <old-name>. Preserve the whole worker directory, including data/; rename it rather than creating a fresh agent. A symlink from the old path can keep existing scripts and stored session paths working during the transition.
Update these surfaces in one cutover:
- The harness table name, drop-in filename, descriptions, work directory, data directory, and environment-file path.
- The fixed callsign, git author and email, forge credential-helper login, environment variables, and cross-crew references in standing briefs.
- The existing forge account's login and display name, retaining its user ID, tokens, collaborators, reviews, and pull requests. Add a redirect from the former profile name. Inspect repository ownership before changing a login: owned repositories may also require supported path migration.
- The existing Switchboard agent name and any display labels in routing rules. Keep endpoint IDs, webhook IDs, queue scopes, and rule actions. Check trusted-actor allowlists if they match a login by name.
- The existing Cairn token's name, retaining its ID, hash, scopes, owner, and credential. Rename local token-record labels as well.
- The new
sbpush -to <name>selectors, health and restart notifications, scheduled sweep prompts, provisioning examples, and local documentation. Old destination selectors can remain aliases while callers migrate.
Endpoint URLs are opaque addresses. They can retain their original slugs; changing a crew name does not require rotating a credential or recreating an endpoint. Display names must come from the agent identity. Recreating an endpoint would separate the worker from its existing queue and routes.
Use supported account-management tools where available. The installed forge administrative CLI and edit-user API did not expose a login rename for the 2026-10-11 migration. That migration used a backed-up SQLite transaction on existing user rows and user_redirect, after confirming that the three accounts owned no repositories, then restarted Gitea. Switchboard agent names and Cairn token labels changed in PostgreSQL transactions. These were label changes only; IDs and credentials were preserved.
Update the public station record
Rename station/crew/<old-name>.md, including its title and prose. Update the matching sketch in the worker's brief, the station manual, operations page, and examples. Keep historical commit bylines and published case attribution as historical records.
The activity collector reads current names from agents.name, joined by endpoint ID. It must not infer a current identity from an old endpoint slug. Verify this with a fixture containing a new agent name and an old endpoint slug. Update ordering assertions when names change alphabetical order.
Publish the website change on a branch using the forge workflow. CI tests it, and a green merge to master deploys it. Check the live crew page, manual, and this procedure at /manual/renaming-agents/ after deployment.
Restart and verify
Run harness reload, then harness start <new-name> for each worker that was enabled before the cutover. Restart adjacent workers whose environment or MCP configuration changed. Their briefs must state the current fixed identity, even when earlier session messages use the previous name.
Verify all of the following before calling the rename complete:
- The supervisor lists the new names as running, without duplicate workers.
- Each existing forge token authenticates as the new login with the same user ID; old profile URLs redirect.
- Switchboard reports the new agent names and recent endpoint activity, with the same endpoint IDs, queue scopes, and route destinations.
- Existing Cairn credentials still authenticate, and new receipts use the current identity.
- Local git configuration, paths, briefs, sweep prompts, and destination selectors agree on the current names.
- Website collection and rendering succeed, required tests pass, and the deployed crew names and manual match the running station.
Check routing with its dry-run facility rather than sending work to the crew merely to test a rename. An existing endpoint's recent authenticated activity proves reconnection without creating a new task.
Rollback
Stop the renamed workers first. Reverse only this migration's identity changes, restore the saved configuration, remove transition symlinks before moving directories back, and restore the old harness drop-ins. Restore routing labels and aliases without changing endpoint or webhook IDs.
Reverse database label changes in transactions keyed by the saved IDs. Do not overwrite a live database with an old full snapshot after new work has arrived; that would discard unrelated work. A snapshot is for disaster recovery under a separately coordinated service stop.
Reload harness and restore the recorded enabled states. Recheck identities and endpoint activity. Revert the website commit through its normal CI publication path so the public record follows the running configuration.
For the 2026-10-11 rename, private configuration backups and the migration record are under ~/agents/artifacts/crew-rename-20261011/. Credentials in that directory must never be committed or published.