@vellumai/assistant 0.9.0 → 0.9.1-staging.1

package/src/config/bundled-tool-registry.ts

@@ -24,7 +24,7 @@ import * as appCreate from "./bundled-skills/app-builder/tools/app-create.js";
 import * as appDelete from "./bundled-skills/app-builder/tools/app-delete.js";
 import * as appGenerateIcon from "./bundled-skills/app-builder/tools/app-generate-icon.js";
 import * as appList from "./bundled-skills/app-builder/tools/app-list.js";
-import * as appBuilder_appRefresh from "./bundled-skills/app-builder/tools/app-refresh.js";
+import * as appRefresh from "./bundled-skills/app-builder/tools/app-refresh.js";
 import * as appUpdate from "./bundled-skills/app-builder/tools/app-update.js";
 // ── app-control ────────────────────────────────────────────────────────────────
 import * as appControlClick from "./bundled-skills/app-control/tools/app-control-click.js";
@@ -88,8 +88,6 @@ import * as messagingRead from "./bundled-skills/messaging/tools/messaging-read.
 import * as messagingSearch from "./bundled-skills/messaging/tools/messaging-search.js";
 import * as messagingSend from "./bundled-skills/messaging/tools/messaging-send.js";
 import * as messagingSenderDigest from "./bundled-skills/messaging/tools/messaging-sender-digest.js";
-// ── personal-page ──────────────────────────────────────────────────────────────
-import * as personalPage_appRefresh from "./bundled-skills/personal-page/tools/app-refresh.js";
 // ── phone-calls ────────────────────────────────────────────────────────────────
 import * as callEnd from "./bundled-skills/phone-calls/tools/call-end.js";
 import * as callStart from "./bundled-skills/phone-calls/tools/call-start.js";
@@ -148,7 +146,7 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["app-builder:tools/app-create.ts", appCreate],
   ["app-builder:tools/app-update.ts", appUpdate],
   ["app-builder:tools/app-delete.ts", appDelete],
-  ["app-builder:tools/app-refresh.ts", appBuilder_appRefresh],
+  ["app-builder:tools/app-refresh.ts", appRefresh],
   ["app-builder:tools/app-generate-icon.ts", appGenerateIcon],
   ["app-builder:tools/app-list.ts", appList],
 
@@ -228,9 +226,6 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["messaging:tools/messaging-sender-digest.ts", messagingSenderDigest],
   ["messaging:tools/messaging-archive-by-sender.ts", messagingArchiveBySender],
 
-  // personal-page
-  ["personal-page:tools/app-refresh.ts", personalPage_appRefresh],
-
   // phone-calls
   ["phone-calls:tools/call-start.ts", callStart],
   ["phone-calls:tools/call-status.ts", callStatus],

package/src/config/call-site-defaults.ts

@@ -1,7 +1,13 @@
 import { type LLMCallSite } from "./schemas/llm.js";
 
 type CallSiteDefaultConfig = {
-  profile: string;
+  /**
+   * Named profile the call site resolves to. Omit to inherit the workspace
+   * default config (`llm.default`, with the active profile applied) — used for
+   * call sites that must resolve to a credentialed provider on every install
+   * rather than pinning a profile that may be unavailable.
+   */
+  profile?: string;
   maxTokens?: number;
   effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
   temperature?: number | null;
@@ -125,8 +131,12 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
     thinking: { enabled: false },
     disableCache: true,
   },
+  // Anonymous and schema leaves inherit the workspace default config (no pinned
+  // profile) so they always resolve to a credentialed provider. Pinning a
+  // managed profile like `cost-optimized` breaks BYOK installs where the managed
+  // profiles are uncredentialed. A per-leaf `profile` option or a `workflowLeaf`
+  // call-site override still takes precedence for cost control.
   workflowLeaf: {
-    profile: "cost-optimized",
     effort: "low",
     thinking: { enabled: false },
   },

package/src/config/feature-flag-registry.json

