chore(redis): clarify async client initialization pattern in get_redis_client documentation

[mrveiss]

Issue

The async Redis client initialization pattern in get_redis_client() can be confusing:

# Returns a coroutine, not a client
redis_coro = get_redis_client(async_client=True, database='main')

# Must be awaited to get actual client
client = await redis_coro

This led to a bug in KB initialization (Issue #3962) where the coroutine wasn't properly awaited in a single statement, creating a double-coroutine issue.

Root Cause

When async_client=True, get_redis_client() returns a coroutine (because it calls async get_async_client()). This is correct but not obvious from:

1. Function name ("get_" implies sync get, not coroutine)
2. Function signature (no async keyword, returns Union[redis.Redis, async_redis.Redis, None])
3. Docstring examples could be clearer

Suggested Improvements

1. Add prominent warning in docstring that async_client=True returns coroutine, not client
2. Add example showing correct pattern: separate assignment from await
3. Consider renaming or adding async wrapper for clarity
4. Consider adding lint rule to catch improper async Redis client initialization

References

• Bug fixed: Issue bug(redis): KB initialization fails with 'coroutine' object has no attribute 'ping' #3962 (KB coroutine handling - commit 033e2cb)
• Session: KB initialization failure debug (2026-04-08)