Skip to content

fix: bind grok-shell sessions via x-grok-session-id so compression state stops forking - #1038

Merged
ranxianglei merged 1 commit into
ranxianglei:masterfrom
elevenfund:2026-09-20_grok-session-header
Sep 20, 2026
Merged

ranxianglei merged 1 commit into
ranxianglei:masterfrom
elevenfund:2026-09-20_grok-session-header

Conversation

@elevenfund

Copy link
Copy Markdown
Contributor

Problem

grok-shell (xAI's CLI) stamps a per-session UUID on every model request as x-grok-session-id (the parallel x-grok-conv-id carries the same value). The identity whitelist did not know either name, so every grok request fell through to anonymous prefix-affinity — and grok-shell reorders its replayed history head between turns (message order/composition changes, not pure append), which breaks the byte-exact hash chain and forks a brand-new session on every request.

Net effect: compression state never accumulates (every session ends with 0 blocks; nudges re-evaluate from scratch forever), exactly the failure mode session-id.ts warns about for identity-less clients.

Captured from grok-shell 1.0.34 (headless, one turn — identity headers on both the main and the turn-summary request):

x-grok-session-id: 01a0bdaf-9378-7102-9306-6271c4224e0e
x-grok-conv-id:    01a0bdaf-9378-7102-9306-6271c4224e0e
x-grok-conv-group-id: 3c394fc4-...
x-grok-agent-id:   be3a529d-...
x-grok-req-id:     05dcb486-...

Fix

Add x-grok-session-id (with x-grok-conv-id as fallback) to the header whitelist, placed with the other client-specific headers — same trust class as x-claude-code-session-id: a client-specific name no other agent sends, so it can never collide with or displace a stronger signal (x-bili-plugin-conversation still outranks everything).

Testing

  • New tests/grok-session-identity.test.ts (3 cases, all green): verbatim session binding, two concurrent session ids stay two sessions, x-grok-conv-id fallback.
  • Full suite: 2055/2060 pass; the 3 failures (claude-native installer round-trip ×2, isMitmHost whitelist ×1) reproduce identically on a clean origin/master checkout in the same environment — they touch real ~/.claude state and are unrelated to this diff.
  • npm run typecheck clean; diff touches no package.json version field.

Verified end-to-end

Proxy running this build, two independent real grok-shell sessions driven through it: each routes to its own UUID-named session, messages accumulate per session, zero anonymous pfa- forks, and compression blocks persist across requests (previously: ~20 forks in 15 minutes, every session 0 blocks).

…ate stops forking

grok-shell (xAI CLI) stamps a per-session UUID on every model request as
x-grok-session-id (x-grok-conv-id carries the same value). The whitelist
did not know them, so every request was anonymous and fell to
prefix-affinity — which forked a fresh session every turn because
grok-shell reorders its replayed history head between turns, leaving
compression state unable to accumulate (every session ended with 0 blocks).
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewed — correct, minimal, well-tested, and independently verified. Ready to merge once the branch is brought up to current master (details below). I did not merge — that's human-only per repo rules.

What I checked

  • Pulled the head (a4158ab, single commit) and confirmed the real change is exactly two files: src/session-id.ts (+9/−1) and the new tests/grok-session-identity.test.ts (+140).
  • Rebased it onto current master (26417a9) in an isolated worktree and ran the full gate there: typecheck clean · full suite green (all 3 grok tests pass) · build succeeds. None of the commits this PR is behind touch the identity path, so the rebase is conflict-free.
  • CI on the PR head is fully green (cross-platform test matrix, build-artifact, version-guard, and the E2E checks).

Code correctness

  • The whitelist insertion at src/session-id.ts:57 places x-grok-session-id / x-grok-conv-id immediately after x-claude-code-session-id, ahead of every generic session-* name. Precedence is preserved end-to-end: x-bili-plugin-conversation is still gated first by the plugin marker, x-claude keeps its slot, and because the loop returns the first hit, the grok headers can only ever bind a request that actually sends them — they cannot collide with or displace a stronger signal, and no other client emits them, so existing bindings are untouched.
  • Resolution confirmed at src/server.ts:1206 (clientConv ?? sessionHeader): the whitelist value wins over any configured sessionHeader, which is exactly why the integration tests (which set sessionHeader: "x-acp-session") exercise the real grok path rather than the configured default.
  • No wire-shape change: the identity value flows through the existing affinityToken() path (src/server.ts:1375) identically to claude/codex/opencode today, and the grok UUID was already present on every client request. This diff only makes the proxy use a header the client already sends — nothing new is injected upstream.
  • Diagnosis matches the documented identity-less-client failure mode (anonymous → prefix-affinity fingerprint collision → orphan/fork → 0 blocks accumulated) and aligns with the "prefer native stable identifiers" guardrail.

Tests

Three integration cases against the real startServer rig cover the load-bearing behaviors: verbatim binding (no pfa- anonymous fork), two concurrent ids staying two sessions (per-terminal isolation), and the x-grok-conv-id fallback. Good coverage for the actual bug.

One action before merge

The branch is currently behind master by 7 commits (incl. #1033, #1034, #1037). It's an external fork, so please use GitHub's "Update branch" button (or rebase + force-push your branch). I verified the resulting tree is green, so it should land cleanly.

Verdict

Passes the auto-merge criteria on scope/diff/tests/greenness, with one deliberate exception: §7.4's "must stay human" list explicitly covers identity/session-binding logic, which is precisely what this touches — so the merge itself is a human call. Everything on the correctness side is done and confirmed.


中文摘要:修复正确且已独立验证(rebase 到最新 master 后 typecheck/全量测试/构建全绿,CI 全绿)——把 x-grok-session-id(含 x-grok-conv-id 兜底)加入身份白名单,让 grok-shell 按会话 UUID 绑定、不再每轮 fork;改动最小、优先级与上游线形均无副作用,仅剩「更新分支到最新 master」一步,合并由人工决定。

@ranxianglei

Copy link
Copy Markdown
Owner

Reviewed — LGTM. Filed the companion issue #1042 (repo rule: fixes reference an issue; please add Fixes #1042 to the PR body).

Code review:

  • Whitelist placement is exactly right: x-grok-session-id / x-grok-conv-id sit at the client-specific trust tier (with x-claude-code-session-id), above the generic x-session-affinity/x-session-id names and below x-bili-plugin-conversation, which keeps its plugin-marker gate. No other agent sends a grok-namespaced header, so no collision/displacement risk; no new trust class is introduced.
  • Tests are deterministic (ephemeral listen(0) ports, real server rig) and pin the three behaviors that matter: verbatim binding, concurrent ids → distinct sessions, conv-id fallback.

Verification on the rebased head (rebased onto current master 26417a9, post-v0.1.128): typecheck clean, full suite 2063 pass / 0 fail (the 3 failures you saw — claude-native installer ×2, isMitmHost ×1 — do not reproduce in this environment), build clean. mergeable is True against master, so the PR can merge as-is even while marked "behind".

One ask per repo convention: every fix carries a CHANGELOG entry (see CHANGELOG.md head). Suggested text, feel free to paste/adapt:

  • Bind grok-shell sessions via x-grok-session-id (grok-shell sessions fork every turn: x-grok-session-id not in the identity header whitelist #1042): grok-shell (xAI's CLI) stamps a per-session UUID on every model request as x-grok-session-id (parallel x-grok-conv-id carries the same value). Neither name was in the identity whitelist, so every grok request fell through to anonymous prefix-affinity — and grok-shell reorders its replayed history head between turns (message order/composition changes, not pure append), breaking the byte-exact hash chain and minting a fresh session per request: compression state never accumulated (every session 0 blocks, nudges re-evaluated from scratch forever). Both headers join the whitelist at the client-specific trust tier (with x-claude-code-session-id — a name no other agent sends, so it can never displace a stronger signal; x-bili-plugin-conversation still outranks everything). Tests pin verbatim session binding, concurrent-id isolation, and the conv-id fallback.

@ranxianglei
ranxianglei merged commit 19970a5 into ranxianglei:master Sep 20, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants