Summary

• Problem: Issue [Bug] /v1/chat/completions: second request with same x-openclaw-session-key during in-flight turn runs in isolated session, loses memory scope #84575 reports that two requests carrying the same x-openclaw-session-key at the OpenAI-compatible endpoints (/v1/chat/completions, /v1/responses) can run in separate sessions when the second arrives while the first is still in flight (e.g. a follow-up message sent before the first turn finishes). The later request starts from an empty session — session_status reports Context: 0/... and memory tools (memory_search) return nothing — so the agent loses all conversation/recall scope for that turn. Multi-user / multi-tab setups and any client that fires a quick follow-up before the previous turn finishes are exposed. Reporter juergenvh added gateway-side evidence on 2026-05-21 confirming the same shape against an embedded runtime.
• Root Cause: Session identity is resolved by resolveSession (src/agents/command/session.ts) before the per-session execution lane is entered. When a session key has no fresh stored entry, resolveSession mints a brand-new sessionId via crypto.randomUUID(). Two commands for the same key that both reach this point before either persists the key→sessionId mapping each mint their own id. The per-session execution lane is keyed by session key, but it only serializes execution, not identity — so the second command runs against a different transcript and an empty memory scope. The WebChat chat.send path already guards concurrent sends; the agent-command path used by the OpenAI-compatible endpoints had no equivalent, leaving the resolve-then-mint step racy. resolveSession is intentionally synchronous (used by many sync callers), so the lock has to live one layer up at the agent-command async caller.
• Fix: Add resolveSessionWithReservation (src/agents/command/session-resolution-reservation.ts) and call it from the agent-command pipeline (src/agents/agent-command.ts) in place of resolveSession. It serializes only the brand-new-session path, per session key: the first command persists the key→sessionId mapping inside a short critical section; any concurrent command re-resolves inside the lock, sees the reserved entry, and adopts the same sessionId instead of forking. This enforces the invariant "same session key ⇒ one session id" at the layer that owns session identity (so all ingress surfaces routed through agent-command benefit, not just one endpoint). Established sessions and explicit-sessionId runs skip the lock entirely (no added latency on the steady-state hot path); the critical section is independent of the per-session execution lane and completes before execution, so it cannot deadlock with it; the reserved entry is the same minimal mapping the command already persists moments later, so no new orphaning behavior; and internal handoffs (sessionEffects === "internal") also bypass the lock so they never write a visible store row, preserving the suppressVisibleSessionEffects contract.
• What changed:
  • src/agents/command/session-resolution-reservation.ts: new resolveSessionWithReservation helper plus a per-session-key serialization queue. ResolveSessionInput declares clone?: boolean (forwarded to resolveSession) and suppressVisibleSessionEffects?: boolean (internal-handoff opt-out).
  • src/agents/command/session-resolution-reservation.test.ts: regression coverage — pre-fix race repro, concurrent-same-key convergence, follow-up reuse, explicit-sessionId passthrough, and the internal-handoff no-visible-row contract.
  • src/agents/agent-command.ts: resolve through resolveSessionWithReservation (one-line replace at prepareAgentCommandExecution); pass clone: false and suppressVisibleSessionEffects: opts.sessionEffects === "internal".
• What did NOT change (scope boundary):
  • resolveSession semantics, the per-session execution lane, and the session-store schema are untouched. The helper composes existing primitives (resolveSession + persistSessionEntry) inside a per-key async mutex.
  • The explicit-sessionId path, ordinary single requests, established (already-persisted, fresh) sessions, and internal handoffs all bypass the reservation lock entirely.
  • Other prepareAgentCommandExecution regions touched by sibling PRs [Fix] Deliver restart recovery replies #86089 / fix(agents): persist user turn before attempt failures #86764 are in different regions of the function; this PR rebases cleanly on current origin/main with zero conflicts.
  • No config keys, gateway protocol, streaming/delivery behavior, plugin SDK, or session-store schema change.
  • No CHANGELOG.md edit (release-owned); no package.json / lockfile / shrinkwrap edit (Dependency Guard not applicable).

Reproduction

1. Configure an agent reachable through the OpenAI-compatible endpoint with a stable x-openclaw-session-key.
2. Send a long, multi-tool request for that session key.
3. While it is still streaming, send a second request with the same x-openclaw-session-key.

• Before: the second turn runs in an isolated session (session_status shows Context: 0/...); it has no recall of the in-flight conversation. On-disk session store ends up with two agent:main:<key> entries pointing at different sessionIds, and the sessions directory has two transcript files.
• After: both turns share one session — the second adopts the first request's sessionId and retains conversation/recall scope. On-disk session store has a single agent:main:<key> entry; the sessions directory has exactly one transcript file.

Real behavior proof