@@ -9,14 +9,6 @@
       "description": "Automatically trigger conversation analysis on the same cadence as memory extraction (batch threshold, idle debounce, end-of-conversation). The analysis agent has full tool access and writes back to memory and skills without user approval.",
       "defaultEnabled": false
     },
-    {
-      "id": "memory-retrospective-fork",
-      "scope": "assistant",
-      "key": "memory-retrospective-fork",
-      "label": "Fork-based memory retrospective",
-      "description": "Fork the source conversation through its latest message for memory retrospectives, instead of rendering the slice into a transcript and waking an empty background conversation. The retrospective reads the conversation natively, including any inherited compaction summary and tail messages. Provider prompt-cache reuse additionally requires memory.retrospective.matchConversationProfile.",
-      "defaultEnabled": false
-    },
     {
       "id": "user-hosted-enabled",
       "scope": "client",
@@ -39,7 +31,7 @@
       "scope": "both",
       "key": "experiment-activation-flow-2026-06-03",
       "label": "Activation Flow Experiment 2026-06-03",
-      "description": "Multivariate activation-flow experiment. control = standard flow; variant-a = activation rail; personal-page = preseeded personal-page app (read by the daemon, hence scope \"both\"). Targeted via LaunchDarkly.",
+      "description": "Multivariate activation-flow experiment. control = standard flow; variant-a = activation rail; personal-page = new sign-up-page variant (front-end only). Targeted via LaunchDarkly.",
       "defaultEnabled": "control",
       "values": ["control", "variant-a", "personal-page"]
     },
@@ -410,14 +402,6 @@
       "label": "Self-intro first message",
       "description": "On the first conversation, send a natural self-introduction (e.g. \"Hi Vela, I'm alex. Nice to meet you.\") on the user's behalf and route it through real LLM inference, instead of serving the canned first greeting. Names come from the onboarding context; falls back to the canned greeting when no name is known. Exposed to clients so pre-hatch onboarding can compute the source-of-truth initial message, and to the assistant so older clients can still be gated server-side. See assistant/src/daemon/first-greeting.ts (buildSelfIntroMessage).",
       "defaultEnabled": false
-    },
-    {
-      "id": "workflows",
-      "scope": "assistant",
-      "key": "workflows",
-      "label": "Assistant Workflows",
-      "description": "Enable the sandboxed workflow orchestration engine (script-driven parallel leaf agents).",
-      "defaultEnabled": false
     }
   ]
 }

package/src/config/inference-profile-validation.ts

@@ -0,0 +1,26 @@
+import { getConfigReadOnly } from "./loader.js";
+
+/**
+ * Validate an inference-profile key against the configured `llm.profiles`
+ * catalog. Returns a user-facing error message when the key is empty or
+ * unknown, or `null` when valid.
+ */
+export function validateInferenceProfileKey(profile: string): string | null {
+  if (!profile.trim()) {
+    return "inferenceProfile must be a non-empty string";
+  }
+  const profiles = getConfigReadOnly().llm?.profiles ?? {};
+  const entry = profiles[profile];
+  if (entry === undefined) {
+    const available = Object.keys(profiles).sort();
+    const hint =
+      available.length > 0
+        ? ` Available profiles: ${available.join(", ")}.`
+        : " No profiles defined in llm.profiles.";
+    return `Inference profile "${profile}" is not defined in llm.profiles.${hint}`;
+  }
+  if (entry.status === "disabled") {
+    return `Inference profile "${profile}" is disabled.`;
+  }
+  return null;
+}

package/src/config/loader.ts

