@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/core/AiProfileService.js

@@ -1,6 +1,10 @@
 import { isAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { isAiProfileSeatScope } from '../shared/aiProfileSeatScope.js';
 import { normalizeSyncSameOriginAssetUrl } from '../sync/syncFieldSemantics.js';
+import { buildAiProfileAvatarStoragePrefixes } from '../utils/aiProfileAvatarPaths.js';
+import { getMcpClientRegistryEntry, inferLegacyMcpClientIdFromProfile } from '../mcp/clientRegistry.js';
+import { assignedAiProfileColor, normalizeAiProfileColor, parseAiProfileColorSource, } from '../shared/aiProfileColors.js';
+import { getTaskforceManagedAgentId, isTaskforceManagedAiProfile } from '../shared/aiProfileAvatarEligibility.js';
 function normalizeNullableIsoString(value) {
     if (typeof value !== 'string')
         return null;
@@ -44,6 +48,36 @@ function compareIsoStrings(left, right) {
         return 1;
     return normalizedLeft.localeCompare(normalizedRight);
 }
+const AI_PROFILE_COLOR_SOURCE_SYNC_RANK = {
+    legacy: 0,
+    assigned_default: 1,
+    agent_explicit: 2,
+    product_default: 3,
+    user_override: 4,
+};
+function compareAiProfileColorSyncCandidates(incoming, existing) {
+    const timestampComparison = compareIsoStrings(incoming.updatedAt, existing.updatedAt);
+    if (timestampComparison !== 0)
+        return timestampComparison;
+    const sourceComparison = AI_PROFILE_COLOR_SOURCE_SYNC_RANK[incoming.source]
+        - AI_PROFILE_COLOR_SOURCE_SYNC_RANK[existing.source];
+    if (sourceComparison !== 0)
+        return sourceComparison;
+    if (incoming.color === existing.color)
+        return 0;
+    return incoming.color < existing.color ? -1 : 1;
+}
+function resolveAiProfileProductDefaultColor(profile) {
+    if (isTaskforceManagedAiProfile(profile))
+        return null;
+    const connection = profile.providerMetadata?.connection;
+    const configuredClientId = connection && typeof connection === 'object' && !Array.isArray(connection)
+        ? connection.clientId
+        : null;
+    const clientId = getMcpClientRegistryEntry(configuredClientId)?.id
+        || inferLegacyMcpClientIdFromProfile(profile);
+    return normalizeAiProfileColor(getMcpClientRegistryEntry(clientId)?.signatureColor);
+}
 function deriveRosterStateUpdatedAt(value, fallbacks) {
     const explicitValue = normalizeNullableIsoString(value);
     const archivedAt = normalizeNullableIsoString(fallbacks.archivedAt);
@@ -213,65 +247,26 @@ function filterAiProfileRowsForTrustedSeatScope(deps, rows, trustedSeatScope) {
         return rows;
     return rows.filter((row) => aiProfileMatchesTrustedSeatScope(deps, row, trustedSeatScope));
 }
-function normalizeAiProfileIdentityValue(value) {
-    return String(value || '').trim().toLowerCase();
-}
-function latestAiProfileActivityValue(row) {
-    return normalizeNullableIsoString(row.last_active_at)
-        ?? normalizeNullableIsoString(row.updated_at)
-        ?? normalizeNullableIsoString(row.created_at)
-        ?? '';
-}
-function rankNullableIdentityMatch(existingValue, incomingValue) {
-    const existing = normalizeAiProfileIdentityValue(existingValue);
-    if (incomingValue) {
-        if (existing === incomingValue)
-            return 2;
-        if (!existing)
-            return 1;
-        return 0;
-    }
-    return existing ? 0 : 1;
-}
-function selectAiProfileIdentityMatch(deps, rows, input, trustedSeatScope) {
+function selectAiProfileIdentityMatch(deps, rows, trustedSeatScope) {
     const scopedRows = filterAiProfileRowsForTrustedSeatScope(deps, rows, trustedSeatScope);
-    const incomingProvider = normalizeAiProfileIdentityValue(input.provider) || null;
-    const incomingModel = normalizeAiProfileIdentityValue(input.model) || null;
-    const incomingSurfaceType = input.surfaceTypeProvided
-        ? normalizeAiProfileIdentityValue(input.surfaceType) || null
-        : null;
-    const ranked = scopedRows
-        .map((row) => {
-        const providerRank = rankNullableIdentityMatch(row.provider, incomingProvider);
-        const surfaceRank = input.surfaceTypeProvided
-            ? rankNullableIdentityMatch(row.surface_type, incomingSurfaceType)
-            : 0;
-        const modelRank = incomingModel && normalizeAiProfileIdentityValue(row.model) === incomingModel ? 1 : 0;
+    return {
+        row: scopedRows.length === 1 ? scopedRows[0] : undefined,
+        rows: scopedRows,
+        matchCount: scopedRows.length,
+    };
+}
+function buildAiProfileIdentityCandidates(deps, rows) {
+    return rows.map((row) => {
+        const profile = deps.aiProfileRowToRecord(row);
         return {
-            row,
-            providerRank,
-            surfaceRank,
-            modelRank,
-            activity: latestAiProfileActivityValue(row),
+            id: profile.id,
+            name: profile.name,
+            username: profile.username,
+            surfaceType: profile.surfaceType ?? null,
+            seatScope: profile.seatScope ?? null,
+            archived: Boolean(profile.archivedAt),
         };
-    })
-        .filter((entry) => Boolean(entry))
-        .sort((left, right) => {
-        if (right.providerRank !== left.providerRank)
-            return right.providerRank - left.providerRank;
-        if (right.surfaceRank !== left.surfaceRank)
-            return right.surfaceRank - left.surfaceRank;
-        if (right.modelRank !== left.modelRank)
-            return right.modelRank - left.modelRank;
-        const activityDelta = right.activity.localeCompare(left.activity);
-        if (activityDelta !== 0)
-            return activityDelta;
-        return String(left.row.id || '').localeCompare(String(right.row.id || ''));
     });
-    return {
-        row: ranked[0]?.row,
-        matchCount: ranked.length,
-    };
 }
 function requiresCloudSeatReservation(existing, nextSeatScope) {
     if (nextSeatScope !== 'cloud_metered')
@@ -287,7 +282,8 @@ function assertAiProfileSeatAvailable(deps, workspaceId) {
             workspaceId,
             limit: aiProfileUsage.limit,
             used: aiProfileUsage.used,
-            remaining: aiProfileUsage.remaining
+            remaining: aiProfileUsage.remaining,
+            recovery: 'Use the existing profileToken when reconnecting, reactivate an archived profile with its token, remove an unused cloud AI profile, or upgrade the workspace plan.'
         });
     }
 }
@@ -305,8 +301,13 @@ function inferAiProfileProviderModelDefaults(name) {
         return { provider: 'OpenAI', model: 'Codex' };
     if (normalized.includes('gemini'))
         return { provider: 'Google', model: 'Gemini' };
+    if (normalized.includes('grok'))
+        return { provider: 'xAI', model: 'Grok CLI' };
     return {};
 }
+function formatCliAiProfileDescriptionName(name) {
+    return String(name || '').trim().replace(/\s+cli$/i, '') || 'AI';
+}
 function inferAiProfileMetadataDefaults(name, surfaceType) {
     const inferredProviderModel = inferAiProfileProviderModelDefaults(name);
     switch (surfaceType) {
@@ -324,7 +325,7 @@ function inferAiProfileMetadataDefaults(name, surfaceType) {
             };
         case 'cli':
             return {
-                description: `${name} CLI coding agent connected through MCP.`,
+                description: `${formatCliAiProfileDescriptionName(name)} CLI coding agent connected through MCP.`,
                 role: 'CLI Coding Agent',
                 ...inferredProviderModel
             };
@@ -353,11 +354,12 @@ function resolveOptionalProfileField(inputValue, existingValue, fallbackValue) {
         return preservedValue;
     return normalizeOptionalProfileField(fallbackValue);
 }
-function resolveAiProfileMetadataFields(deps, input, existing) {
-    const surfaceTypeInput = normalizeAiProfileSurfaceTypeInput(deps, input.surfaceType);
+function resolveAiProfileMetadataFields(deps, input, existing, trustedSurfaceType) {
+    const trustedSurfaceTypeProvided = trustedSurfaceType !== undefined;
+    const surfaceTypeInput = normalizeAiProfileSurfaceTypeInput(deps, trustedSurfaceTypeProvided ? trustedSurfaceType : input.surfaceType);
     const manuallyOverridden = hasManualSurfaceTypeOverride(existing);
     const effectiveSurfaceType = surfaceTypeInput === undefined
-        || manuallyOverridden
+        || (manuallyOverridden && !trustedSurfaceTypeProvided)
         ? existing?.surfaceType ?? null
         : surfaceTypeInput;
     const inferredDefaults = inferAiProfileMetadataDefaults(input.name, effectiveSurfaceType);
@@ -367,7 +369,7 @@ function resolveAiProfileMetadataFields(deps, input, existing) {
         provider: resolveOptionalProfileField(input.provider, existing?.provider, inferredDefaults.provider) ?? null,
         model: resolveOptionalProfileField(input.model, existing?.model, inferredDefaults.model) ?? null,
         surfaceType: effectiveSurfaceType,
-        surfaceTypeProvided: surfaceTypeInput !== undefined && !manuallyOverridden,
+        surfaceTypeProvided: surfaceTypeInput !== undefined && (!manuallyOverridden || trustedSurfaceTypeProvided),
     };
 }
 function applyAiProfileMetadataDefaults(record) {
@@ -453,7 +455,7 @@ function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
         return;
     if (normalizeNullableIsoString(row.avatar_updated_at))
         return;
-    const avatarPrefix = `workspaces/${workspaceId}/assets/images/ai-profiles/${id}/avatar/`;
+    const avatarPrefixes = buildAiProfileAvatarStoragePrefixes({ workspaceId, profileId: id });
     try {
         const latestCropped = deps.db.prepare(`
             SELECT storage_key, updated_at, created_at
@@ -461,7 +463,7 @@ function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
             WHERE tenant_id = ?
               AND workspace_id = ?
               AND deleted_at IS NULL
-              AND storage_key LIKE ?
+              AND (storage_key LIKE ? OR storage_key LIKE ?)
               AND (
                     LOWER(original_filename) LIKE 'cropped-%'
                     OR LOWER(logical_name) = 'ai profile avatar display'
@@ -477,7 +479,7 @@ function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
               )
             ORDER BY COALESCE(updated_at, created_at) DESC, storage_key DESC
             LIMIT 1
-        `).get(deps.tenantId, workspaceId, `${avatarPrefix}%`);
+        `).get(deps.tenantId, workspaceId, `${avatarPrefixes[0]}%`, `${avatarPrefixes[1]}%`);
         if (!latestCropped)
             return;
         const latestSource = deps.db.prepare(`
@@ -486,7 +488,7 @@ function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
             WHERE tenant_id = ?
               AND workspace_id = ?
               AND deleted_at IS NULL
-              AND storage_key LIKE ?
+              AND (storage_key LIKE ? OR storage_key LIKE ?)
               AND (
                     LOWER(original_filename) LIKE 'source-%'
                     OR LOWER(logical_name) = 'ai profile avatar source'
@@ -498,7 +500,7 @@ function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
               )
             ORDER BY COALESCE(updated_at, created_at) DESC, storage_key DESC
             LIMIT 1
-        `).get(deps.tenantId, workspaceId, `${avatarPrefix}%`);
+        `).get(deps.tenantId, workspaceId, `${avatarPrefixes[0]}%`, `${avatarPrefixes[1]}%`);
         const avatarStorageKey = String(latestCropped.storage_key || '').trim();
         if (!avatarStorageKey)
             return;
@@ -542,7 +544,7 @@ function hydrateAiProfileRecord(deps, row, diagnostics) {
     backfillMissingAiProfileAvatarFromDuplicate(deps, row);
     backfillMissingAiProfileAvatarFromAssetIndex(deps, row);
     const record = deps.aiProfileRowToRecord(row);
-    const hydrated = applyAiProfileMetadataDefaults(record);
+    let hydrated = applyAiProfileMetadataDefaults(record);
     const metadataChanged = record.description !== hydrated.description
         || record.role !== hydrated.role
         || record.provider !== hydrated.provider
@@ -560,6 +562,23 @@ function hydrateAiProfileRecord(deps, row, diagnostics) {
             diagnostics.metadataBackfillCount = (diagnostics.metadataBackfillCount || 0) + 1;
         }
     }
+    const taskforceAgentId = getTaskforceManagedAgentId(hydrated);
+    const canonicalAgentColor = taskforceAgentId ? assignedAiProfileColor(taskforceAgentId) : null;
+    if (canonicalAgentColor && hydrated.colorSource !== 'user_override'
+        && (normalizeAiProfileColor(hydrated.color) !== canonicalAgentColor || hydrated.colorSource !== 'assigned_default')) {
+        const colorUpdatedAt = hydrated.colorUpdatedAt ?? hydrated.updatedAt;
+        deps.db.prepare(`
+            UPDATE ai_profiles
+            SET color = ?, color_source = 'assigned_default', color_updated_at = ?
+            WHERE tenant_id = ? AND id = ?
+        `).run(canonicalAgentColor, colorUpdatedAt, deps.tenantId, hydrated.id);
+        hydrated = {
+            ...hydrated,
+            color: canonicalAgentColor,
+            colorSource: 'assigned_default',
+            colorUpdatedAt,
+        };
+    }
     return hydrated;
 }
 export function listAiProfilesService(deps, workspaceId, options) {
@@ -574,6 +593,8 @@ export function listAiProfilesService(deps, workspaceId, options) {
             username,
             icon,
             color,
+            color_source,
+            color_updated_at,
             avatar_url,
             avatar_source_url,
             avatar_revision,
@@ -743,7 +764,40 @@ export function upsertAiProfileForSyncService(deps, profile) {
     const mergedName = metadataSourceProfile?.name ?? deps.normalizeAiProfileName(profile.name);
     const mergedUsername = metadataSourceProfile?.username ?? deps.normalizeAiProfileUsername(profile.username, profile.name);
     const mergedIcon = metadataSourceProfile?.icon ?? deps.normalizeAiProfileIcon(profile.icon);
-    const mergedColor = metadataSourceProfile?.color ?? deps.normalizeAiProfileColor(profile.color);
+    const incomingColor = normalizeAiProfileColor(profile.color);
+    const incomingColorSource = parseAiProfileColorSource(profile.colorSource) ?? 'legacy';
+    const incomingColorUpdatedAtProvided = Object.prototype.hasOwnProperty.call(profile, 'colorUpdatedAt');
+    const incomingColorUpdatedAt = normalizeNullableIsoString(profile.colorUpdatedAt);
+    const existingColorSource = parseAiProfileColorSource(existingProfile?.colorSource) ?? 'legacy';
+    const existingColorUpdatedAt = normalizeNullableIsoString(existingProfile?.colorUpdatedAt) ?? existingUpdatedAt;
+    const existingRawColor = String(existingProfile?.color || '').trim();
+    const incomingColorWins = !existingRow
+        || Boolean(incomingColorUpdatedAtProvided && incomingColorUpdatedAt && incomingColor && (compareAiProfileColorSyncCandidates({ color: incomingColor, source: incomingColorSource, updatedAt: incomingColorUpdatedAt }, {
+            color: existingRawColor || assignedAiProfileColor(`${mergedName}:${mergedUsername}`),
+            source: existingColorSource,
+            updatedAt: existingColorUpdatedAt,
+        }) > 0));
+    let mergedColor = incomingColorWins && incomingColor
+        ? incomingColor
+        : existingRawColor || assignedAiProfileColor(`${mergedName}:${mergedUsername}`);
+    let mergedColorSource = !existingRow && !incomingColor
+        ? 'assigned_default'
+        : incomingColorWins && incomingColor
+            ? (!incomingColorUpdatedAt ? 'assigned_default' : incomingColorSource)
+            : existingColorSource;
+    const mergedColorUpdatedAt = incomingColorWins && incomingColor
+        ? (incomingColorUpdatedAt ?? normalizedUpdatedAt)
+        : existingColorUpdatedAt;
+    const productDefaultColor = resolveAiProfileProductDefaultColor({
+        name: mergedName,
+        username: mergedUsername,
+        surfaceType: resolvedMetadata.surfaceType,
+        providerMetadata: metadataSourceProfile?.providerMetadata ?? existingProfile?.providerMetadata ?? null,
+    });
+    if (productDefaultColor && mergedColorSource !== 'user_override') {
+        mergedColor = productDefaultColor;
+        mergedColorSource = 'product_default';
+    }
     const existingAvatarUrl = normalizeAiProfileAvatarUrl(existingProfile?.avatarUrl);
     const existingAvatarSourceUrl = normalizeAiProfileAvatarUrl(existingProfile?.avatarSourceUrl);
     const incomingAvatarUrl = incomingAvatarUrlProvided ? normalizeAiProfileAvatarUrl(profile.avatarUrl) : null;
@@ -802,14 +856,15 @@ export function upsertAiProfileForSyncService(deps, profile) {
     const mergedLastActiveAt = compareIsoStrings(normalizedLastActiveAt, existingLastActiveAt) > 0
         ? normalizedLastActiveAt
         : existingLastActiveAt;
-    deps.db.prepare(`
+    return deps.db.transaction(() => {
+        deps.db.prepare(`
         INSERT INTO ai_profiles (
-            id, tenant_id, workspace_id, profile_token, name, username, icon, color,
+            id, tenant_id, workspace_id, profile_token, name, username, icon, color, color_source, color_updated_at,
             avatar_url, avatar_source_url, avatar_revision, avatar_updated_at,
             description, role, provider, model, surface_type, seat_scope, provider_metadata_json,
             archived_at, archived_by, archived_reason, merged_into_profile_id,
             roster_state_updated_at, created_at, updated_at, last_active_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT(id) DO UPDATE SET
             workspace_id = excluded.workspace_id,
             profile_token = excluded.profile_token,
@@ -817,6 +872,8 @@ export function upsertAiProfileForSyncService(deps, profile) {
             username = excluded.username,
             icon = excluded.icon,
             color = excluded.color,
+            color_source = excluded.color_source,
+            color_updated_at = excluded.color_updated_at,
             avatar_url = excluded.avatar_url,
             avatar_source_url = excluded.avatar_source_url,
             avatar_revision = excluded.avatar_revision,
@@ -836,17 +893,64 @@ export function upsertAiProfileForSyncService(deps, profile) {
             created_at = excluded.created_at,
             updated_at = excluded.updated_at,
             last_active_at = excluded.last_active_at
-    `).run(profileId, deps.tenantId, normalizedWorkspaceId, mergedProfileToken, mergedName, mergedUsername, mergedIcon, mergedColor, mergedAvatarUrl, mergedAvatarSourceUrl, mergedAvatarRevision, mergedAvatarUpdatedAt, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, mergedProviderMetadata, mergedArchivedAt, mergedArchivedBy, mergedArchivedReason, mergedMergedIntoProfileId, mergedRosterStateUpdatedAt, mergedCreatedAt, mergedUpdatedAt, mergedLastActiveAt);
-    const refreshed = deps.db.prepare(`
+    `).run(profileId, deps.tenantId, normalizedWorkspaceId, mergedProfileToken, mergedName, mergedUsername, mergedIcon, mergedColor, mergedColorSource, mergedColorUpdatedAt, mergedAvatarUrl, mergedAvatarSourceUrl, mergedAvatarRevision, mergedAvatarUpdatedAt, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, mergedProviderMetadata, mergedArchivedAt, mergedArchivedBy, mergedArchivedReason, mergedMergedIntoProfileId, mergedRosterStateUpdatedAt, mergedCreatedAt, mergedUpdatedAt, mergedLastActiveAt);
+        if (incomingMetadataWins) {
+            reconcileSyncedAiProfileConnectionBindings(deps, normalizedWorkspaceId, profileId, mergedProviderMetadata);
+        }
+        const refreshed = deps.db.prepare(`
         SELECT *
         FROM ai_profiles
         WHERE tenant_id = ? AND id = ?
         LIMIT 1
     `).get(deps.tenantId, profileId);
-    if (!refreshed) {
-        throw deps.createRuleError('Failed to upsert AI profile during sync', 500, 'AI_PROFILE_SYNC_UPSERT_FAILED');
+        if (!refreshed) {
+            throw deps.createRuleError('Failed to upsert AI profile during sync', 500, 'AI_PROFILE_SYNC_UPSERT_FAILED');
+        }
+        return hydrateAiProfileRecord(deps, refreshed);
+    })();
+}
+function reconcileSyncedAiProfileConnectionBindings(deps, workspaceId, profileId, providerMetadataJson) {
+    let metadata = {};
+    if (providerMetadataJson) {
+        try {
+            const parsed = JSON.parse(providerMetadataJson);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                metadata = parsed;
+        }
+        catch {
+            // The profile row remains authoritative even when legacy metadata is malformed.
+        }
+    }
+    const connection = metadata.connection && typeof metadata.connection === 'object' && !Array.isArray(metadata.connection)
+        ? metadata.connection
+        : {};
+    const bindingIds = Array.isArray(connection.bindingIds)
+        ? Array.from(new Set(connection.bindingIds
+            .map((value) => String(value || '').trim())
+            .filter((value) => value.length > 0 && value.length <= 128 && /^[A-Za-z0-9._:-]+$/.test(value))))
+            .sort()
+        : [];
+    const clientId = String(connection.clientId || '').trim() || null;
+    if (bindingIds.length === 0) {
+        deps.db.prepare(`DELETE FROM ai_profile_connection_bindings WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ?`)
+            .run(deps.tenantId, workspaceId, profileId);
+        return;
+    }
+    const placeholders = bindingIds.map(() => '?').join(', ');
+    deps.db.prepare(`DELETE FROM ai_profile_connection_bindings
+        WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ? AND connection_id NOT IN (${placeholders})`)
+        .run(deps.tenantId, workspaceId, profileId, ...bindingIds);
+    const now = new Date().toISOString();
+    const upsert = deps.db.prepare(`INSERT INTO ai_profile_connection_bindings
+        (tenant_id, workspace_id, connection_id, profile_id, client_id, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (tenant_id, workspace_id, connection_id) DO UPDATE SET
+            profile_id = excluded.profile_id,
+            client_id = excluded.client_id,
+            updated_at = excluded.updated_at`);
+    for (const bindingId of bindingIds) {
+        upsert.run(deps.tenantId, workspaceId, bindingId, profileId, clientId, now, now);
     }
-    return hydrateAiProfileRecord(deps, refreshed);
 }
 export function mergeAiProfilesService(deps, input) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
@@ -880,40 +984,97 @@ export function mergeAiProfilesService(deps, input) {
         });
     }
     const mergedSeatScope = resolveAiProfileSeatScope(deps, mergeRecord.seatScope, keepRecord);
+    const keepMetadata = keepRecord.providerMetadata && typeof keepRecord.providerMetadata === 'object' ? keepRecord.providerMetadata : {};
+    const mergeMetadata = mergeRecord.providerMetadata && typeof mergeRecord.providerMetadata === 'object' ? mergeRecord.providerMetadata : {};
+    const keepConnection = keepMetadata.connection && typeof keepMetadata.connection === 'object' && !Array.isArray(keepMetadata.connection)
+        ? keepMetadata.connection : {};
+    const mergeConnection = mergeMetadata.connection && typeof mergeMetadata.connection === 'object' && !Array.isArray(mergeMetadata.connection)
+        ? mergeMetadata.connection : {};
     const mergedAt = new Date().toISOString();
-    const doMerge = deps.db.transaction(() => {
-        deps.db.prepare(`
-            UPDATE tasks SET assignee = ?, updated_at = ?
-            WHERE tenant_id = ? AND workspace_id = ? AND assignee = ?
-        `).run(keepId, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId);
-        deps.db.prepare(`
-            UPDATE tasks SET created_by = ?, updated_at = ?
-            WHERE tenant_id = ? AND workspace_id = ? AND created_by = ?
-        `).run(keepId, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId);
-        deps.db.prepare(`
-            UPDATE ai_profiles
-            SET seat_scope = ?,
-                avatar_url = COALESCE(avatar_url, ?),
-                avatar_source_url = COALESCE(avatar_source_url, ?),
-                updated_at = ?
-            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
-        `).run(mergedSeatScope.seatScope, normalizeAiProfileAvatarUrl(mergeRecord.avatarUrl), normalizeAiProfileAvatarUrl(mergeRecord.avatarSourceUrl), mergedAt, deps.tenantId, normalizedWorkspaceId, keepId);
-        deps.db.prepare(`
-            UPDATE comments SET author = ?
-            WHERE tenant_id = ? AND workspace_id = ? AND author = ?
-        `).run(keepId, deps.tenantId, normalizedWorkspaceId, mergeId);
-        deps.db.prepare(`
-            UPDATE ai_profiles
-            SET archived_at = ?,
-                archived_by = ?,
-                archived_reason = ?,
-                merged_into_profile_id = ?,
-                roster_state_updated_at = ?,
-                updated_at = ?
-            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
-        `).run(mergedAt, keepId, 'merged_duplicate', keepId, mergedAt, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId);
+    const lockTaskIds = deps.db.prepare(`
+        SELECT id FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ?
+        ORDER BY id
+    `).all(deps.tenantId, normalizedWorkspaceId)
+        .map((row) => String(row.id || '').trim()).filter(Boolean);
+    deps.runTaskMetadataOwnershipTransaction({
+        workspaceId: normalizedWorkspaceId,
+        taskIds: lockTaskIds,
+        updatedAt: mergedAt,
+        apply: (protectedTaskIds) => {
+            const affectedTaskIds = deps.db.prepare(`
+                SELECT id FROM tasks
+                WHERE tenant_id = ? AND workspace_id = ? AND (assignee = ? OR created_by = ?)
+                ORDER BY id
+            `).all(deps.tenantId, normalizedWorkspaceId, mergeId, mergeId)
+                .map((row) => String(row.id || '').trim()).filter(Boolean);
+            const conflicts = affectedTaskIds.filter((taskId) => protectedTaskIds.has(taskId));
+            if (conflicts.length > 0) {
+                throw deps.createRuleError('This task metadata is managed by durable sync. Retry the edit from a durable-sync-aware task editor.', 409, 'TASK_METADATA_DURABLE_SYNC_REQUIRED', { taskIds: conflicts });
+            }
+            const doMerge = deps.db.transaction(() => {
+                if (affectedTaskIds.length > 0) {
+                    const taskPlaceholders = affectedTaskIds.map(() => '?').join(',');
+                    deps.db.prepare(`
+                        UPDATE tasks SET assignee = ?, updated_at = ?
+                        WHERE tenant_id = ? AND workspace_id = ? AND assignee = ?
+                          AND id IN (${taskPlaceholders})
+                    `).run(keepId, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId, ...affectedTaskIds);
+                    deps.db.prepare(`
+                        UPDATE tasks SET created_by = ?, updated_at = ?
+                        WHERE tenant_id = ? AND workspace_id = ? AND created_by = ?
+                          AND id IN (${taskPlaceholders})
+                    `).run(keepId, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId, ...affectedTaskIds);
+                }
+                deps.db.prepare(`
+                    UPDATE ai_profile_connection_bindings SET profile_id = ?, updated_at = ?
+                    WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ?
+                `).run(keepId, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId);
+                const canonicalBindingIds = deps.db.prepare(`SELECT connection_id FROM ai_profile_connection_bindings WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ? ORDER BY connection_id`)
+                    .all(deps.tenantId, normalizedWorkspaceId, keepId)
+                    .map((row) => String(row.connection_id || '').trim()).filter(Boolean);
+                const mergedBindingIds = Array.from(new Set([
+                    ...(Array.isArray(keepConnection.bindingIds) ? keepConnection.bindingIds : []),
+                    ...(Array.isArray(mergeConnection.bindingIds) ? mergeConnection.bindingIds : []),
+                    ...canonicalBindingIds,
+                ].map((value) => String(value || '').trim()).filter(Boolean)));
+                const nextKeepConnection = {
+                    ...mergeConnection,
+                    ...keepConnection,
+                    ...(mergedBindingIds.length > 0 ? { bindingIds: mergedBindingIds } : {}),
+                };
+                const nextMergeConnection = { ...mergeConnection };
+                delete nextMergeConnection.bindingIds;
+                const nextKeepMetadata = { ...mergeMetadata, ...keepMetadata, connection: nextKeepConnection };
+                const nextMergeMetadata = { ...mergeMetadata, connection: nextMergeConnection };
+                deps.db.prepare(`
+                    UPDATE ai_profiles
+                    SET seat_scope = ?,
+                        avatar_url = COALESCE(avatar_url, ?),
+                        avatar_source_url = COALESCE(avatar_source_url, ?),
+                        provider_metadata_json = ?,
+                        updated_at = ?
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                `).run(mergedSeatScope.seatScope, normalizeAiProfileAvatarUrl(mergeRecord.avatarUrl), normalizeAiProfileAvatarUrl(mergeRecord.avatarSourceUrl), JSON.stringify(nextKeepMetadata), mergedAt, deps.tenantId, normalizedWorkspaceId, keepId);
+                deps.db.prepare(`
+                    UPDATE comments SET author = ?
+                    WHERE tenant_id = ? AND workspace_id = ? AND author = ?
+                `).run(keepId, deps.tenantId, normalizedWorkspaceId, mergeId);
+                deps.db.prepare(`
+                    UPDATE ai_profiles
+                    SET archived_at = ?,
+                        archived_by = ?,
+                        archived_reason = ?,
+                        merged_into_profile_id = ?,
+                        provider_metadata_json = ?,
+                        roster_state_updated_at = ?,
+                        updated_at = ?
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                `).run(mergedAt, keepId, 'merged_duplicate', keepId, JSON.stringify(nextMergeMetadata), mergedAt, mergedAt, deps.tenantId, normalizedWorkspaceId, mergeId);
+            });
+            return doMerge();
+        },
     });
-    doMerge();
     const refreshed = deps.db.prepare(`
         SELECT * FROM ai_profiles WHERE tenant_id = ? AND id = ? LIMIT 1
     `).get(deps.tenantId, keepId);
@@ -989,6 +1150,56 @@ export function updateAiProfileAvatarService(deps, input) {
     }
     return hydrateAiProfileRecord(deps, refreshed);
 }
+export function updateAiProfileColorGroupService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const profileIds = Array.from(new Set((input.profileIds || []).map((id) => String(id || '').trim()).filter(Boolean)));
+    if (!profileIds.length)
+        throw deps.createRuleError('profileIds is required', 400, 'AI_PROFILE_IDS_REQUIRED');
+    const profiles = deps.db.prepare(`
+        SELECT * FROM ai_profiles
+        WHERE tenant_id = ? AND workspace_id = ? AND archived_at IS NULL
+    `).all(deps.tenantId, workspaceId);
+    const selected = profileIds.map((id) => profiles.find((row) => String(row.id) === id)).filter(Boolean);
+    if (selected.length !== profileIds.length)
+        throw deps.createRuleError('One or more AI profiles were not found.', 404, 'AI_PROFILE_NOT_FOUND');
+    const records = selected.map((row) => deps.aiProfileRowToRecord(row));
+    if (records.some(isTaskforceManagedAiProfile) && input.allowTaskforceManaged !== true) {
+        throw deps.createRuleError('Taskforce-managed agent colors require a trusted workspace color editor.', 409, 'AI_PROFILE_COLOR_MANAGED');
+    }
+    const resetColors = input.reset === true ? new Map(records.map((profile) => {
+        const productColor = resolveAiProfileProductDefaultColor(profile);
+        const taskforceMetadata = profile.providerMetadata?.taskforce;
+        const taskforceAgentId = taskforceMetadata && typeof taskforceMetadata === 'object' && !Array.isArray(taskforceMetadata)
+            ? String(taskforceMetadata.taskforceAgentId || '').trim()
+            : '';
+        return [profile.id, {
+                color: taskforceAgentId
+                    ? assignedAiProfileColor(taskforceAgentId)
+                    : productColor || assignedAiProfileColor(`${profile.name}:${profile.username}`),
+                source: taskforceAgentId ? 'assigned_default' : (productColor ? 'product_default' : 'assigned_default'),
+            }];
+    })) : null;
+    const requestedColor = input.reset === true ? null : normalizeAiProfileColor(input.color);
+    if (input.reset !== true && !requestedColor) {
+        throw deps.createRuleError('color must be a Taskforce palette token or hex color.', 400, 'AI_PROFILE_COLOR_INVALID');
+    }
+    const now = new Date().toISOString();
+    const run = deps.db.transaction(() => {
+        for (const id of profileIds) {
+            const resetColor = resetColors?.get(id);
+            deps.db.prepare(`
+                UPDATE ai_profiles SET color = ?, color_source = ?, color_updated_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            `).run(resetColor?.color ?? requestedColor, resetColor?.source ?? 'user_override', now, deps.tenantId, workspaceId, id);
+        }
+    });
+    run();
+    return profileIds.map((id) => {
+        const row = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ? AND id = ?`)
+            .get(deps.tenantId, workspaceId, id);
+        return hydrateAiProfileRecord(deps, row);
+    });
+}
 export function updateAiProfileSurfaceTypeService(deps, input) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
     const profileId = String(input.profileId || '').trim();
@@ -1029,6 +1240,137 @@ export function updateAiProfileSurfaceTypeService(deps, input) {
     }
     return hydrateAiProfileRecord(deps, refreshed);
 }
+export function updateAiProfileProviderMetadataService(deps, input) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const profileId = String(input.profileId || '').trim();
+    if (!profileId)
+        throw deps.createRuleError('profileId is required', 400, 'AI_PROFILE_ID_REQUIRED');
+    const existing = deps.db.prepare(`
+        SELECT *
+        FROM ai_profiles
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND archived_at IS NULL
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, profileId);
+    if (!existing) {
+        throw deps.createRuleError(`Profile ${profileId} not found`, 404, 'AI_PROFILE_NOT_FOUND');
+    }
+    const providerMetadata = input.providerMetadata && typeof input.providerMetadata === 'object' && !Array.isArray(input.providerMetadata)
+        ? input.providerMetadata
+        : null;
+    const updatedAt = new Date().toISOString();
+    deps.db.prepare(`
+        UPDATE ai_profiles
+        SET provider_metadata_json = ?,
+            updated_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+    `).run(providerMetadata ? JSON.stringify(providerMetadata) : null, updatedAt, deps.tenantId, normalizedWorkspaceId, profileId);
+    const refreshed = deps.db.prepare(`
+        SELECT *
+        FROM ai_profiles
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, profileId);
+    if (!refreshed) {
+        throw deps.createRuleError('Failed to update AI profile provider metadata', 500, 'AI_PROFILE_METADATA_UPDATE_FAILED');
+    }
+    return hydrateAiProfileRecord(deps, refreshed);
+}
+function normalizeConnectionBindingId(deps, value) {
+    const normalized = String(value || '').trim();
+    if (!normalized || normalized.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(normalized)) {
+        throw deps.createRuleError('A valid MCP connection ID is required', 400, 'AI_PROFILE_CONNECTION_ID_INVALID');
+    }
+    return normalized;
+}
+function parseProviderMetadataRow(row) {
+    if (typeof row.provider_metadata_json !== 'string' || !row.provider_metadata_json.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(row.provider_metadata_json);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function bindAiProfileConnectionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const profileId = String(input.profileId || '').trim();
+    const connectionId = normalizeConnectionBindingId(deps, input.connectionId);
+    const clientId = String(input.clientId || '').trim() || null;
+    return deps.db.transaction(() => {
+        const target = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND archived_at IS NULL LIMIT 1`)
+            .get(deps.tenantId, workspaceId, profileId);
+        if (!target)
+            throw deps.createRuleError(`Profile ${profileId} not found`, 404, 'AI_PROFILE_NOT_FOUND');
+        const now = new Date().toISOString();
+        deps.db.prepare(`INSERT INTO ai_profile_connection_bindings (tenant_id, workspace_id, connection_id, profile_id, client_id, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (tenant_id, workspace_id, connection_id) DO UPDATE SET profile_id = excluded.profile_id, client_id = excluded.client_id, updated_at = excluded.updated_at`)
+            .run(deps.tenantId, workspaceId, connectionId, profileId, clientId, now, now);
+        const rows = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ?`).all(deps.tenantId, workspaceId);
+        for (const row of rows) {
+            const metadata = parseProviderMetadataRow(row);
+            const connection = metadata.connection && typeof metadata.connection === 'object' && !Array.isArray(metadata.connection)
+                ? metadata.connection
+                : {};
+            const bindingIds = Array.isArray(connection.bindingIds)
+                ? connection.bindingIds.map((value) => String(value || '').trim()).filter(Boolean)
+                : [];
+            const isTarget = String(row.id) === profileId;
+            const nextBindingIds = isTarget
+                ? Array.from(new Set([...bindingIds, connectionId]))
+                : bindingIds.filter((value) => value !== connectionId);
+            const nextConnection = { ...connection };
+            if (isTarget && clientId)
+                nextConnection.clientId = clientId;
+            if (nextBindingIds.length > 0)
+                nextConnection.bindingIds = nextBindingIds;
+            else
+                delete nextConnection.bindingIds;
+            const changed = JSON.stringify(connection) !== JSON.stringify(nextConnection);
+            if (!changed)
+                continue;
+            deps.db.prepare(`UPDATE ai_profiles SET provider_metadata_json = ?, updated_at = ? WHERE tenant_id = ? AND workspace_id = ? AND id = ?`)
+                .run(JSON.stringify({ ...metadata, connection: nextConnection }), now, deps.tenantId, workspaceId, row.id);
+        }
+        const refreshed = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ? AND id = ? LIMIT 1`)
+            .get(deps.tenantId, workspaceId, profileId);
+        if (!refreshed)
+            throw deps.createRuleError('Failed to bind MCP connection', 500, 'AI_PROFILE_CONNECTION_BIND_FAILED');
+        return hydrateAiProfileRecord(deps, refreshed);
+    })();
+}
+export function getAiProfileByConnectionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const connectionId = normalizeConnectionBindingId(deps, input.connectionId);
+    const binding = deps.db.prepare(`SELECT p.* FROM ai_profile_connection_bindings b JOIN ai_profiles p ON p.tenant_id = b.tenant_id AND p.workspace_id = b.workspace_id AND p.id = b.profile_id
+        WHERE b.tenant_id = ? AND b.workspace_id = ? AND b.connection_id = ? LIMIT 1`)
+        .get(deps.tenantId, workspaceId, connectionId);
+    if (binding) {
+        const record = hydrateAiProfileRecord(deps, binding);
+        return input.seatScope !== undefined && (record.seatScope ?? null) !== input.seatScope ? null : record;
+    }
+    const legacyRows = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ?`).all(deps.tenantId, workspaceId)
+        .filter((row) => {
+        const record = hydrateAiProfileRecord(deps, row);
+        if (input.seatScope !== undefined && (record.seatScope ?? null) !== input.seatScope)
+            return false;
+        const connection = parseProviderMetadataRow(row).connection;
+        return Array.isArray(connection?.bindingIds) && connection.bindingIds.includes(connectionId);
+    });
+    if (legacyRows.length > 1) {
+        throw deps.createRuleError('This MCP connection is bound to multiple AI profiles. Merge the duplicates or reconnect with a profileToken.', 409, 'AI_PROFILE_BINDING_AMBIGUOUS', {
+            workspaceId, profileIds: legacyRows.map((row) => String(row.id)),
+        });
+    }
+    if (legacyRows.length === 0)
+        return null;
+    const record = hydrateAiProfileRecord(deps, legacyRows[0]);
+    if (!record.archivedAt)
+        bindAiProfileConnectionService(deps, { workspaceId, profileId: record.id, connectionId });
+    return record;
+}
 export function archiveAiProfileService(deps, input) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
     const profileId = String(input.profileId || '').trim();
@@ -1087,6 +1429,29 @@ export function resolveAiProfileService(deps, input, options) {
     const profileToken = String(input.profileToken || '').trim();
     const now = new Date().toISOString();
     const trustedSeatScope = normalizeAiProfileSeatScopeInput(deps, options?.trustedSeatScope);
+    const resolveExistingColor = (existing) => {
+        if (isTaskforceManagedAiProfile(existing)) {
+            return { color: existing.color, source: existing.colorSource ?? 'legacy', updatedAt: existing.colorUpdatedAt ?? existing.updatedAt };
+        }
+        if (existing.colorSource === 'user_override') {
+            return { color: existing.color, source: existing.colorSource, updatedAt: existing.colorUpdatedAt ?? existing.updatedAt };
+        }
+        const productColor = normalizeAiProfileColor(options?.trustedSignatureColor);
+        if (productColor) {
+            const productColorAlreadyApplied = normalizeAiProfileColor(existing.color) === productColor
+                && existing.colorSource === 'product_default';
+            return productColorAlreadyApplied
+                ? { color: existing.color, source: existing.colorSource, updatedAt: existing.colorUpdatedAt ?? existing.updatedAt }
+                : { color: productColor, source: 'product_default', updatedAt: now };
+        }
+        if (input.color === undefined || input.color === null || String(input.color).trim() === '') {
+            return { color: existing.color, source: existing.colorSource ?? 'legacy', updatedAt: existing.colorUpdatedAt ?? existing.updatedAt };
+        }
+        const color = normalizeAiProfileColor(input.color);
+        if (!color)
+            throw deps.createRuleError('color must be a Taskforce palette token or hex color.', 400, 'AI_PROFILE_COLOR_INVALID');
+        return { color, source: 'agent_explicit', updatedAt: now };
+    };
     if (profileToken) {
         const existingRows = deps.db.prepare(`
             SELECT *
@@ -1116,9 +1481,7 @@ export function resolveAiProfileService(deps, input, options) {
                 const nextIcon = input.icon === undefined
                     ? existingProfile.icon
                     : deps.normalizeAiProfileIcon(input.icon);
-                const nextColor = input.color === undefined
-                    ? existingProfile.color
-                    : deps.normalizeAiProfileColor(input.color);
+                const nextColor = resolveExistingColor(existingProfile);
                 const nextDescription = normalizeOptionalProfileField(input.description);
                 const nextRole = normalizeOptionalProfileField(input.role);
                 const nextProvider = normalizeOptionalProfileField(input.provider);
@@ -1130,7 +1493,7 @@ export function resolveAiProfileService(deps, input, options) {
                     provider: nextProvider,
                     model: nextModel,
                     surfaceType: input.surfaceType,
-                }, existingProfile);
+                }, existingProfile, options?.trustedSurfaceType);
                 const resolvedSeatScope = resolveTrustedAiProfileSeatScope(deps, trustedSeatScope, existingProfile);
                 if (requiresCloudSeatReservation(existingProfile, resolvedSeatScope.seatScope)) {
                     assertAiProfileSeatAvailable(deps, normalizedWorkspaceId);
@@ -1140,7 +1503,7 @@ export function resolveAiProfileService(deps, input, options) {
                     SET name = ?,
                         username = ?,
                         icon = ?,
-                        color = ?,
+                        color = ?, color_source = ?, color_updated_at = ?,
                         description = COALESCE(?, description),
                         role = COALESCE(?, role),
                         provider = COALESCE(?, provider),
@@ -1161,7 +1524,7 @@ export function resolveAiProfileService(deps, input, options) {
                         last_active_at = ?,
                         updated_at = ?
                     WHERE tenant_id = ? AND id = ?
-                `).run(nextName, nextUsername, nextIcon, nextColor, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, now, now, now, deps.tenantId, String(archivedRow.id || '').trim());
+                `).run(nextName, nextUsername, nextIcon, nextColor.color, nextColor.source, nextColor.updatedAt, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, now, now, now, deps.tenantId, String(archivedRow.id || '').trim());
                 const refreshed = deps.db.prepare(`
                     SELECT *
                     FROM ai_profiles
@@ -1187,9 +1550,7 @@ export function resolveAiProfileService(deps, input, options) {
             const nextIcon = input.icon === undefined
                 ? existingProfile.icon
                 : deps.normalizeAiProfileIcon(input.icon);
-            const nextColor = input.color === undefined
-                ? existingProfile.color
-                : deps.normalizeAiProfileColor(input.color);
+            const nextColor = resolveExistingColor(existingProfile);
             const nextDescription = normalizeOptionalProfileField(input.description);
             const nextRole = normalizeOptionalProfileField(input.role);
             const nextProvider = normalizeOptionalProfileField(input.provider);
@@ -1201,7 +1562,7 @@ export function resolveAiProfileService(deps, input, options) {
                 provider: nextProvider,
                 model: nextModel,
                 surfaceType: input.surfaceType,
-            }, existingProfile);
+            }, existingProfile, options?.trustedSurfaceType);
             const resolvedSeatScope = resolveTrustedAiProfileSeatScope(deps, trustedSeatScope, existingProfile);
             if (requiresCloudSeatReservation(existingProfile, resolvedSeatScope.seatScope)) {
                 assertAiProfileSeatAvailable(deps, normalizedWorkspaceId);
@@ -1211,7 +1572,7 @@ export function resolveAiProfileService(deps, input, options) {
                 SET name = ?,
                     username = ?,
                     icon = ?,
-                    color = ?,
+                    color = ?, color_source = ?, color_updated_at = ?,
                     description = COALESCE(?, description),
                     role = COALESCE(?, role),
                     provider = COALESCE(?, provider),
@@ -1227,7 +1588,7 @@ export function resolveAiProfileService(deps, input, options) {
                     last_active_at = ?,
                     updated_at = ?
                 WHERE tenant_id = ? AND id = ?
-            `).run(nextName, nextUsername, nextIcon, nextColor, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, now, now, deps.tenantId, String(existingRow.id || '').trim());
+            `).run(nextName, nextUsername, nextIcon, nextColor.color, nextColor.source, nextColor.updatedAt, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, now, now, deps.tenantId, String(existingRow.id || '').trim());
             const refreshed = deps.db.prepare(`
                 SELECT *
                 FROM ai_profiles
@@ -1243,21 +1604,6 @@ export function resolveAiProfileService(deps, input, options) {
             };
         }
     }
-    const identityDescription = normalizeOptionalProfileField(input.description);
-    const identityRole = normalizeOptionalProfileField(input.role);
-    const inferredIdentity = inferAiProfileProviderModelDefaults(name);
-    const identityProvider = normalizeOptionalProfileField(input.provider)
-        ?? normalizeOptionalProfileField(inferredIdentity.provider);
-    const identityModel = normalizeOptionalProfileField(input.model)
-        ?? normalizeOptionalProfileField(inferredIdentity.model);
-    const identityMetadata = resolveAiProfileMetadataFields(deps, {
-        name,
-        description: identityDescription,
-        role: identityRole,
-        provider: identityProvider,
-        model: identityModel,
-        surfaceType: input.surfaceType,
-    }, null);
     const exactMatches = deps.db.prepare(`
         SELECT *
         FROM ai_profiles
@@ -1270,52 +1616,22 @@ export function resolveAiProfileService(deps, input, options) {
           )
         ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
     `).all(deps.tenantId, normalizedWorkspaceId, name, deps.normalizeAiProfileUsername(undefined, name));
-    const exactMatch = selectAiProfileIdentityMatch(deps, exactMatches, identityMetadata, trustedSeatScope);
+    const exactMatch = selectAiProfileIdentityMatch(deps, exactMatches, trustedSeatScope);
+    if (exactMatch.matchCount > 1) {
+        throw deps.createRuleError(`Multiple active AI profiles match "${name}". Bind with a profileToken or merge the duplicates before retrying.`, 409, 'AI_PROFILE_AMBIGUOUS', {
+            workspaceId: normalizedWorkspaceId,
+            candidates: buildAiProfileIdentityCandidates(deps, exactMatch.rows),
+            recovery: 'Use a profileToken for the intended profile, or merge/archive duplicate profiles in AI Profile Manager.',
+        });
+    }
     if (exactMatch.row) {
         const canonicalId = String(exactMatch.row.id || '').trim();
-        const nextName = name;
-        const nextUsername = deps.normalizeAiProfileUsername(undefined, nextName);
-        const nextIcon = deps.normalizeAiProfileIcon(input.icon);
-        const nextColor = deps.normalizeAiProfileColor(input.color);
-        const nextDescription = normalizeOptionalProfileField(input.description);
-        const nextRole = normalizeOptionalProfileField(input.role);
-        const nextProvider = normalizeOptionalProfileField(input.provider);
-        const nextModel = normalizeOptionalProfileField(input.model);
-        const existingProfile = deps.aiProfileRowToRecord(exactMatch.row);
-        const resolvedMetadata = resolveAiProfileMetadataFields(deps, {
-            name: nextName,
-            description: nextDescription,
-            role: nextRole,
-            provider: nextProvider,
-            model: nextModel,
-            surfaceType: input.surfaceType,
-        }, existingProfile);
-        const resolvedSeatScope = resolveTrustedAiProfileSeatScope(deps, trustedSeatScope, existingProfile);
-        if (requiresCloudSeatReservation(existingProfile, resolvedSeatScope.seatScope)) {
-            assertAiProfileSeatAvailable(deps, normalizedWorkspaceId);
-        }
         deps.db.prepare(`
             UPDATE ai_profiles
-            SET name = ?,
-                username = ?,
-                icon = ?,
-                color = ?,
-                description = COALESCE(?, description),
-                role = COALESCE(?, role),
-                provider = COALESCE(?, provider),
-                model = COALESCE(?, model),
-                last_active_at = ?,
-                updated_at = ?,
-                surface_type = CASE
-                    WHEN ? = 1 THEN ?
-                    ELSE surface_type
-                END,
-                seat_scope = CASE
-                    WHEN ? = 1 THEN ?
-                    ELSE seat_scope
-                END
+            SET last_active_at = ?,
+                updated_at = ?
             WHERE tenant_id = ? AND id = ?
-        `).run(nextName, nextUsername, nextIcon, nextColor, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, now, now, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, deps.tenantId, canonicalId);
+        `).run(now, now, deps.tenantId, canonicalId);
         const reused = deps.db.prepare(`
             SELECT *
             FROM ai_profiles
@@ -1327,13 +1643,7 @@ export function resolveAiProfileService(deps, input, options) {
         }
         return {
             created: false,
-            profile: hydrateAiProfileRecord(deps, reused),
-            ...(exactMatch.matchCount > 1 ? {
-                duplicateWarning: {
-                    existingProfileId: canonicalId,
-                    message: `Multiple profiles matched "${name}". Reused ${canonicalId}; merge the remaining duplicates.`
-                }
-            } : {})
+            profile: hydrateAiProfileRecord(deps, reused)
         };
     }
     const archivedMatches = deps.db.prepare(`
@@ -1348,76 +1658,30 @@ export function resolveAiProfileService(deps, input, options) {
           )
         ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
     `).all(deps.tenantId, normalizedWorkspaceId, name, deps.normalizeAiProfileUsername(undefined, name));
-    const archivedMatch = selectAiProfileIdentityMatch(deps, archivedMatches, identityMetadata, trustedSeatScope);
-    if (archivedMatch.row) {
-        const canonicalId = String(archivedMatch.row.id || '').trim();
-        const nextName = name;
-        const nextUsername = deps.normalizeAiProfileUsername(undefined, nextName);
-        const nextIcon = deps.normalizeAiProfileIcon(input.icon);
-        const nextColor = deps.normalizeAiProfileColor(input.color);
-        const nextDescription = normalizeOptionalProfileField(input.description);
-        const nextRole = normalizeOptionalProfileField(input.role);
-        const nextProvider = normalizeOptionalProfileField(input.provider);
-        const nextModel = normalizeOptionalProfileField(input.model);
-        const existingProfile = deps.aiProfileRowToRecord(archivedMatch.row);
-        const resolvedMetadata = resolveAiProfileMetadataFields(deps, {
-            name: nextName,
-            description: nextDescription,
-            role: nextRole,
-            provider: nextProvider,
-            model: nextModel,
-            surfaceType: input.surfaceType,
-        }, existingProfile);
-        const resolvedSeatScope = resolveTrustedAiProfileSeatScope(deps, trustedSeatScope, existingProfile);
-        if (requiresCloudSeatReservation(existingProfile, resolvedSeatScope.seatScope)) {
-            assertAiProfileSeatAvailable(deps, normalizedWorkspaceId);
-        }
-        deps.db.prepare(`
-            UPDATE ai_profiles
-            SET name = ?,
-                username = ?,
-                icon = ?,
-                color = ?,
-                description = COALESCE(?, description),
-                role = COALESCE(?, role),
-                provider = COALESCE(?, provider),
-                model = COALESCE(?, model),
-                last_active_at = ?,
-                updated_at = ?,
-                archived_at = NULL,
-                archived_by = NULL,
-                archived_reason = NULL,
-                merged_into_profile_id = NULL,
-                roster_state_updated_at = ?,
-                surface_type = CASE
-                    WHEN ? = 1 THEN ?
-                    ELSE surface_type
-                END,
-                seat_scope = CASE
-                    WHEN ? = 1 THEN ?
-                    ELSE seat_scope
-                END
-            WHERE tenant_id = ? AND id = ?
-        `).run(nextName, nextUsername, nextIcon, nextColor, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, now, now, now, resolvedMetadata.surfaceTypeProvided ? 1 : 0, resolvedMetadata.surfaceType, resolvedSeatScope.seatScopeProvided ? 1 : 0, resolvedSeatScope.seatScope, deps.tenantId, canonicalId);
-        const reactivated = deps.db.prepare(`
-            SELECT *
-            FROM ai_profiles
-            WHERE tenant_id = ? AND id = ?
-            LIMIT 1
-        `).get(deps.tenantId, canonicalId);
-        if (!reactivated) {
-            throw deps.createRuleError('Failed to refresh AI profile', 500, 'AI_PROFILE_REFRESH_FAILED');
-        }
-        return {
-            created: false,
-            profile: hydrateAiProfileRecord(deps, reactivated)
-        };
+    const archivedMatch = selectAiProfileIdentityMatch(deps, archivedMatches, trustedSeatScope);
+    if (archivedMatch.matchCount > 0) {
+        throw deps.createRuleError(`An archived AI profile matches "${name}". Reactivate it with its profileToken or choose a distinct identity.`, 409, 'AI_PROFILE_RETIRED', {
+            workspaceId: normalizedWorkspaceId,
+            candidates: buildAiProfileIdentityCandidates(deps, archivedMatch.rows),
+            recovery: 'Use the archived profileToken to reactivate the intended profile, or rename the new identity.',
+        });
     }
     const id = deps.generateEntityId('ai-profile');
     const issuedProfileToken = deps.issueProfileToken();
     const username = deps.normalizeAiProfileUsername(undefined, name);
     const icon = deps.normalizeAiProfileIcon(input.icon);
-    const color = deps.normalizeAiProfileColor(input.color);
+    const explicitColorProvided = input.color !== undefined && input.color !== null && String(input.color).trim() !== '';
+    const explicitColor = explicitColorProvided ? normalizeAiProfileColor(input.color) : null;
+    if (explicitColorProvided && !explicitColor) {
+        throw deps.createRuleError('color must be a Taskforce palette token or hex color.', 400, 'AI_PROFILE_COLOR_INVALID');
+    }
+    const productColor = normalizeAiProfileColor(options?.trustedSignatureColor);
+    const color = productColor || explicitColor || assignedAiProfileColor(`${name}:${username}`);
+    const colorSource = productColor
+        ? 'product_default'
+        : explicitColor
+            ? 'agent_explicit'
+            : 'assigned_default';
     const description = normalizeOptionalProfileField(input.description);
     const role = normalizeOptionalProfileField(input.role);
     const provider = normalizeOptionalProfileField(input.provider);
@@ -1429,7 +1693,7 @@ export function resolveAiProfileService(deps, input, options) {
         provider,
         model,
         surfaceType: input.surfaceType,
-    }, null);
+    }, null, options?.trustedSurfaceType);
     const resolvedSeatScope = resolveTrustedAiProfileSeatScope(deps, trustedSeatScope, null);
     if (resolvedSeatScope.seatScope === 'cloud_metered') {
         assertAiProfileSeatAvailable(deps, normalizedWorkspaceId);
@@ -1439,12 +1703,12 @@ export function resolveAiProfileService(deps, input, options) {
         : null;
     deps.db.prepare(`
         INSERT INTO ai_profiles (
-            id, tenant_id, workspace_id, profile_token, name, username, icon, color,
+            id, tenant_id, workspace_id, profile_token, name, username, icon, color, color_source, color_updated_at,
             avatar_url, avatar_source_url, description, role, provider, model, surface_type, seat_scope, provider_metadata_json,
             archived_at, archived_by, archived_reason, merged_into_profile_id,
             roster_state_updated_at, created_at, updated_at, last_active_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(id, deps.tenantId, normalizedWorkspaceId, issuedProfileToken, name, username, icon, color, null, null, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, providerMetadata ? JSON.stringify(providerMetadata) : null, null, null, null, null, now, now, now, now);
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, deps.tenantId, normalizedWorkspaceId, issuedProfileToken, name, username, icon, color, colorSource, now, null, null, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, providerMetadata ? JSON.stringify(providerMetadata) : null, null, null, null, null, now, now, now, now);
     const created = deps.db.prepare(`
         SELECT *
         FROM ai_profiles