• Behavior addressed: concurrent commands carrying the same x-openclaw-session-key must converge on one sessionId and one transcript; once the first command persists the key→sessionId mapping, any concurrent same-key command re-resolves inside the lock and adopts the same id instead of forking an isolated, memory-less session.
• Real environment tested: Linux x64, Node 22.22, OpenClaw Gateway built from this branch serving POST /v1/chat/completions, routed to a local OpenAI-compatible model endpoint with an isolated on-disk session store. Real curl requests, real on-disk session-store JSON, real session transcript files.
• Exact steps or command run after this patch: launched openclaw gateway run (this branch) bound to the OpenAI-compatible endpoints; fired two concurrent curl calls to /v1/chat/completions carrying an identical x-openclaw-session-key: final-1779465436; inspected the on-disk session store and the per-session transcript files. Unit-level regression: node scripts/run-vitest.mjs src/agents/command/session-resolution-reservation.test.ts.
• Evidence after fix (verbatim live console output):

two concurrent requests, identical x-openclaw-session-key=final-1779465436 (23:57:16 start -> 23:57:32 done)
$ curl .../v1/chat/completions -H 'x-openclaw-session-key: final-1779465436' -d '{"model":"openclaw","messages":[{"role":"user","content":"first turn"}]}' &
$ curl .../v1/chat/completions -H 'x-openclaw-session-key: final-1779465436' -d '{"model":"openclaw","messages":[{"role":"user","content":"second turn concurrent"}]}' &
A: {"id":"chatcmpl_189760ea-7315-4873-a704-bd3bc6b51fa7", ... "choices":[{"message":{"role":"assistant","content":"ok"},"finish_reason":"stop"}]}
B: {"id":"chatcmpl_9408b3a5-f114-45ba-aa49-f8d5e8ff3940", ... "choices":[{"message":{"role":"assistant","content":"ok"},"finish_reason":"stop"}]}

resolved session for that key (single store entry, single id):
agent:main:final-1779465436 -> sessionId bc472c1b-9cbb-4a8e-b337-51a53d3e2aef

session transcripts for that id (exactly one, so no fork):
bc472c1b-9cbb-4a8e-b337-51a53d3e2aef.jsonl

• Observed result after fix: two distinct concurrent runs against one session key converged on one sessionId and one transcript file — the second request joined the in-flight session instead of forking an isolated, memory-less one. The on-disk session store recorded a single reservation-shaped entry { sessionId, updatedAt, sessionStartedAt } written by resolveSessionWithReservation. The explicit-sessionId path and steady-state established-session path are visibly unchanged (no lock entered).
• Code-path coverage: node scripts/run-vitest.mjs src/agents/command/session-resolution-reservation.test.ts (10 passed across 2 files) covers the pre-fix race repro (two resolveSession calls fork distinct sessionIds), concurrent same-key convergence, follow-up reuse of the reserved id, explicit-sessionId passthrough, and the new internal-handoff contract (suppressVisibleSessionEffects: true does not write a visible session-store row).
• What was not tested: a multi-hour production deployment and a third-party hosted model provider were not exercised; the live run used a local OpenAI-compatible model endpoint and an isolated session store. Cross-PR merge order with [Fix] Deliver restart recovery replies #86089 / fix(agents): persist user turn before attempt failures #86764 was not simulated end-to-end, but the branch rebases cleanly on current origin/main with zero conflicts.

Risk / Mitigation

• Risk: per-key serialization could add latency or deadlock with the per-session execution lane. Mitigation: only the brand-new-session path takes the lock; established sessions, explicit-sessionId runs, and internal handoffs bypass it, so the steady-state hot path is unchanged. The critical section is resolveSession (sync) + one store write and completes before the execution lane is entered, so it cannot deadlock with it.
• Risk: an early-reserved entry could orphan if the run aborts immediately after reservation. Mitigation: the reserved entry is the same minimal sessionId mapping the command persists moments later anyway; the orphan window matches the pre-fix crypto.randomUUID() + persistSessionEntry window — no new orphaning shape.
• Risk: cross-PR conflict with [Fix] Deliver restart recovery replies #86089 (restart recovery) and fix(agents): persist user turn before attempt failures #86764 (persist user turn) inside prepareAgentCommandExecution. Mitigation: codegraph reports function-level overlap; actual diff regions do not collide. This PR rebases cleanly onto current origin/main (zero conflict). Merge order is independent.
• Risk: ClawSweeper's prior P1 blockers — (1) ResolveSessionInput omitted clone, which the call site still passes; (2) reservation wrote a visible session-store row before agentCommandInternal derived suppressVisibleSessionEffects from opts.sessionEffects === "internal", breaking the documented internal-handoff contract. Mitigation: both addressed — clone?: boolean added to ResolveSessionInput and forwarded to resolveSession; suppressVisibleSessionEffects?: boolean added and short-circuits the lock+persist for internal runs; the call site computes the flag inline from opts.sessionEffects; a new test asserts internal handoffs do not write a visible row.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration
• Sessions / storage

Linked Issue/PR

Fixes #84575