box/docs/UUID-ROTATION.md

# Thread-UUID rotation: measurement & mapping hygiene proposal

Date: 2026-10-04. Source: `dm-log.jsonl` (window 2026-10-03 21:36Z → 2026-10-04 19:46Z,
~22h, 3318 lines — the log does not cover a full 7 days; rates below are
extrapolated from this window and should be re-measured on a longer one).
Read-only analysis; no code changed.

## 1. Measured rotation per alias

Two distinct phenomena share the symptom "alias → different UUID":

- **(A) Real thread death/rotation.** The SPA retires threads. Observed earlier
  for heartbeat-opm (5bd5b350 → 0077e918 → dead, twice in one day, per operator
  notes; predates this log window).
- **(B) Fuzzy-search nondeterminism.** `sidechat use "<name>"` scans every DOM
  element for `textContent.includes(name)`, picks the shortest match, and clicks
  it (`muse-chat-api.py: cmd_sidechat_use`). The candidate set changes between
  React renders, so the same alias resolves to different live threads run to run
  — with no thread dying at all.

| alias | distinct UUIDs (window) | autoprovisioned (real rotations) | send-target flaps (fuzzy) | changes/day* |
|---|---|---|---|---|
| heartbeat | 4 (5f18476d, 1e75a740, 0077e918, …) | 0 | 3 | ~3.3 flap |
| 646 tasks | 4 (1e75a740, a7d0b08a, 1dfb3199) | 1 (18:30 → 1dfb3199) | 2 | ~1.1 real, ~2.2 flap |
| 646-pip | 2 (82779e55 → 75feb3a2) | 1 (18:01) | 0 | ~1.1 real |
| ops-audit | 2 (75feb3a2 → 34a8a87c) | 1 (19:28) | 0 | ~1.1 real |
| main-loop brain | 1 (5f18476d) | 0 | — | collision, see §3 |
| pipe-* (6 aliases) | 1 each | 1 each (creation) | 0 | 0 post-creation |
| 646-pip-coord | 1 (4466d0c1) | 0 | 0 | 0 |
| 646-opm-coord | 1 (4139dd4e) | 0 | 0 | 0 |

\* changes/day extrapolated from ~22h window; demo-day traffic inflates flaps.

Smoking gun for (B): at 16:25:53 a `super`→646 send for "646 tasks" landed on
a7d0b08a, and 52 seconds later an `opm`→646 send for the same alias in the same
recipient browser landed on 1e75a740. No thread died in between — the fuzzy
search is nondeterministic across runs.

## 2. Who writes / reads job-sidechats.json today

Writers:
- `dm.py` autoprovision path only (atomic tmp+mv write of
  `{thread_uuid, agent, created_at}` on `sidechat_autoprovisioned`).
