fix(cache): honor the host-declared conversation key on the affinity-key path (salvage of #97158)

[kshitijk4poor]

Summary

Salvage of PR #97158 by @JoaoMarcos44 onto current main, authorship preserved, plus a one-line fix for the CI failure the PR branch carried.

Lets the host declare the logical conversation behind its physical session ids, and makes all four conversation-affinity surfaces consult that declaration: prompt_cache_key on both OpenAI-wire transports, the OpenRouter/Nous sticky session_id, and xAI's x-grok-conv-id. Hosts that mint one physical session per RESPONSE (Hermes Studio group chat, POST /v1/responses with client-managed history) re-keyed all four on every reply, so the conversation never landed back on the routing bucket it warmed (#96811, the cost half of #96570). The declared key is the already-in-hand gateway_session_key (X-Hermes-Session-Key / build_session_key), hashed to gwk_<sha256[:24]> so no platform/chat/user identifier reaches a provider. Explicit fork children (/branch, delegate, tool) and background-review forks keep their own scope (#79161); no id-syntax inference (#79017's failure class stays closed — see #96768's negative controls).

Changes

• Contributor commit (verbatim): agent/portal_tags.py affinity-scope ContextVar, agent/prompt_cache_scope.py declared_conversation_scope (memoized, fork-boundary-aware, degrades to physical id on DB error), hermes_state.py public is_explicit_fork_child, openrouter/nous profile fallback chains, run_agent.py scope publication for turns and out-of-turn compaction, 365-line test file
• Follow-up commit (ours): initialize affinity_token = None alongside token = None in run_conversation — the turn-lease timeout/interrupt early paths return before set_affinity_scope() runs, and the finally reads the name unconditionally → UnboundLocalError. This was exactly the 4 red cross-process lease tests on the PR's CI; reproduced locally, red→green with this init.

Review notes

• Memoization verified: the fork-check DB read happens once per session segment, not per API call; no gwk_/physical oscillation path (error → not memoized → retried until success; lineage hit → pinned).
• Mid-conversation upgrade: existing gateway conversations take ONE provider-side affinity re-key on first response after upgrade, then stay stable — strictly better than the per-response churn being fixed.
• Known limitation (documented, not blocking): gwk_ is an unsalted hash of the chat key, so two installs serving the same chat share a sticky bucket — pre-existing property of build_session_key, edge case.
• Coexists with test(cache): pin the prompt-cache scope isolation invariant for per-response session ids #96768's isolation invariants (its agents declare nothing → unchanged fallback path).

Validation

Suite	Result
test_declared_conversation_scope + test_prompt_cache_scope + transports/test_chat_completions + test_cross_process_turn_lease + test_run_agent	390 passed
PR branch CI (before fix)	4 failed in the lease suites
This branch (after one-line init)	12/12 lease tests green

Closes #97158. Refs #96811, #96570.

[kshitijk4poor]

Status: converting to draft — @cervantesh's review on #97158 contains one blocker this salvage fixes and one it does not.

Fixed here: the cleanup regression (blocker 2). affinity_token is initialized alongside token, and the 4 previously-red cross-process lease tests are green on this branch (12/12).

Verified still present (blocker 1): the /new lifetime violation. Reproduced on this exact head with the resolver + a real SessionDB:

db.create_session('sess-A', source='telegram')
a = agent(session_id='sess-A', _gateway_session_key=K)
db.create_session('sess-B', source='telegram')   # what /new produces — same chat key K
b = agent(session_id='sess-B', _gateway_session_key=K)
resolve_prompt_cache_scope(a)  # gwk_e545a9eb80a9283345539b21
resolve_prompt_cache_scope(b)  # gwk_e545a9eb80a9283345539b21  ← does NOT rotate

gateway/session.py::reset_session() mints a fresh physical id but keeps the chat key, so declared-key precedence maps pre- and post-/new conversations onto one affinity scope — violating the #79017/#86733 contract (continuity across compression rotation, reset on /new//branch), and doing so for every native messaging gateway, not just per-response hosts.

What a correct carrier needs (matching the review's criteria): stable across per-response physical ids within one logical conversation, rotating on /new. The chat key alone cannot provide that — it needs a per-conversation epoch mixed in (e.g. a value minted at reset_session()/conversation creation and carried alongside the key), which is a design change to the declaration contract, not a follow-up commit.

Holding this salvage as draft until the lifecycle question is settled on #97158. The affinity_token fix commit here remains valid for whichever revision lands.

[kshitijk4poor]

Closing this salvage draft alongside #97158: the lifecycle blocker (declared chat-key scope does not rotate on /new — reproduced on this exact head, see the draft note above) requires a revision of the declaration contract itself (key + per-conversation epoch, covering the /v1/responses/Studio boundaries), so the eventual fix will be a fresh PR implementing that contract rather than commits stacked on this branch. @JoaoMarcos44's commit and the affinity_token cleanup fix here will be carried into that revision with authorship preserved.