fix(honcho): isolate session routing for multi-user gateway (#1500)

Salvaged from PR #1470 by adavyas.

Core fix: Honcho tool calls in a multi-session gateway could route to
the wrong session because honcho_tools.py relied on process-global
state. Now threads session context through the call chain:
  AIAgent._invoke_tool() → handle_function_call() → registry.dispatch()
  → handler **kw → _resolve_session_context()

Changes:
- Add _resolve_session_context() to prefer per-call context over globals
- Plumb honcho_manager + honcho_session_key through handle_function_call
- Add sync_honcho=False to run_conversation() for synthetic flush turns
- Pass honcho_session_key through gateway memory flush lifecycle
- Harden gateway PID detection when /proc cmdline is unreadable
- Make interrupt test scripts import-safe for pytest-xdist
- Wrap BibTeX examples in Jekyll raw blocks for docs build
- Fix thread-order-dependent assertion in client lifecycle test
- Expand Honcho docs: session isolation, lifecycle, routing internals

Dropped from original PR:
- Indentation change in _create_request_openai_client that would move
  client creation inside the lock (causes unnecessary contention)

Co-authored-by: adavyas <adavyas@users.noreply.github.com>

website/docs/developer-guide/gateway-internals.md

@@ -86,7 +86,33 @@ The gateway also runs maintenance tasks such as:
 
 ## Honcho interaction
 
-When Honcho is enabled, the gateway can keep persistent Honcho managers aligned with session lifetimes and platform-specific session keys.
+When Honcho is enabled, the gateway keeps persistent Honcho managers aligned with session lifetimes and platform-specific session keys.
+
+### Session routing
+
+Honcho tools (`honcho_profile`, `honcho_search`, `honcho_context`, `honcho_conclude`) need to execute against the correct user's Honcho session. In a multi-user gateway, the process-global module state in `tools/honcho_tools.py` is insufficient — multiple sessions may be active concurrently.
+
+The solution threads session context through the call chain:
+
+```
+AIAgent._invoke_tool()
+  → handle_function_call(honcho_manager=..., honcho_session_key=...)
+    → registry.dispatch(**kwargs)
+      → _handle_honcho_*(args, **kw)
+        → _resolve_session_context(**kw)   # prefers explicit kwargs over module globals
+```
+
+`_resolve_session_context()` in `honcho_tools.py` checks for `honcho_manager` and `honcho_session_key` in the kwargs first, falling back to the module-global `_session_manager` / `_session_key` for CLI mode where there's only one session.
+
+### Memory flush lifecycle
+
+When a session is reset, resumed, or expires, the gateway flushes memories before discarding context. The flush creates a temporary `AIAgent` with:
+
+- `session_id` set to the old session's ID (so transcripts load correctly)
+- `honcho_session_key` set to the gateway session key (so Honcho writes go to the right place)
+- `sync_honcho=False` passed to `run_conversation()` (so the synthetic flush turn doesn't write back to Honcho's conversation history)
+
+After the flush completes, any queued Honcho writes are drained and the gateway-level Honcho manager is shut down for that session key.
 
 ## Related docs
 

website/docs/user-guide/features/honcho.md

@@ -247,6 +247,25 @@ Dialectic queries scale reasoning effort with message complexity:
 
 The gateway creates short-lived `AIAgent` instances per request. Honcho managers are owned at the gateway session layer (`_honcho_managers` dict) so they persist across requests within the same session and flush at real session boundaries (reset, resume, expiry, server stop).
 
+#### Session Isolation
+
+Each gateway session (e.g., a Telegram chat, a Discord channel) gets its own Honcho session context. The session key — derived from the platform and chat ID — is threaded through the entire tool dispatch chain so that Honcho tool calls always execute against the correct session, even when multiple users are messaging concurrently.
+
+This means:
+- **`honcho_profile`**, **`honcho_search`**, **`honcho_context`**, and **`honcho_conclude`** all resolve the correct session at call time, not at startup
+- Background memory flushes (triggered by `/reset`, `/resume`, or session expiry) preserve the original session key so they write to the correct Honcho session
+- Synthetic flush turns (where the agent saves memories before context is lost) skip Honcho sync to avoid polluting conversation history with internal bookkeeping
+
+#### Session Lifecycle
+
+| Event | What happens to Honcho |
+|-------|------------------------|
+| New message arrives | Agent inherits the gateway's Honcho manager + session key |
+| `/reset` | Memory flush fires with the old session key, then Honcho manager shuts down |
+| `/resume` | Current session is flushed, then the resumed session's Honcho context loads |
+| Session expiry | Automatic flush + shutdown after the configured idle timeout |
+| Gateway stop | All active Honcho managers are flushed and shut down gracefully |
+
 ## Tools
 
 When Honcho is active, four tools become available. Availability is gated dynamically — they are invisible when Honcho is disabled.