# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

The secrets vault's master-key handling is rebuilt to kill the recurring
"vault looks empty" disease (the 2026-06-05 bifurcation incident — CMT-1038):

1. **Per-agent keychain slots.** The master key now lives under
   `master-key:<stateDir>` instead of one machine-global slot shared by every
   agent. Agents still on the legacy slot adopt their key automatically on
   first read; nothing ever writes the global slot again.
2. **Self-describing vault format (v2).** New vault writes stamp an 8-byte
   key fingerprint into the header. A reader holding the wrong key gets a
   precise, named error ("encrypted with key id …; the vault is NOT empty")
   instead of silently treating the vault as empty. Old (v1) vaults read
   forever; the first write upgrades them.
3. **Dual-key reads + self-healing.** If the keychain and file keys diverge,
   readers try both; a fallback success is loudly reported and the next write
   converges the vault back to the primary key.
4. `GET /secrets/sync-status` now reports `vault: ok | empty | decrypt-failed`
   — decrypt failure is no longer masked as an empty key list.

Encryption itself (AES-256-GCM), vault location, and the tests-can't-touch-
the-real-keychain guard are unchanged.

## What to Tell Your User

Secrets you've handed me can no longer turn invisible because two parts of me
ended up holding different vault keys. If the keys ever drift, I keep reading
your secrets, log exactly what happened, and self-heal on the next write —
instead of asking you to send the secret again.

## Summary of New Capabilities

- Per-agent keychain accounts with automatic legacy adoption.
- v2 vault format with key fingerprint (wrong-key ≠ corruption ≠ empty).
- Dual-key read fallback + convergence-on-write.
- `vault` status on `GET /secrets/sync-status`.

## Evidence

`tests/unit/secret-store-key-coherence.test.ts` (11 new — including the
verbatim incident: a vault written with the file key stays readable when the
keychain key diverges, then converges on the next write) + 29 existing
secret-store tests + 21 secret-adjacent regression tests (store-first
integration, sealed-handoff at-rest, hardening, e2e) all green. tsc + lint
clean.
