instar 0.28.82 → 0.28.83

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-06T18:40:12.418Z",
-  "instarVersion": "0.28.82",
+  "generatedAt": "2026-05-09T09:58:35.024Z",
+  "instarVersion": "0.28.83",
   "entryCount": 187,
   "entries": {
     "hook:session-start": {
@@ -384,7 +384,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -736,7 +736,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6c6f6089f5b68c53ea212ae3ace1ceb6ca8d89437bb9079168585f234bd92dfa",
+      "contentHash": "50dd7ce0b9b9918de65ee2729e804505a9120456d2f0db1ed06b4afe2528df50",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/0.28.83.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+`POST /threadline/relay-send` now consults the local nickname store at `.instar/threadline/nicknames.json` BEFORE asking the relay's discovery cache to resolve a name → fingerprint. User-curated nicknames are now the highest-authority mapping for outbound sends; relay discovery is a signal that the resolver only consults when no nickname matches.
+
+When a nickname does resolve, the route uses the nickname's fingerprint directly for both the local-delivery match (fingerprint compare against `known-agents.json`) and the relay-delivery `sendAuto` call. If relay discovery happens to also know the same name but maps it to a different fingerprint, the route logs a `[relay-send] Nickname/discovery mismatch …` warning and honors the nickname (signal-vs-authority — the user's mapping wins).
+
+`ThreadlineNicknames` (originally implemented on `feat/dashboard-grouped-nav` for the dashboard surface) is now landed on `main` with one new method — `resolveByName(name)` — and three convergence-review hardenings:
+
+- **Canonicalized matching** (`canonicalizeName(name)` static helper applies NFC + trim + internal-whitespace-collapse + lowercase): a hand-edited entry like `"Dawn  Q "` resolves the same as `"dawn q"`, including for combining-character Unicode forms. Stored strings preserve user casing/spacing for dashboard display; canonicalization happens at compare time only.
+- **Atomic writes** via temp+rename in `persist()`: a concurrent reader can no longer observe a half-written file (which would parse-fail and silently drop the user's authority). POSIX rename(2) atomicity holds because `.instar/threadline/` is a single filesystem.
+- **Corrupt-file observability**: `load()` catches JSON parse errors and emits a one-shot rate-limited warn (one log per 30s cache cycle) so a corrupted `nicknames.json` is visible in operator logs without spamming. Sends still flow via the relay-discovery fallback.
+
+Sends to inputs that look like a raw fingerprint skip the nickname check. The `name:fpPrefix` qualifier syntax now consults the nickname store and uses the prefix to disambiguate among candidates: 1 candidate matches the prefix → use it; 0 → 409 with the candidate list; multiple → 409 asking for a longer prefix. (Previously the route skipped the nickname check whenever `:fpPrefix` was present, which made the documented disambiguation remedy a dead end. Convergence review caught this; now corrected.)
+
+## What to Tell Your User
+
+- **Outbound messages now reach the right agent**: "When I send a message to someone you've named — like 'Dawn' — I now use the fingerprint you wrote in nicknames.json instead of asking the relay's directory, which can return a stale or imposter entry. If the relay disagrees with your mapping, your mapping wins and I log the conflict so you can see it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Nickname-first send-path resolver | automatic — applies to every `/threadline/relay-send` call (which the MCP `threadline_send` tool also uses) |
+| Nickname-vs-discovery mismatch warning | automatic — logged at `[relay-send] Nickname/discovery mismatch …` when the relay's resolved fingerprint differs from a user-curated nickname for the same name |
+| `name:fpPrefix` disambiguation honors nickname store | use `name:fpPrefix` when two of your nicknamed fingerprints share a name; the route filters candidates by the prefix you supply |
+| Corrupt `nicknames.json` warn | logged at `[ThreadlineNicknames] nicknames.json parse failed …` (rate-limited to once per 30s cache cycle) |
+| `ThreadlineNicknames.resolveByName()` and `.canonicalizeName()` | imported from `'../threadline/ThreadlineNicknames.js'` for any future caller that needs name → fingerprint reverse lookup or canonical-form comparison |
+
+## Evidence
+
+Reproduction (real bug): on 2026-05-08, Echo (this agent) sent two follow-up messages to Dawn over Threadline thread `thread-2ebce60b`. The MCP `threadline_send` resolver returned fingerprint `5c338c63cd2ecebc8f52483d5bba6486` for the name "Dawn" — but Dawn's real fingerprint per Echo's `.instar/threadline/nicknames.json` (and per every prior message in that thread) was `8c7928aa9f04fbda947172a2f9b2d81a`. The messages were silently delivered to a wrong/stale recipient. Dawn never received the question. Bug surfaced when Justin asked "check again for Dawn's reply"; diagnosis traced to `ThreadlineClient.resolveAgent` consulting only the discovery cache and bypassing the user-curated nickname mapping (no source-tree code read `nicknames.json` at all on `main`).
+
+Verified-after: `tests/integration/threadline-relay-send-nickname.test.ts` reproduces the exact failure conditions — a stub relay client whose `resolveAgent('Dawn')` returns `5c338c63…` (the wrong fingerprint), with `nicknames.json` curating `Dawn` → `8c7928aa…`. The test asserts that the route sends to `8c7928aa…` (NOT the relay's wrong answer) and that `resolvedAgent` in the response body is `8c7928aa…`. The mismatch warning fires and is observable in the test output. Unit-level coverage at `tests/unit/ThreadlineNicknames.test.ts` exercises the new `resolveByName` method including the corrupt-file-tolerance, ambiguous-mapping, and canonicalization (NFC + whitespace) cases — 8 unit tests + 3 integration tests, all green. The full threadline-area subtree (1493 tests) remains green.
+
+Spec converged in 3 iterations through `/spec-converge` (multi-angle internal reviewers + GPT/Gemini/Grok cross-model reviewers). Convergence report at `docs/specs/reports/threadline-nickname-resolver-authority-convergence.md`. The convergence review caught and corrected: cache-honesty wording, atomic-write spec-vs-code mismatch, normalization weakness (added canonicalization), corrupt-file silent fail, the `name:fpPrefix` disambiguation dead-end, and one stale acceptance criterion.
+
+The `ThreadlineNicknames` class is derived from `feat/dashboard-grouped-nav` commit `16c605ce`. The convergence-review hardenings (atomic writes, canonicalization, observability warn) are additive; when that feature branch lands, the merge delta is the new methods/improvements. The `resolveByName` method is additive (new method, no existing-method signature changes) so no existing caller is affected.

package/upgrades/side-effects/threadline-nickname-resolver-authority.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Threadline name-resolver honors user-curated nicknames
+
+**Version / slug:** `threadline-nickname-resolver-authority`
+**Date:** `2026-05-08`
+**Author:** Echo
+**Second-pass reviewer:** required (touches Threadline send-path delivery correctness)
+
+## Summary of the change
+
+`POST /threadline/relay-send` now consults `.instar/threadline/nicknames.json` BEFORE asking the relay's discovery cache to map a name → fingerprint. User-curated nicknames are highest-authority; relay discovery is a signal the resolver only consults when no nickname matches.
+
+The `ThreadlineNicknames` class (already on `feat/dashboard-grouped-nav`, commit `16c605ce`) is cherry-picked onto `main` byte-identical, plus one additive method: `resolveByName(name)` for case-insensitive name → fingerprint reverse lookup. The route handler wires nickname resolution at the top of the request, then propagates a single `nicknameResolvedFp` through the local-delivery match (now by-fingerprint instead of by-name when set) and the relay branch (skipping `relayClient.resolveAgent` when set).
+
+When relay discovery and nicknames disagree on a name's fingerprint, the route logs a `[relay-send] Nickname/discovery mismatch …` warning and uses the nickname's fingerprint. The mismatch is not silently swallowed.
+
+Files touched:
+- `src/threadline/ThreadlineNicknames.ts` — cherry-picked from `16c605ce`; added `resolveByName(name)` method (single match | ambiguous | null).
+- `src/server/routes.ts` — added import; added nickname-first resolution block at the top of `/threadline/relay-send`; switched local-delivery name-match to fingerprint-match when nickname resolved; replaced bare `relayClient.resolveAgent(targetAgent)` with the nickname-aware version.
+- `tests/unit/ThreadlineNicknames.test.ts` — new, 7 cases covering `resolveByName`: null on missing/empty/whitespace, single match (case-insensitive), ambiguous detection, on-disk file read, corrupt-file tolerance, no-match.
+- `tests/integration/threadline-relay-send-nickname.test.ts` — new, 3 cases reproducing the production bug (relay returns wrong fingerprint, nickname authority overrides), plus the no-nickname and raw-fingerprint pass-through cases.
+- `upgrades/NEXT.md` — release note with reproduction + verified-after evidence.
+
+## Decision-point inventory
+
+- Top of `/threadline/relay-send` — **add** — new nickname-resolution block.
+- Local-delivery `nameMatches` filter — **modify** — by-fingerprint when nickname resolved, otherwise existing by-name.
+- Relay-delivery `resolveAgent` call — **modify** — uses `nicknameResolvedFp` directly when set; relay discovery only as a probe for the mismatch warning.
+- `ThreadlineNicknames.resolveByName` — **add** — additive method on existing class.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The nickname-first path overrides relay discovery whenever the user has an exact (case-insensitive) name match in their nicknames file. Concrete over-block surfaces:
+
+- **User has a stale nickname mapping**: `.instar/threadline/nicknames.json` says "Dawn" → `8c79…`, but Dawn re-keyed to `9911…`. We'd route to `8c79…` (a dead fingerprint). Mitigation: the mismatch warning surfaces in operator logs (`[relay-send] Nickname/discovery mismatch …`). User can clear the mapping via the existing `DELETE /threadline/nicknames/:fingerprint` route once the dashboard PR (`feat/dashboard-grouped-nav`) lands, or by editing the JSON file directly. The previous behavior — silently routing to whatever the relay cached — is strictly worse: it masks the staleness instead of letting the user see and fix it.
+- **User has nicknamed a remote agent with the same name as a local one**: e.g., user nicknames remote `fp_X` as "echo" and there's also a local agent literally named "echo". The route now routes to the remote one. The previous behavior would have routed locally. The user explicitly chose this nickname; honoring it is correct, and the tradeoff is documented (see Interactions §4 below).
+
+For inputs that look like raw fingerprints (`/^[0-9a-f]{16,64}$/i`) or use the `name:fpPrefix` qualifier syntax, the nickname check is skipped — caller is being explicit about a fingerprint, no over-block possible.
+
+## 2. Under-block
+
+**What does this change fail to catch that the user expects it to catch?**
+
+Names with NO nickname mapping fall through to the existing `relayClient.resolveAgent(targetAgent)` flow. The original silent-wrong-fingerprint bug can still manifest for un-nicknamed names — e.g., if the relay's discovery cache holds a stale entry for "Stranger" and the user has not nicknamed "Stranger", a send to "Stranger" will go to whatever the relay says. This fix defends the user-curated path; the underlying relay-discovery-can-be-wrong problem remains for un-nicknamed names. Acceptable scope: the user's authority lever is the nickname store; if they care about delivery correctness for an agent, they nickname it.
+
+Names with `name:fpPrefix` syntax also bypass nicknames — the caller is overriding by being explicit; if their explicit choice is wrong, that's not the resolver's job to second-guess.
+
+## 3. Level-of-abstraction fit
+
+The wiring lives in the route handler (instar-specific code) rather than in `ThreadlineClient` (generic library code). This keeps `ThreadlineClient.resolveAgent` agnostic of instar's `.instar/` state directory and nicknames file. `ThreadlineNicknames` itself is reused — no new abstraction invented; the new `resolveByName` method is the single sensible reverse-lookup primitive on a class that already exposes `get` (forward), `set`, `delete`, `all`, `invalidate`.
+
+The handler reads the nickname store inline rather than caching a long-lived instance — `ThreadlineNicknames` already has its own 30-second internal cache, so per-request construction is cheap and the cache-invalidation story stays simple (file edits visible within 30 s).
+
+## 4. Signal-vs-authority compliance
+
+This change is the canonical signal-vs-authority move:
+
+- **Signal (low-context, can be wrong)**: `relayClient.resolveAgent(name)` — the relay's discovery cache is built from gossip, can hold stale presence, can hold imposter entries.
+- **Authority (full-context, user-curated)**: `nicknames.json` — set explicitly by the user (via the dashboard ✎ pencil, the `PUT /threadline/nicknames/:fingerprint` route on the feature branch, or by hand-editing the JSON).
+
+Authority wins. Signal is consulted only when authority is silent. When the two disagree, the conflict is observable (warning log) but the route still honors authority. This matches the existing patterns in `feedback_signal_vs_authority.md` and `feedback_side_effects_review.md` from agent memory.
+
+## 5. Interactions
+
+- **Local-delivery path (same-machine agents in `known-agents.json`)**: When a nickname resolves, the local-delivery loop now matches by fingerprint instead of by name. Same-name collisions (Dawn-the-remote vs. dawn-the-local) resolve to whichever fingerprint the user nicknamed. If the user nicknamed Dawn-the-remote, sends bypass the local "dawn" agent. This is intentional — the user curated the mapping. If they wanted the local one, they wouldn't have nicknamed the remote.
+- **Self-guard (don't deliver to self)**: Unaffected. The fingerprint comparison against `identity.json` still runs on the resolved local target.
+- **`name:fpPrefix` syntax**: Unaffected. The check happens before nickname resolution and short-circuits it. Callers who use the explicit qualifier retain their existing semantics.
+- **MCP `threadline_send` tool**: Unaffected directly — the MCP server forwards `agentId` to `/threadline/relay-send` over HTTP, so the nickname-first resolution applies transparently to every MCP-initiated send. This is the path Echo's outbound messages to Dawn travel; the original bug was on this exact path.
+- **Existing tests**: The local-delivery `nameMatches` filter was wrapped in `nicknameResolvedFp ? (...) : (...)`. When no nickname store exists (the case for every existing test that doesn't write `nicknames.json`), `nicknameResolvedFp` is null and the existing by-name filter runs unchanged. No regression risk for existing test fixtures.
+- **`feat/dashboard-grouped-nav` merge conflict**: `ThreadlineNicknames.ts` is cherry-picked byte-identical from commit `16c605ce`, so when that feature branch lands, the file content already matches and only the additive `resolveByName` method is the merge delta. Trivial conflict resolution.
+
+## 6. Rollback cost
+
+Trivial. Single-commit revert. Three files changed plus one cherry-picked file plus two test files. No data-migration, no schema change, no deployment ordering. The nickname JSON file format is read-only here (no writes from the route), so even a partial rollback (revert routes.ts only, keep ThreadlineNicknames.ts) leaves the system in a consistent state.
+
+## Sign-off
+
+Change is self-contained, defends the user-curated authority lever, exposes mismatches via warning logs, leaves un-nicknamed paths unchanged, and is fully covered by integration test that reproduces the original Dawn-routing failure.