instar 1.3.276 → 1.3.277

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.276",
+  "version": "1.3.277",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T07:56:55.941Z",
-  "instarVersion": "1.3.276",
+  "generatedAt": "2026-06-05T08:15:17.647Z",
+  "instarVersion": "1.3.277",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "ebff9df80ee18fbb9a7a92fff3bca09a1db23ef357540f7afa7c1a768386e339",
+      "contentHash": "79a4439d7a02d91071447e360cc333379885f2dec5aa0e60045c2e49be336289",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.277.md

@@ -0,0 +1,50 @@
+# 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.

package/upgrades/side-effects/vault-key-coherence.md

@@ -0,0 +1,113 @@
+# Side-Effects Review — Vault key coherence (CMT-1038)
+
+**Version / slug:** `vault-key-coherence`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (crypto algorithm unchanged; resolution/format layers only; every boundary side test-pinned; v1 reads preserved; failure modes strictly improve on today's silent-empty)
+
+## Summary of the change
+
+Three layers killing the key-bifurcation disease: (1) per-agent keychain
+accounts (`master-key:<stateDir>`) with read-time adoption of the legacy
+global slot (which is never written again); (2) v2 store format with a keyId
+header (`'ISv2'|keyId(8)|iv|tag|ct`) so wrong-key is a precise, named error
+distinct from corruption — v1 files read forever; (3) dual-key read fallback
+(primary first, then the other source, read-only alternates) with a loud
+DegradationReporter on divergence and natural convergence on the next write.
+Plus: `GET /secrets/sync-status` now reports `vault: {status:'ok'|'empty'|
+'decrypt-failed', error?}` instead of masking decrypt-failure as empty.
+Keychain ops are injectable (`SecretStoreConfig.keychainOps`) so all of this
+is unit-tested against a fake; the #789 real-keychain test guard holds
+whenever no fake is injected.
+
+## Decision-point inventory (each side pinned)
+
+1. Per-agent slot present / legacy-only (adopt, global untouched) / neither
+   (generate → per-agent slot, NEVER global) — 3 tests.
+2. v2 keyId match / no-match (named error, "NOT empty") / matching-key
+   corruption (GCM auth error) — 3 tests.
+3. v1 primary-key read / v1 fallback-key read (THE incident case) /
+   write-after-fallback converges to primary / forceFileKey primary with
+   keychain alternate — 4 tests.
+4. Guard: no injected fake + VITEST ⇒ file-key only — 1 test.
+5. vaultStatus: ok / empty / decrypt-failed (route surface).
+
+## 1. Over-block
+
+Nothing readable today becomes unreadable: every key the old code could
+resolve is still a candidate, plus more. The new thrown errors fire ONLY
+where today's code also throws (v1, both keys wrong) or silently lied
+(reported empty); the route now reports those as `decrypt-failed` instead of
+`[]`.
+
+## 2. Under-block
+
+- The legacy global slot remains readable machine-wide until every agent
+  adopts — by design (deleting it would break un-migrated agents). It decays
+  naturally: nothing writes it, every reader adopts away from it.
+- Dual-key fallback widens which keys may open a vault to keys the SAME agent
+  resolves from ITS OWN two sources — no new principals, no cross-agent keys.
+- Convergence-on-write re-encrypts with the primary; if another process of
+  the same agent still resolves only the stale alternate, IT then uses its
+  own fallback (now in the other direction) and converges the same way — the
+  fixed point is both sources agreeing, reached after adoption.
+
+## 3. Level-of-abstraction fit
+
+Resolution lives in MasterKeyManager (the single key authority); format +
+fallback in SecretStore.read/write (the single at-rest codec); the route only
+gains a status field. Wire-sync crypto (X25519/HKDF) untouched.
+
+## 4. Signal vs authority compliance
+
+**Reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+No gating added. Errors got MORE precise; the degradation report is
+signal-only; adoption/convergence are self-healing writes within the agent's
+own key material.
+
+## 5. Interactions
+
+- Store-first drop persistence (#789), sealed-handoff at-rest, and the sync
+  provisioner all read through the same read() — regression suites green
+  (21/21).
+- Echo's live vault (v1, file-key, keychain slot deleted in the incident
+  remediation): reads via primary file key unchanged; first write upgrades to
+  v2 with the file keyId. No migration step needed anywhere — resolution-time
+  adoption + write-time format upgrade.
+- Mixed fleet versions: older readers can't read v2 — but a vault is only
+  read by ITS OWN agent on ITS OWN machine (wire sync re-encrypts per peer),
+  so the only mixed-version reader of a given file is the same agent
+  mid-update, which restarts onto the new code. Residual window ≈ one
+  restart; documented.
+
+## 6. External surfaces
+
+`vault` field on sync-status (additive); exported `perAgentKeychainAccount`/
+`keyIdOf` helpers; `SecretStoreConfig.keychainOps` (test seam). No config
+flags, no migration, no new routes.
+
+## 7. Rollback cost
+
+Revert restores old code — which reads v1 files only. Any vault already
+upgraded to v2 would need its 28-byte header stripped (`tail -c +13` of the
+post-magic body) — documented here as the rollback runbook; low likelihood
+(revert would only follow a fast-caught regression, before fleet-wide v2
+rewrites).
+
+## Conclusion
+
+The recurring "vault looks empty" disease removed at its three roots —
+shared slot, mute wrong-key failures, single-key reads — with strictly more
+diagnosable failure modes and zero operator action.
+
+## Second-pass review (if required)
+
+Not required — see header.
+
+## Evidence pointers
+
+- `tests/unit/secret-store-key-coherence.test.ts` (11, incl. THE incident
+  case verbatim and convergence-on-write).
+- `tests/unit/secret-store.test.ts` 29/29; secret-adjacent regression suites
+  21/21 (store-first integration + sealed-handoff + hardening + e2e).
+- `docs/specs/vault-key-coherence.md` + `.eli16.md`. <!-- tracked: CMT-1038 -->