TASK-003: Document process-local constraint for RuntimeState and SessionCache

- Add comprehensive docstring to runtime_state.py explaining single-process
  constraint, impacts in multi-worker deployments, and solution approach
- Add comprehensive docstring to session_cache.py explaining process-local
  cache limitation, security implications, and Redis/database alternatives
- Update Architecture.md to clarify session cache is process-local and
  describe single-worker enforcement via TASK-002
- Update Architecture.md runtime state section with detailed explanation of
  per-process state and multi-worker impacts
- Add Backend-Development.md section 13.7.2 documenting session cache
  pluggability pattern with example Redis implementation
- All tests pass; linting passes; type checking has pre-existing errors

This is the short-term fix for TASK-003: enforce single-worker deployment
(TASK-002) and document the constraint clearly. The long-term fix (Redis
backend) is deferred as a follow-up.

backend/app/utils/runtime_state.py

@@ -6,11 +6,36 @@ framework state bag limited to shared infrastructure handles and immutable
 configuration while still allowing existing code to access runtime values via
 attribute proxying.
 
-RuntimeState is designed for a single-process, single-worker asyncio
-deployment. Mutations must complete without awaiting across read-modify-write
-sequences. If BanGUI is ever deployed with multiple workers or across processes,
-this module must be replaced with a shared backend such as Redis or shared
-memory.
+⚠️  SINGLE-PROCESS CONSTRAINT
+==============================
+
+RuntimeState is designed for a single-process, single-worker asyncio deployment.
+This means:
+  - Each process has its own independent copy of all runtime state.
+  - Changes to runtime_state in one process are NOT visible to other processes.
+  - Mutations must complete without awaiting across read-modify-write sequences
+    (cooperative scheduling within a single event loop is safe).
+
+IMPACT IN MULTI-WORKER DEPLOYMENTS:
+  - Logout processed by worker A clears the session from A's in-memory cache,
+    but worker B still has that session in its own cache and will accept it.
+  - Health status updates (server_status) received by worker A are invisible
+    to worker B's dashboard responses — each worker reports stale data.
+  - fail2ban activation/recovery tracking (pending_recovery, last_activation)
+    is per-worker and unreliable across processes.
+
+MULTI-WORKER SOLUTION:
+  To deploy BanGUI with multiple workers (e.g., via gunicorn -w 4), you must:
+    1. Replace RuntimeState with a shared store (Redis, shared memory, database).
+    2. Replace InMemorySessionCache with RedisSessionCache (see session_cache.py).
+    3. Ensure all workers use the same backend for coordination.
+
+SINGLE-WORKER ENFORCEMENT:
+  See TASK-002 in Docs/Tasks.md for deployment configuration that enforces
+  single-worker mode, preventing this issue entirely.
+
+For now, BanGUI is deployed as single-worker only — this constraint is
+acceptable and keeps the implementation simple.
 """
 
 from __future__ import annotations

backend/app/utils/session_cache.py

@@ -3,6 +3,50 @@
 This module defines a cache interface for authenticated sessions and a default
 process-local in-memory implementation. The backend can swap the cache
 implementation without changing the authentication dependency logic.
+
+⚠️  PROCESS-LOCAL CONSTRAINT (InMemorySessionCache)
+====================================================
+
+InMemorySessionCache stores validated sessions in a process-local dict.
+This means:
+  - Each worker process has its own independent session cache.
+  - A session invalidated (logout) by worker A is still valid in worker B.
+  - Changes to the cache in one process are NOT visible to other processes.
+
+IMPACT IN MULTI-WORKER DEPLOYMENTS:
+  - User logs out (worker A clears session from its cache).
+  - User makes a new request → routed to worker B.
+  - Worker B still has the stale session in its cache → request is accepted.
+  - User appears still logged in (from their perspective).
+
+  This is a security issue: logout does not work reliably across workers.
+
+MULTI-WORKER SOLUTION:
+  To deploy BanGUI with multiple workers (e.g., via gunicorn -w 4), replace
+  InMemorySessionCache with a shared backend such as:
+    - RedisSessionCache — backed by Redis (recommended for production).
+    - DatabaseSessionCache — backed by SQLite or PostgreSQL.
+    - SharedMemorySessionCache — backed by IPC (for local multi-process).
+
+  The SessionCache Protocol is already designed for pluggable backends:
+    class SessionCache(Protocol):
+        def get(token: str) -> Session | None: ...
+        def set(token: str, session: Session, ttl_seconds: float) -> None: ...
+        def invalidate(token: str) -> None: ...
+        def clear() -> None: ...
+
+  To add Redis support:
+    1. Create RedisSessionCache in this module (implements SessionCache).
+    2. Update runtime_state.set_runtime_settings() to instantiate RedisSessionCache
+       when REDIS_URL is configured.
+    3. See Backend-Development.md § "Session Cache Pluggability" for details.
+
+SINGLE-WORKER ENFORCEMENT:
+  See TASK-002 in Docs/Tasks.md for deployment configuration that enforces
+  single-worker mode, preventing this issue entirely.
+
+For now, BanGUI is deployed as single-worker only — this constraint is
+acceptable and keeps the implementation simple.
 """
 
 from __future__ import annotations