fix(backend): preserve satellite commands during account deletion

Fixed critical bugs where MCP processes weren't terminated and FK constraints
blocked user deletion during self-service account removal.

- Preserve pending satellite commands by setting target_team_id and created_by
  to NULL instead of deleting them
- Delete only completed/failed/acknowledged/executing satellite commands
- Added cleanup of satellite-related records (processes, usage logs, client
  activity) before user deletion to prevent FK violations
- Follows same pattern as TeamService.deleteTeam()

This ensures satellites can still process pending kill commands while allowing
user and team deletion to proceed without FK constraint errors.

Author: Lasim

services/backend/src/db/schema-tables/satellites.ts

@@ -68,7 +68,7 @@ export const satelliteCommands = pgTable('satelliteCommands', {
   id: text('id').primaryKey(),
   satellite_id: text('satellite_id').notNull().references(() => satellites.id, { onDelete: 'cascade' }),
   command_type: text('command_type', {
-    enum: ['spawn', 'kill', 'restart', 'configure', 'health_check']
+    enum: ['spawn', 'kill', 'restart', 'configure', 'health_check', 'invalidate_user_token_cache']
   }).notNull(),
   priority: text('priority', { enum: ['immediate', 'high', 'normal', 'low'] }).notNull().default('normal'),
   payload: text('payload').notNull(), // JSON command data with team context

services/backend/src/routes/users/deleteMyAccount.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type { FastifyInstance, FastifyRequest } from 'fastify';
-import { and, eq, ne } from 'drizzle-orm';
+import { and, eq, ne, or } from 'drizzle-orm';
 import { getDb, getSchema } from '../../db/index';
 import { McpInstallationService } from '../../services/mcpInstallationService';
 import { SatelliteCommandService } from '../../services/satelliteCommandService';
@@ -360,15 +360,120 @@ export default async function deleteMyAccountRoute(server: FastifyInstance) {
         // Don't fail account deletion if event emission fails
       }
 
-      // STEP 7: Delete satellite commands targeting this team
+      // STEP 6.5: Invalidate satellite token caches
       server.log.debug({
-        operation: 'account_deletion_delete_satellite_commands',
+        operation: 'account_deletion_invalidate_satellite_cache',
+        userId,
+        userEmail: user.email
+      }, 'Sending cache invalidation commands to satellites');
+
+      try {
+        const satelliteCommandService = new SatelliteCommandService(db, server.log);
+        const commands = await satelliteCommandService.notifyUserDeletion(userId, user.email);
+
+        server.log.info({
+          operation: 'account_deletion_cache_invalidation_sent',
+          userId,
+          userEmail: user.email,
+          satelliteCommandsCreated: commands.length
+        }, `Cache invalidation sent to ${commands.length} satellites`);
+      } catch (cacheError) {
+        server.log.error(cacheError, 'Failed to send cache invalidation - continuing deletion');
+        // Non-fatal: caches expire naturally within 5 minutes
+      }
+
+      // STEP 7: Handle satellite commands - preserve pending commands
+      server.log.debug({
+        operation: 'account_deletion_handle_satellite_commands',
+        userId,
+        teamId
+      }, 'Handling satellite commands');
+
+      // Set target_team_id = NULL for PENDING commands for this team (allows team deletion without blocking satellite execution)
+      await db
+        .update(schema.satelliteCommands)
+        .set({ target_team_id: null })
+        .where(
+          and(
+            eq(schema.satelliteCommands.target_team_id, teamId),
+            eq(schema.satelliteCommands.status, 'pending')
+          )
+        );
+
+      // Delete non-pending satellite commands for this team (completed/failed/executing) since they're no longer needed
+      await db
+        .delete(schema.satelliteCommands)
+        .where(
+          and(
+            eq(schema.satelliteCommands.target_team_id, teamId),
+            or(
+              eq(schema.satelliteCommands.status, 'completed'),
+              eq(schema.satelliteCommands.status, 'failed'),
+              eq(schema.satelliteCommands.status, 'acknowledged'),
+              eq(schema.satelliteCommands.status, 'executing')
+            )
+          )
+        );
+
+      // Handle ALL commands created by this user (for any team) - set created_by = NULL for pending, delete completed
+      await db
+        .update(schema.satelliteCommands)
+        .set({ created_by: null })
+        .where(
+          and(
+            eq(schema.satelliteCommands.created_by, userId),
+            eq(schema.satelliteCommands.status, 'pending')
+          )
+        );
+
+      await db
+        .delete(schema.satelliteCommands)
+        .where(
+          and(
+            eq(schema.satelliteCommands.created_by, userId),
+            or(
+              eq(schema.satelliteCommands.status, 'completed'),
+              eq(schema.satelliteCommands.status, 'failed'),
+              eq(schema.satelliteCommands.status, 'acknowledged'),
+              eq(schema.satelliteCommands.status, 'executing')
+            )
+          )
+        );
+
+      server.log.info({
+        operation: 'account_deletion_satellite_commands_handled',
         userId,
         teamId
-      }, 'Deleting satellite commands for team');
+      }, 'Satellite commands handled - pending commands preserved');
 
