---
name: fleet-service-rename-cutover
description: "Rename a Dank-fleet LLM service end-to-end (repo trio, deployer keys, tags, hosts): the 2026-10-10 frank-archon/dragoon/zealot cutover procedure."
---

# Fleet service rename cutover (serverAppConfigs)

Procedure proven 2026-10-10 renaming the three LLM services to their wire
aliases (repo `55f87fc`). For any future full service rename.

## Repo codemod
1. `git mv` every tracked file whose path carries the old token
   (`frank-<old>` → `frank-<new>`, plus `frank_<old>` bats seams).
2. Content sweep over all tracked text files:
   `git grep -Ilz '' | xargs -0 sed -i` with expressions for
   `frank-<old>`, `FRANK_<OLD>`, `frank_<old>` → new forms; add the
   `LLM_<OLD>` / `llm_<old>` / handler-name forms in the same pass.
3. Known casualties to record: `scripts/patches/*.patch` context lines get
   rewritten (patches stop applying byte-exact); historical prose adopts
   the new name (one service, one name — Frank's rule).
4. Fix sed-made-contradictory lore by hand: AGENTS.md Model Config
   paragraph, any "keeps the old names" sentences. Do NOT enumerate the
   retired names anywhere — the acceptance test is
   `git grep -cE '<old forms>'` == 0 (case-insensitive too).
5. Rename rollback tags in lockstep (docs quote tag names):
   `git tag NEW OLD; git tag -d OLD`, push new, delete old refs on origin.
6. Sweep the harness config comments too: `~/.omp/agent/models.yml`.

## Deployer keying (why the sweep is safe)
`scripts/deploy-plan.py` SERVICE_ORDER/host sets + `services_for_path`
trio mapping; `scripts/deploy-remote.sh` `service_is_allowed` case,
`deploy_service` dispatch, `relink_unit <service>` (symlink
`/etc/systemd/system/<name>.service` → `scripts/<name>.service`),
markers keyed by service name under `~/.local/state/serverAppConfigs/
deploy-state/`. `add_pending_services` AUTO-TRASHES markers whose service
is retired — no marker surgery needed if you skip a full drain.

## Host cutover per endpoint (order matters)
1. `sudo systemctl stop <old>`; rename `~/logs/frank_<old>.log` → new;
   `podman rm -f` the old container name(s);
   `sudo rm` the unit symlink + `multi-user.target.wants/<old>.service`;
   `sudo systemctl daemon-reload`; trash the marker to
   `~/.AGENTTRASH/<date>-fleet-rename/` with a NEUTRAL filename.
2. `deploy.sh <host> --service <new-name>` (run from the main checkout;
   refuses on a worktree branch). The handler relinks under the new name,
   enables, restarts, health-gates.
3. Do the harness-default-model endpoint LAST on its host, and never stop
   an endpoint while a deploy on the other host is approaching its e2e
   gate (the gate probes the live fleet).

## Acceptance
`/health` 200 + `/v1/models` shows the new id (radiance echoes requested
names — verify on `/v1/models` only); unit active+enabled; new container
name running; `git grep` zero on every checkout; e2e gate green;
Prometheus job up (note: llama.cpp needs `--metrics` in the serve script
for the scrape — absence is a pre-existing gap, not a rename regression).
Out of scope: retired endpoint names (`frank-medium/small/npu`) and git
history — old strings there are expected.