@@ -362,6 +362,10 @@ const DEPRECATED_FIELDS: Record<string, string> = {
     "per-lane concurrency caps (slowLlmConcurrency, fastConcurrency, " +
     "embedConcurrency) instead of a single batch size. " +
     "The field will be removed from your config file.",
+  "daemon.reapOrphanedSubprocesses":
+    "daemon.reapOrphanedSubprocesses has been removed. The daemon now reaps " +
+    "orphaned subprocesses automatically whenever it runs as PID 1 on Linux. " +
+    "The field will be removed from your config file.",
 };
 
 /**

package/src/config/profile-order.ts

@@ -0,0 +1,28 @@
+/**
+ * Presentation ordering for inference profiles. `llm.profileOrder` lists the
+ * keys a workspace wants surfaced first; the resolver ignores it, so it exists
+ * purely to keep profile pickers consistent across surfaces.
+ */
+
+/**
+ * Order profile keys for presentation: keys named in `profileOrder` first
+ * (deduped, and only those that resolve to a real profile), then the remaining
+ * keys alphabetically.
+ */
+export function orderProfileKeys(
+  profiles: Record<string, unknown>,
+  profileOrder: readonly string[] | undefined,
+): string[] {
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  for (const name of profileOrder ?? []) {
+    if (profiles[name] != null && !seen.has(name)) {
+      ordered.push(name);
+      seen.add(name);
+    }
+  }
+  const tail = Object.keys(profiles)
+    .filter((n) => !seen.has(n))
+    .sort();
+  return [...ordered, ...tail];
+}

package/src/config/schemas/elevenlabs.ts

@@ -1,6 +1,5 @@
 // Default ElevenLabs voice — "Amelia" (expressive, enthusiastic, British English).
 // Used by both in-app TTS and phone calls (via Twilio ConversationRelay).
-// Mirrored in: clients/macos/.../OpenAIVoiceService.swift (defaultVoiceId)
 export const DEFAULT_ELEVENLABS_VOICE_ID = "ZF6FPAbjXT4488VcRRnw";
 
 /** Valid conversation timeout values (seconds). Shared with voice-config-update tool. */

package/src/config/schemas/platform.ts

@@ -87,14 +87,6 @@ export const DaemonConfigSchema = z
       .describe(
         "Whether the daemon records conversations even when no client is connected",
       ),
-    reapOrphanedSubprocesses: z
-      .boolean({
-        error: "daemon.reapOrphanedSubprocesses must be a boolean",
-      })
-      .default(false)
-      .describe(
-        "Whether the daemon, when running as PID 1 in a container, periodically reaps orphaned subprocesses that reparented to it. Off by default while the behavior is being validated.",
-      ),
   })
   .describe("Background daemon process configuration");
 

package/src/config/seed-inference-profiles.ts