-      await db.delete(schema.satelliteCommands)
-        .where(eq(schema.satelliteCommands.target_team_id, teamId));
+      // STEP 7.5: Delete satellite-related records
+      server.log.debug({
+        operation: 'account_deletion_delete_satellite_data',
+        userId,
+        teamId
+      }, 'Deleting satellite-related data');
+
+      // Delete satellite processes for user's default team
+      await db.delete(schema.satelliteProcesses)
+        .where(eq(schema.satelliteProcesses.team_id, teamId));
+
+      // Delete satellite usage logs for user's default team
+      await db.delete(schema.satelliteUsageLogs)
+        .where(eq(schema.satelliteUsageLogs.team_id, teamId));
+
+      // Delete MCP client activity records for the user
+      await db.delete(schema.mcpClientActivity)
+        .where(eq(schema.mcpClientActivity.user_id, userId));
+
+      // Delete MCP client activity metrics for the user
+      await db.delete(schema.mcpClientActivityMetrics)
+        .where(eq(schema.mcpClientActivityMetrics.user_id, userId));
+
+      server.log.info({
+        operation: 'account_deletion_satellite_data_deleted',
+        userId,
+        teamId
+      }, 'Satellite-related data deleted');
 
       // STEP 8: Delete the default team
       server.log.debug({

services/backend/src/services/satelliteCommandService.ts

@@ -5,7 +5,7 @@ import type { FastifyBaseLogger } from 'fastify';
 import { nanoid } from 'nanoid';
 
 // Match schema enum from satelliteCommands table
-export type CommandType = 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check';
+export type CommandType = 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check' | 'invalidate_user_token_cache';
 export type CommandPriority = 'immediate' | 'high' | 'normal' | 'low';
 
 export interface SatelliteCommand {
@@ -89,7 +89,7 @@ export class SatelliteCommandService {
     await this.db.insert(satelliteCommands).values(commands.map(cmd => ({
       id: cmd.id,
       satellite_id: cmd.satellite_id,
-      command_type: cmd.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check',
+      command_type: cmd.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check' | 'invalidate_user_token_cache',
       priority: cmd.priority as 'immediate' | 'high' | 'normal' | 'low',
       payload: cmd.payload,
       status: 'pending' as const,
@@ -158,7 +158,7 @@ export class SatelliteCommandService {
     await this.db.insert(satelliteCommands).values({
       id: command.id,
       satellite_id: command.satellite_id,
-      command_type: command.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check',
+      command_type: command.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check' | 'invalidate_user_token_cache',
       priority: command.priority as 'immediate' | 'high' | 'normal' | 'low',
       payload: command.payload,
       status: 'pending' as const,
@@ -236,7 +236,7 @@ export class SatelliteCommandService {
     await this.db.insert(satelliteCommands).values(commands.map(cmd => ({
       id: cmd.id,
       satellite_id: cmd.satellite_id,
-      command_type: cmd.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check',
+      command_type: cmd.command_type as 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check' | 'invalidate_user_token_cache',
       priority: cmd.priority as 'immediate' | 'high' | 'normal' | 'low',
       payload: cmd.payload,
       status: 'pending' as const,
@@ -345,4 +345,27 @@ export class SatelliteCommandService {
     });
   }
 
+  /**
+   * Notify satellites to invalidate all cached tokens for a SPECIFIC deleted user
+   * This ensures only the deleted user's tokens are removed from cache
+   */
+  async notifyUserDeletion(userId: string, userEmail: string): Promise<SatelliteCommand[]> {
+    this.logger.info({
+      operation: 'notify_user_deletion',
+      userId,
+      userEmail
+    }, `Notifying satellites to invalidate tokens for deleted user: ${userEmail}`);
+
+    return await this.createCommandForAllGlobalSatellites({
+      commandType: 'invalidate_user_token_cache',
+      priority: 'immediate',
+      payload: {
+        event: 'user_deleted',
+        user_id: userId,
+        user_email: userEmail
+      },
+      expiresInMinutes: 5
+    });
+  }
+
 }

services/satellite/src/server.ts

@@ -729,6 +729,10 @@ export async function createServer() {
       server.decorate('tokenIntrospectionService', tokenIntrospectionService);
       server.decorate('oauthTokenService', oauthTokenService);
 
+      // Configure command processor with token services for cache invalidation
+      commandProcessor.setTokenIntrospectionService(tokenIntrospectionService);
+      commandProcessor.setOAuthTokenService(oauthTokenService);
+
       server.log.info({
         operation: 'oauth_services_initialized',
         satellite_id: satelliteId,
@@ -819,6 +823,10 @@ export async function createServer() {
     server.decorate('tokenIntrospectionService', tokenIntrospectionService);
     server.decorate('oauthTokenService', oauthTokenService);
 
+    // Configure command processor with token services for cache invalidation
+    commandProcessor.setTokenIntrospectionService(tokenIntrospectionService);
+    commandProcessor.setOAuthTokenService(oauthTokenService);
+
     server.log.info({
       operation: 'oauth_services_initialized',
       satellite_id: satelliteId,

services/satellite/src/services/command-polling-service.ts

@@ -3,7 +3,7 @@ import { BackendClient } from './backend-client';
 
 export interface SatelliteCommand {
   id: string;
-  command_type: 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check';
+  command_type: 'spawn' | 'kill' | 'restart' | 'configure' | 'health_check' | 'invalidate_user_token_cache';
   priority: 'immediate' | 'high' | 'normal' | 'low';
   payload: {
     installation_id?: string;  // Primary identifier for MCP installations

services/satellite/src/services/command-processor.ts

@@ -28,6 +28,10 @@ export class CommandProcessor {
   private stdioDiscoveryManager: StdioToolDiscoveryManager | null;
   private unifiedToolDiscoveryManager: UnifiedToolDiscoveryManager | null = null;
   private eventBus: EventBus | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private tokenIntrospectionService: any | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private oauthTokenService: any | null = null;
   private processes: Map<string, ProcessInfo> = new Map();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private onConfigurationUpdate?: (config: any) => Promise<void>;
@@ -68,6 +72,22 @@ export class CommandProcessor {
     this.eventBus = eventBus;
   }
 
+  /**
+   * Set token introspection service for cache invalidation
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setTokenIntrospectionService(service: any): void {
+    this.tokenIntrospectionService = service;
+  }
+
+  /**
+   * Set OAuth token service for cache invalidation
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setOAuthTokenService(service: any): void {
+    this.oauthTokenService = service;
+  }
+
   /**
    * Emit status change event to backend
    */
@@ -175,6 +195,9 @@ export class CommandProcessor {
         case 'health_check':
           result = await this.handleHealthCheckCommand(command);
           break;
+        case 'invalidate_user_token_cache':
+          result = await this.handleInvalidateUserTokenCacheCommand(command);
+          break;
         default:
           throw new Error(`Unknown command type: ${command.command_type}`);
       }
@@ -778,6 +801,81 @@ export class CommandProcessor {
     };
   }
 
+  /**
+   * Handle invalidate_user_token_cache command
+   * Invalidates ONLY the specified user's cached tokens (preserves other users' caches)
+   */
+  private async handleInvalidateUserTokenCacheCommand(command: SatelliteCommand): Promise<CommandResult> {
+    const payload = command.payload;
+    const userId = payload.user_id as string;
+    const userEmail = payload.user_email as string;
+
+    if (!userId) {
+      throw new Error('user_id is required for user token cache invalidation');
+    }
+
+    this.logger.info({
+      operation: 'command_invalidate_user_token_cache',
+      command_id: command.id,
+      user_id: userId,
+      user_email: userEmail
+    }, `Invalidating cached tokens for SPECIFIC user: ${userEmail}`);
+
+    try {
+      let invalidatedCount = 0;
+
+      // Invalidate TokenIntrospectionService cache (Bearer tokens)
+      if (this.tokenIntrospectionService) {
+        const count = this.tokenIntrospectionService.invalidateUserTokens(userId);
+        invalidatedCount += count;
+        this.logger.debug({
+          operation: 'token_introspection_cache_invalidated',
+          user_id: userId,
+          count
+        }, `Invalidated ${count} bearer token cache entries for user ${userId}`);
+      }
+
+      // Invalidate OAuthTokenService cache (MCP OAuth tokens)
+      if (this.oauthTokenService) {
+        const count = this.oauthTokenService.clearUserCache(userId);
+        invalidatedCount += count;
+        this.logger.debug({
+          operation: 'oauth_token_cache_invalidated',
+          user_id: userId,
+          count
+        }, `Invalidated ${count} OAuth token cache entries for user ${userId}`);
+      }
+
+      this.logger.info({
+        operation: 'user_token_cache_invalidated',
+        command_id: command.id,
+        user_id: userId,
+        user_email: userEmail,
+        total_invalidated: invalidatedCount
+      }, `Successfully invalidated ${invalidatedCount} cached tokens for user ${userEmail}`);
+
+      return {
+        command_id: command.id,
+        status: 'completed',
+        result: {
+          user_id: userId,
+          user_email: userEmail,
+          invalidated_count: invalidatedCount,
+          message: `Invalidated ${invalidatedCount} cached tokens for user ${userEmail}`
+        }
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error({
+        operation: 'command_invalidate_user_token_cache_failed',
+        command_id: command.id,
+        user_id: userId,
+        error: errorMessage
+      }, `User token cache invalidation failed: ${errorMessage}`);
+      throw error;
+    }
+  }
+
   /**
    * Handle credential validation for a specific installation (Phase 9)
    * Tries to call tools/list with the installation's credentials

services/satellite/src/services/oauth-token-service.ts

@@ -254,4 +254,28 @@ export class OAuthTokenService {
       operation: 'oauth_tokens_cache_cleared_all'
     }, 'Cleared all OAuth token cache');
   }
+
+  /**
+   * Clear all cached tokens for a specific user
+   */
+  clearUserCache(userId: string): number {
+    let cleared = 0;
+
+    // Cache key format: `${installationId}:${userId}:${teamId}`
+    for (const cacheKey of this.tokenCache.keys()) {
+      const parts = cacheKey.split(':');
+      if (parts.length === 3 && parts[1] === userId) {
+        this.tokenCache.delete(cacheKey);
+        cleared++;
+      }
+    }
+
+    this.logger.info({
+      operation: 'oauth_tokens_user_cache_cleared',
+      user_id: userId,
+      cleared_count: cleared
+    }, `Cleared ${cleared} OAuth cache entries for user ${userId}`);
+
+    return cleared;
+  }
 }