- Manual edits (e.g. today's removal of stale heartbeat-opm / pipe-9735f2).

NOT writers:
- The new sweeper thread_uuid backfill (workstream 1) writes **followups.json
  only** — it does not refresh job-sidechats.json.
- `thread_lifecycle.py` exists but is marked "prototype, not deployed".

Readers: `dm.py resolve_sidechat_target` (exact key match → UUID, else
passthrough to fuzzy search), harvester/siphon (monitor list), box-ctl,
job-dispatch, super-cli.

Critical gap in the refresh story: a **dead mapped UUID does not self-heal**.
`sidechat use <dead-uuid>` → SPA redirects to `/` → output is
"Navigated to: https://muse.ai/" (not NOTFOUND) → `nav_failed no_thread_url` →
hard fail. Autoprovision only fires on NOTFOUND from *name* search. So a dead
mapping = permanent send failures for that alias until a human removes the
entry. (This is fail-closed, not misdelivery — but it is not self-healing.)

Second gap: an **unmapped alias whose fuzzy search keeps "succeeding" never
autoprovision** and therefore never earns a canonical mapping — it flaps
forever. This is heartbeat's exact situation right now (see §3).

## 3. Flags

- **MISSING mapping, highest churn: `heartbeat`.** 4 UUIDs in 3h, zero
  autoprovision events, no entry in job-sidechats.json (the old `heartbeat-opm`
  entry was removed during today's hardcoded-alias cleanup). Every send does a
  fresh fuzzy search. At 16:45 a heartbeat send landed on 1e75a740 — 646 tasks'
  thread. **Misdelivery already happened here.**
- **MISSING mapping: `ops-audit`.** Re-provisioned 19:28 (34a8a87c) but the
  alias was never registered; next fuzzy search may flap.
- **COLLISION, unverified: `main-loop brain` → 5f18476d.** The brain's init
  send (19:40) fuzzy-matched into 5f18476d — the same thread heartbeat used at
  16:35 and 19:41. No `sidechat_autoprovisioned` event for the brain alias, so
  no new thread was created. Either the fuzzy search false-positived into
  heartbeat's thread, or the brain was deliberately placed there. **Confirm
  intent — if unintended, digests and heartbeat traffic are cross-talking.**
- **No current mapping points to a UUID superseded by a newer autoprovision
  for the same alias** — all 11 entries match their alias's latest
  autoprovision event. Nothing stale in that narrow sense.
- **Aging, low-risk:** `test-auto-prov` (last confirmed 16:20), `646-opm-coord`
  (last confirmed 12:52), and six single-use `pipe-*` demo entries accumulate
  with no TTL. Harmless today, cruft tomorrow.
- **Confounder:** as of ~19:43Z all four chromebox browsers are flapping
  (dying every 10–15 min, no crash signature). Nav flakiness measured today is
  polluted by this; re-measure rotation after the browsers stabilize.

## 4. Proposal: mapping hygiene

1. **Canonical entry for every recurring alias.** `heartbeat`, `ops-audit`,
   `main-loop brain` (once its thread is confirmed), `646 tasks`, `646-pip`,
   `646-pip-coord`, `646-opm-coord` must each have exactly one entry, created
   by explicit provisioning — never by fuzzy luck. Unmapped + fuzzy-matched is
   the misdelivery configuration; it should be treated as a bug, not a
   fallback.
2. **Dead-UUID reprovisioning.** On `no_thread_url` / `uuid_mismatch` where
   the nav target came from a *mapping* (source == `dynamic_mapping`), fall
   through to autoprovision and overwrite the mapping — the same path name
   search uses today. This closes the "dead mapping = permanent failure" gap
   and makes rotation self-healing. (Keep failing closed when even
   autoprovision can't produce a thread page.)
3. **Exact-match-first fuzzy search.** Before the DOM substring scan,
   `sidechat use` should try an exact title match (normalized case/space).
   Only fall back to substring on no exact hit. This kills most cross-alias
   false positives (the 16:45 heartbeat→646-tasks landing) without changing
   the autoprovision contract.
4. **TTL + audit job.** Add `last_confirmed_at` to each mapping entry, refreshed
   on every successful send through it. A periodic audit (daily is plenty;
   weekly at minimum) flags: entries unconfirmed > TTL (7d job, 24h heartbeat),
   aliases seen in dm-log with no entry, and UUIDs serving >1 alias
   (collision detector — would have caught 1e75a740 and 5f18476d). Report-only
   at first; auto-prune single-use `pipe-*`/test entries after TTL.
5. **Sweeper backfill → also refresh the mapping.** The workstream-1 backfill
   already learns the live UUID per followup; writing it through to
   job-sidechats.json when the followup's target is a mapped alias is nearly
   free and covers the "nudge provisioned a thread dm.py didn't" case.
6. **Do not reintroduce hardcoded UUIDs** (the empty `SIDCHAT_ALIASES` was the
   right call). The mapping file is the single source of truth; the audit job
   in (4) is what keeps it honest.

## 5. Suggested next steps (no code in this workstream)

- Confirm `main-loop brain` thread intent (collision with heartbeat's 5f18476d).
- Provision canonical threads for `heartbeat` and `ops-audit`; register them.
- Implement proposal items 2 and 3 (dm.py + muse-chat-api.py — small, surgical).
- Stand up the audit job (4) as report-only; review one week of flags before
  enabling any auto-prune.
- Re-run this measurement on a 7-day dm-log window once rotation stabilizes
  post-browser-flap.