provisioning
    ↓
command_received (satellite received configure command)
    ↓
connecting (spawning MCP server process or connecting to HTTP/SSE)
    ↓
discovering_tools (calling tools/list)
    ↓
syncing_tools (sending tools to backend)
    ↓
online (ready for use)

online
    ↓
restarting (user updated config, backend sets status immediately)
    ↓
connecting (satellite receives command, restarts server)
    ↓
discovering_tools
    ↓
online

online
    ↓
offline/error (server unreachable or error response)
    ↓
[automatic recovery when server comes back]
    ↓
connecting
    ↓
discovering_tools
    ↓
online

online
    ↓
requires_reauth (401/403 response or token refresh failed)
    ↓
[user re-authenticates via dashboard]
    ↓
connecting
    ↓
discovering_tools
    ↓
online

online
    ↓
(stdio process crashes)
    ↓
connecting (auto-restart attempt 1)
    ↓
(crashes again within 5 minutes)
    ↓
connecting (auto-restart attempt 2)
    ↓
(crashes again within 5 minutes)
    ↓
permanently_failed (manual intervention required)

// services/satellite/src/services/unified-tool-discovery-manager.ts

export type ServerAvailabilityStatus =
  | 'online'
  | 'offline'
  | 'error'
  | 'requires_reauth'
  | 'permanently_failed'
  | 'connecting'
  | 'discovering_tools';

export interface ServerStatusEntry {
  status: ServerAvailabilityStatus;
  lastUpdated: Date;
  message?: string;
}

class UnifiedToolDiscoveryManager {
  private serverStatus: Map<string, ServerStatusEntry> = new Map();

  // Set server status (called by discovery managers and MCP wrapper)
  setServerStatus(serverSlug: string, status: ServerAvailabilityStatus, message?: string): void {
    this.serverStatus.set(serverSlug, {
      status,
      lastUpdated: new Date(),
      message
    });
  }

  // Check if server is available for tool execution
  isServerAvailable(serverSlug: string): boolean {
    const statusEntry = this.serverStatus.get(serverSlug);
    if (!statusEntry) return true; // Unknown = available (safe default)
    return statusEntry.status === 'online';
  }

  // Get all tools, filtered by server status
  getAllTools(): ToolMetadata[] {
    const allTools = this.getAllToolsUnfiltered();
    return allTools.filter(tool => {
      const serverSlug = tool.tool_path.split(':')[0];
      return this.isServerAvailable(serverSlug);
    });
  }
}

// services/satellite/src/services/remote-tool-discovery-manager.ts

// On successful discovery
this.statusCallback?.(serverSlug, 'online');

// On connection error
const { status, message } = RemoteToolDiscoveryManager.getStatusFromError(error);
this.statusCallback?.(serverSlug, status, message);

// services/satellite/src/services/stdio-tool-discovery-manager.ts

// On successful discovery
this.statusCallback?.(processId, 'online');

// On discovery error
this.statusCallback?.(processId, 'error', errorMessage);

// UnifiedToolDiscoveryManager.getAllTools() filters by status
const tools = toolDiscoveryManager.getAllTools(); // Only 'online' servers

// Tools from offline/error/requires_reauth servers are hidden

// services/satellite/src/core/mcp-server-wrapper.ts

const serverSlug = toolPath.split(':')[0];
const statusEntry = this.toolDiscoveryManager?.getServerStatus(serverSlug);

// Block execution for non-recoverable states
if (statusEntry?.status === 'requires_reauth') {
  return {
    error: `Tool cannot be executed - server requires re-authentication.

Status: ${statusEntry.status}
The server requires re-authentication. Please re-authorize in the dashboard.

Unavailable server: ${serverSlug}`
  };
}

// Allow execution for offline/error (enables recovery detection)