@@ -167,10 +167,13 @@ export type SeedInferenceProfilesOptions = {
  *
  * Runs on every daemon startup. Two responsibilities:
  *
- * 1. **Managed profiles** (`balanced`, `quality-optimized`, `cost-optimized`):
- *    overwritten on every boot so Vellum can push model/config updates to
- *    customers. Each carries `provider_connection: "anthropic-managed"`.
- *    Platform overlays (`preserveProfileNames`) take precedence.
+ * 1. **Managed profiles** (`balanced`, `quality-optimized`, `cost-optimized`,
+ *    `balanced-economy`): reconciled from the code templates on every boot —
+ *    on-platform and off-platform alike — so Vellum can push model/config
+ *    updates to customers in a release without a workspace migration. The
+ *    templates own all profile content; only `label` and `status` are
+ *    user-overridable and survive reseeds. Platform overlays
+ *    (`preserveProfileNames`) take precedence for the boot they are supplied.
  *
  * 2. **User profiles** (`custom-balanced`, `custom-quality-optimized`,
  *    `custom-cost-optimized`): materialized once at hatch time for
@@ -208,22 +211,25 @@ export function seedInferenceProfiles(
   // subsequent boot.
   const isByokMode = !isPlatform;
 
-  // 1. Managed profiles. Off-platform: overwrite on every boot so Vellum can
-  //    push model/config updates in new releases. On-platform: insert only if
-  //    absent — the platform controls profiles through overlays, and the
-  //    overlay fragment is authoritative even when it omits fields the local
-  //    template carries (e.g. an overlay supplying only provider/model/label
-  //    must not get its maxTokens/thinking polluted from the template). The
-  //    legacy migration-052 backfill that seeds label-less Anthropic
-  //    defaults is healed by workspace migration 082
-  //    (`backfill-managed-profile-labels`) rather than the seeder, so
-  //    this skip path stays simple.
+  // 1. Managed profiles. Reconciled from the code templates on every boot —
+  //    on-platform and off-platform alike — so Vellum can push model/config
+  //    updates in new releases just by editing `MANAGED_PROFILE_TEMPLATES` /
+  //    `model-intents.ts` and shipping a release, with no workspace migration.
+  //    The templates are the single source of truth for profile *content*
+  //    (model, maxTokens, effort, thinking, description, provider/connection).
   //
-  //    Two user-editable fields survive the overwrite: `label` (display
-  //    rename) and `status` (active/disabled toggle). The PUT route
-  //    `/v1/config/llm/profiles/:name` lets users patch these on managed
-  //    profiles without duplicating; we have to honor those edits across
-  //    reseeds or they'd silently revert on every boot. Carry by
+  //    Platform overlays (`preserveProfileNames`) still take precedence for the
+  //    boot they are supplied: a profile named in the overlay is skipped here so
+  //    the overlay fragment lands verbatim and is never polluted by template
+  //    fields it omits. The overlay is a one-time hatch input (archived after
+  //    its first merge), so on subsequent boots the templates reconcile content
+  //    as usual.
+  //
+  //    Two user-editable fields survive the reconcile: `label` (display
+  //    rename) and `status` (active/disabled toggle) — the only fields a user
+  //    may override. The PUT route `/v1/config/llm/profiles/:name` lets users
+  //    patch these on managed profiles without duplicating; we honor those
+  //    edits across reseeds or they'd silently revert on every boot. Carry by
   //    key-presence rather than truthiness so an explicit `null` (user
   //    cleared the label) survives too.
   //
@@ -249,7 +255,6 @@ export function seedInferenceProfiles(
 
   for (const [name, template] of Object.entries(MANAGED_PROFILE_TEMPLATES)) {
     if (preservedProfileNames.has(name)) continue;
-    if (isPlatform && readObject(profiles[name]) !== null) continue;
 
     const previous = readObject(profiles[name]);
     const effectiveTemplate: ManagedProfileTemplate = isByokMode

package/src/contacts/contact-store.ts

@@ -1,12 +1,14 @@
 import { and, asc, desc, eq, isNotNull, like, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import type { ChannelId } from "../channels/types.js";
 import { getDb } from "../memory/db-connection.js";
 import {
   assistantContactMetadata,
   contactChannels,
   contacts,
 } from "../memory/schema.js";
+import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { emitContactChange } from "./contact-events.js";
 import type {
   AssistantContactMetadata,
@@ -27,6 +29,27 @@ function escapeLike(value: string): string {
   return value.replace(/%/g, "").replace(/_/g, "");
 }
 
+/**
+ * Find the first contact_channels row whose (type, address) matches.
+ * Uses COLLATE NOCASE to find legacy lowercased rows (pre-migration 290).
+ */
+function findConflictingChannel(
+  db: ReturnType<typeof getDb>,
+  type: string,
+  address: string,
+) {
+  return db
+    .select()
+    .from(contactChannels)
+    .where(
+      and(
+        eq(contactChannels.type, type),
+        sql`${contactChannels.address} = ${address} COLLATE NOCASE`,
+      ),
+    )
+    .get();
+}
+
 /**
  * Pure slug transform applied to a display name. No DB lookup, no collision
  * handling — callers that need a collision-free filename should use
@@ -152,15 +175,7 @@ interface SyncChannelData {
 
 // ── CRUD ─────────────────────────────────────────────────────────────
 
-/** Retrieve a contact by ID.
- * Used by functions that have already resolved identity through channel lookups. */
-export function getContactInternal(id: string): ContactWithChannels | null {
-  const db = getDb();
-  const row = db.select().from(contacts).where(eq(contacts.id, id)).get();
-  if (!row) return null;
-  return withChannels(parseContact(row));
-}
-
+/** Retrieve a contact by ID. */
 export function getContact(id: string): ContactWithChannels | null {
   const db = getDb();
   const row = db.select().from(contacts).where(eq(contacts.id, id)).get();
@@ -168,6 +183,9 @@ export function getContact(id: string): ContactWithChannels | null {
   return withChannels(parseContact(row));
 }
 
+/** @deprecated Use {@link getContact} directly. */
+export const getContactInternal = getContact;
+
 /**
  * Look up a single contact channel by its primary key.
  * Returns the parsed channel row, or null if it does not exist.
@@ -199,6 +217,15 @@ export function upsertContact(params: {
   const db = getDb();
   const now = Date.now();
 
+  // Canonicalize all channel addresses up front so every downstream path
+  // (lookups, inserts, conflict checks) uses the canonical form.
+  const canonicalChannels = params.channels?.map((ch) => ({
+    ...ch,
+    address:
+      canonicalizeInboundIdentity(ch.type as ChannelId, ch.address) ??
+      ch.address,
+  }));
+
   let contactId = params.id;
 
   // If an ID is provided, check if the contact exists for update
@@ -226,10 +253,10 @@ export function upsertContact(params: {
         .where(eq(contacts.id, contactId))
         .run();
 
-      if (params.channels) {
+      if (canonicalChannels) {
         syncChannels(
           contactId,
-          params.channels,
+          canonicalChannels,
           now,
           params.reassignConflictingChannels,
         );
@@ -240,20 +267,10 @@ export function upsertContact(params: {
     }
   }
 
-  // Try to find by channel address to avoid duplicates
-  if (!contactId && params.channels && params.channels.length > 0) {
-    for (const ch of params.channels) {
-      // Primary lookup: match by (type, address)
-      const existingChannel = db
-        .select()
-        .from(contactChannels)
-        .where(
-          and(
-            eq(contactChannels.type, ch.type),
-            eq(contactChannels.address, ch.address.toLowerCase()),
-          ),
-        )
-        .get();
+  // Try to find by channel canonical identity to avoid duplicates
+  if (!contactId && canonicalChannels && canonicalChannels.length > 0) {
+    for (const ch of canonicalChannels) {
+      const existingChannel = findConflictingChannel(db, ch.type, ch.address);
 
       if (existingChannel) {
         contactId = existingChannel.contactId;
@@ -274,7 +291,7 @@ export function upsertContact(params: {
           .where(eq(contacts.id, contactId))
           .run();
 
-        syncChannels(contactId, params.channels, now);
+        syncChannels(contactId, canonicalChannels, now);
         emitContactChange();
         return { ...getContactInternal(contactId)!, created: false };
       }
@@ -318,10 +335,10 @@ export function upsertContact(params: {
     })
     .run();
 
-  if (params.channels) {
+  if (canonicalChannels) {
     syncChannels(
       contactId,
-      params.channels,
+      canonicalChannels,
       now,
       params.reassignConflictingChannels,
     );
@@ -345,9 +362,8 @@ function syncChannels(
   const db = getDb();
 
   for (const ch of channels) {
-    const normalizedAddress = ch.address.toLowerCase();
-
-    // Check if this channel already exists for this contact
+    // Match by (type, address) — the canonical identity for all channel types.
+    // COLLATE NOCASE catches legacy rows that were lowercased by old write paths.
     const existing = db
       .select()
       .from(contactChannels)
@@ -355,7 +371,7 @@ function syncChannels(
         and(
           eq(contactChannels.contactId, contactId),
           eq(contactChannels.type, ch.type),
-          eq(contactChannels.address, normalizedAddress),
+          sql`${contactChannels.address} = ${ch.address} COLLATE NOCASE`,
         ),
       )
       .get();
@@ -367,6 +383,8 @@ function syncChannels(
       const isBlocked = existing.status === "blocked";
 
       const updateSet: Record<string, unknown> = {};
+      // Self-heal legacy lowercased addresses to canonical form.
+      if (existing.address !== ch.address) updateSet.address = ch.address;
       if (ch.isPrimary !== undefined) updateSet.isPrimary = ch.isPrimary;
       if (ch.externalUserId !== undefined)
         updateSet.externalUserId = ch.externalUserId;
@@ -394,17 +412,8 @@ function syncChannels(
       continue;
     }
 
-    // Check if this channel exists for a different contact (unique constraint)
-    const conflicting = db
-      .select()
-      .from(contactChannels)
-      .where(
-        and(
-          eq(contactChannels.type, ch.type),
-          eq(contactChannels.address, normalizedAddress),
-        ),
-      )
-      .get();
+    // Check if this channel's canonical identity conflicts with another contact.
+    const conflicting = findConflictingChannel(db, ch.type, ch.address);
 
     if (conflicting) {
       if (reassignConflicting) {
@@ -451,7 +460,7 @@ function syncChannels(
         id: uuid(),
         contactId,
         type: ch.type,
-        address: normalizedAddress,
+        address: ch.address,
         isPrimary: ch.isPrimary ?? false,
         externalUserId: ch.externalUserId ?? null,
         externalChatId: ch.externalChatId ?? null,
@@ -480,8 +489,8 @@ export function searchContacts(params: {
 
   // Search by channel address first (exact or partial match)
   if (params.channelAddress) {
-    const normalizedAddress = escapeLike(params.channelAddress.toLowerCase());
-    if (!normalizedAddress) return [];
+    const escapedAddress = escapeLike(params.channelAddress);
+    if (!escapedAddress) return [];
     const channelRows = db
       .select({ contactId: contactChannels.contactId })
       .from(contactChannels)
@@ -490,9 +499,9 @@ export function searchContacts(params: {
         params.channelType
           ? and(
               eq(contactChannels.type, params.channelType),
-              like(contactChannels.address, `%${normalizedAddress}%`),
+              like(contactChannels.address, `%${escapedAddress}%`),
             )
-          : and(like(contactChannels.address, `%${normalizedAddress}%`)),
+          : and(like(contactChannels.address, `%${escapedAddress}%`)),
       )
       .all();
 
@@ -675,6 +684,8 @@ export function mergeContacts(
       .all();
 
     for (const ch of donorChannels) {
+      // COLLATE NOCASE catches legacy lowercased rows so we don't try to
+      // move a donor channel that collides with an existing survivor channel.
       const exists = tx
         .select()
         .from(contactChannels)
@@ -682,7 +693,7 @@ export function mergeContacts(
           and(
             eq(contactChannels.contactId, keepId),
             eq(contactChannels.type, ch.type),
-            eq(contactChannels.address, ch.address),
+            sql`${contactChannels.address} = ${ch.address} COLLATE NOCASE`,
           ),
         )
         .get();
@@ -705,11 +716,15 @@ export function mergeContacts(
 
 /**
  * Find a contact by a specific channel address. Returns null if not found.
+ * Canonicalizes the address before querying. Uses COLLATE NOCASE to match
+ * legacy lowercased rows that migration 290 couldn't restore.
  */
 export function findContactByAddress(
   type: string,
   address: string,
 ): ContactWithChannels | null {
+  const canonical =
+    canonicalizeInboundIdentity(type as ChannelId, address) ?? address;
   const db = getDb();
   const channel = db
     .select()
@@ -717,31 +732,7 @@ export function findContactByAddress(
     .where(
       and(
         eq(contactChannels.type, type),
-        eq(contactChannels.address, address.toLowerCase()),
-      ),
-    )
-    .get();
-
-  if (!channel) return null;
-  return getContactInternal(channel.contactId);
-}
-
-/**
- * Find a contact by channel external user ID. This is the key lookup for trust
- * resolution — maps a channel-native sender identity to its parent Contact.
- */
-export function findContactByChannelExternalId(
-  channelType: string,
-  externalUserId: string,
-): ContactWithChannels | null {
-  const db = getDb();
-  const channel = db
-    .select()
-    .from(contactChannels)
-    .where(
-      and(
-        eq(contactChannels.type, channelType),
-        eq(contactChannels.externalUserId, externalUserId),
+        sql`${contactChannels.address} = ${canonical} COLLATE NOCASE`,
       ),
     )
     .get();
@@ -753,6 +744,7 @@ export function findContactByChannelExternalId(
 /**
  * Find a contact by channel external chat ID. This is the fallback lookup path
  * when externalUserId is not available — matches by (type, externalChatId).
+ * No unique constraint exists on externalChatId, so ORDER BY is needed.
  */
 function findContactByChannelExternalChatId(
   channelType: string,
@@ -768,30 +760,40 @@ function findContactByChannelExternalChatId(
         eq(contactChannels.externalChatId, externalChatId),
       ),
     )
+    .orderBy(
+      sql`CASE ${contactChannels.status}
+        WHEN 'active' THEN 0
+        WHEN 'unverified' THEN 1
+        ELSE 2
+      END`,
+      desc(contactChannels.updatedAt),
+    )
     .get();
   if (!channel) return null;
   return getContactInternal(channel.contactId);
 }
 
 /**
- * Find a contact and matching channel by trying externalUserId first, then
+ * Find a contact and matching channel by trying address first, then
  * falling back to externalChatId. Mirrors the findMember lookup strategy.
  */
 export function findContactChannel(params: {
   channelType: string;
-  externalUserId?: string;
+  address?: string;
   externalChatId?: string;
 }): { contact: ContactWithChannels; channel: ContactChannel } | null {
-  if (params.externalUserId) {
-    const contact = findContactByChannelExternalId(
-      params.channelType,
-      params.externalUserId,
-    );
+  if (params.address) {
+    const canonical =
+      canonicalizeInboundIdentity(
+        params.channelType as ChannelId,
+        params.address,
+      ) ?? params.address;
+    const contact = findContactByAddress(params.channelType, canonical);
     if (contact) {
       const ch = contact.channels.find(
         (c) =>
           c.type === params.channelType &&
-          c.externalUserId === params.externalUserId,
+          c.address.toLowerCase() === canonical.toLowerCase(),
       );
       if (ch) return { contact, channel: ch };
     }
@@ -952,8 +954,6 @@ export function updateContactPrincipalAndChannel(
 ): boolean {
   const db = getDb();
   const now = Date.now();
-  const normalizedAddress = newPrincipalId.toLowerCase();
-
   // Look up the channel we're about to update so we know its type.
   const channel = db
     .select()
@@ -962,17 +962,8 @@ export function updateContactPrincipalAndChannel(
     .get();
   if (!channel) return false;
 
-  // Guard: check if another channel row already holds this (type, address).
-  const conflicting = db
-    .select()
-    .from(contactChannels)
-    .where(
-      and(
-        eq(contactChannels.type, channel.type),
-        eq(contactChannels.address, normalizedAddress),
-      ),
-    )
-    .get();
+  // Guard: check if another channel row holds this canonical identity.
+  const conflicting = findConflictingChannel(db, channel.type, newPrincipalId);
 
   if (conflicting && conflicting.id !== channelId) {
     return false;
@@ -986,8 +977,8 @@ export function updateContactPrincipalAndChannel(
 
     db.update(contactChannels)
       .set({
+        address: newPrincipalId,
         externalUserId: newPrincipalId,
-        address: normalizedAddress,
         updatedAt: now,
       })
       .where(eq(contactChannels.id, channelId))