---
name: omp-model-id-rename-cutover
description: Rename an OMP fleet model id in models.yml and prove every reference and endpoint still resolves before commit/push.
---

# OMP model id rename cutover

Renaming a model id in `~/.omp/agent/models.yml` touches three layers: the registry, every
reference in `agent/config.yml`, and the wire contract with the serving endpoint.

## 1. Find every reference
Provider names are labels; ids are referenced from `config.yml` (`modelRoles.*`,
`task.agentModelOverrides.*`, `compaction.modes`), from other models' `compactionModel`,
and from docs/memory. Grep the tracked set:

```bash
git ls-files -z | xargs -0 grep -ln 'OLD_ID'
```

`agent/memories/**` and `omp-docs/log.md` are historical records: leave them alone.
`agent/models.yml` comments that name the *service* (e.g. `frank-large.env`) stay — the
systemd unit names do not change with the harness id.

## 2. Prove reference integrity (throwaway, do not commit)
Parse both YAMLs and cross-check. The provider label contains a space and parentheses
(`llamacpp (dankserver)`), so use an explicit pattern; a `split(/\s+/)` yields false
unresolved hits like `(dankclaw)/frank-dragoon`.

```python
pat = re.compile(r"llamacpp \([^)]+\)/[A-Za-z0-9._-]+")
known = {f"{n}/{m['id']}" for n, pv in models["providers"].items() for m in pv["models"]}
# walk cfg.modelRoles / cfg.task / compactionModel, flag tokens not in known
```

Expect: zero unresolved refs, and every `compactionModel` present in `known`.

## 3. Prove the endpoint accepts the new id
`/v1/models` reports the SERVED name (radiance echoes the request id, halogen and
llama.cpp echo their own). Then send a 4-token completion with the NEW id against each
provider `baseUrl`:

```bash
curl -s http://HOST:PORT/v1/chat/completions -H 'content-type: application/json' \
  -d '{"model":"NEW_ID","messages":[{"role":"user","content":"say OK"}],"max_tokens":4}'
```

200 + `reasoning_content` = the rename is harness-side only. All three engines on the
Dank fleet ignore the request `model` field.

## 4. Fit check against the served window
Read the served window (`/v1/models` → `context_length` / `meta.n_ctx`) and confirm the
declared `contextWindow + maxTokens` fits the slot/pool the engine admits against.
Compaction fires at `compaction.thresholdPercent` of `contextWindow`; the clamp is
`max_tokens = min(maxTokens, contextWindow − est − 4096)` and the chars/4 estimate
under-runs ~3 % on code.

## 5. Commit shape
One commit for `models.yml` (ids + windows + sampling), one for `config.yml` (role map,
compaction endpoint). Note in the message which wire names stay unchanged, and record
the rename in `omp-docs/log.md` (newest section first). Run `scripts/kb-lint.sh` before
committing docs. The `.githooks/pre-commit` secret gate runs automatically; never
`--no-verify`.