fix(opencode-go): give sessionless requests an isolated session lane

devlog/_plan/260911_l1_responses_core/000_packet.md

@@ -0,0 +1,92 @@
+# Dispatch packet — L1 (revision 5)
+
+Round unit: `devlog/_plan/260911_lane_dispatch_round` on `dev`. Base freeze: `origin/dev` `6d3ad12e3` (2.51.0).
+Five audit rounds shaped this packet. The last one was a seven-lane feasibility check that asked whether each stack is implementable inside its owned paths; three lanes came back with gaps, and the fixes are folded here. `010_lane_partition.md` is the authoritative ownership list; `130_wp4_feasibility.md` records why each path was granted.
+
+
+## Shared frame
+
+**Repository.** Your worktree is named in your packet, already checked out on your lane branch, cut
+from `origin/dev` `6d3ad12e3` (2.51.0). Work only there. Do not add, move, or remove a worktree.
+
+**Loop.** Run `$codexclaw:cxc-loop` as HOTL for your lane: one work-phase per issue, in order. Your
+goal ends when your last PR is green and reported, not when the code looks right.
+
+**Subagents.** Unlimited `xai/grok-4.6` subagents, read-only, spawned with `spawn_agent`
+(`model: "xai/grok-4.6"`). Use them to reproduce, to read the call sites you are about to change, to
+find a second caller of a helper you are touching, and to review your staged diff adversarially
+before you push. A finding enters your work only with an exact `path:line` anchor. Subagents never
+write, commit, push, or call a mutating `gh`. Treat a `fail` verdict the way this round did: fold it
+in and re-audit. This packet is at revision 3 because two audit rounds rejected revisions 1 and 2.
+
+**MUST NOT.**
+
+- No local product suite: no `bun test`, no `bun run test`, no `bun run test:changed`, no
+  `bun run typecheck`, no `bun run build:gui`, no `bun install`. Report them as `NOT RUN`.
+- No merge, no release, no force-push to a shared branch, no direct push to `dev`.
+- No path outside your owned list, including paths a carried PR happens to touch. Dropping a hunk
+  from a carried PR is expected; report what you dropped.
+- No locale key in `gui/src/i18n/*`. If you need one, stop and report.
+- No security write-up in `devlog/`; scratch space only, per `AGENTS.md`.
+
+**MUST.**
+
+- Prefix every mutating git command with `git -c core.hooksPath=/dev/null`. This repository's hooks
+  can start a GUI install, typecheck, and build, which the no-local-suite rule forbids.
+- Push with `--no-verify`.
+- Write the focused regression test `AGENTS.md` requires for a behaviour change, in the domain
+  directory beside the existing tests for that subsystem, and register it in both
+  `scripts/test-layout/layout.json` `explicit` and `tests/fixtures/test-layout-expected.json`. You
+  will not run it; hosted CI will. Those two maps are append-only and other lanes are adding to them
+  too; the orchestrator resolves the conflicts at merge, so do not skip the entry.
+- Fill every section of `.github/PULL_REQUEST_TEMPLATE.md` and put `Closes #<issue>` in the body. In
+  **Verification**, state that the local suite, typecheck, and build were `NOT RUN` by operator
+  instruction and that hosted CI on the exact pushed head is the proof.
+- When you carry another author's PR, add a `Co-authored-by` trailer in a branch commit. Resolve the
+  address with `gh api users/<login> --jq '.id'` and use `<id>+<login>@users.noreply.github.com`.
+- Keep a devlog unit under `devlog/_plan/260911_l<N>_<slug>/`.
+
+**Stacking.** First PR targets `dev`; the second targets the first PR's head branch, the third the
+second. Retarget a child to `dev` after its parent lands. No native GitHub stacks.
+
+**Decisions already made for you.** Both audit rounds found items where the issue left a real choice
+open. Those calls are recorded in your packet in bold. Implement the recorded decision; if you think
+it is wrong, report the reason and stop.
+
+**Stop conditions.** Stop and report when the fix needs a path you do not own, when it needs a policy
+no issue has fixed, when a locale key is unavoidable, or when hosted CI fails for a reason outside
+your diff.
+
+**Report format.** Per PR: number, exact head SHA, CI run id and conclusion, the issue it closes, the
+co-authors credited, the hunks you dropped from a carried PR, and any decision you made. Say
+`NOT RUN` for local checks.
+
+**Decision boundary.** You do not merge, do not close another author's PR, and do not rank your lane
+against another. When your last PR is green, report and stop.
+
+## L1 — Responses pipeline and tool contract
+
+Worktree `~/.codex/worktrees/260911-l1/opencodex`, branch `codex/260911-l1-responses-core`.
+
+Owned: `src/server/responses/core.ts`, `src/server/responses/compact.ts`,
+`src/server/responses/policy-fallback.ts`, `src/server/chat-completions.ts`,
+`src/server/claude-messages.ts`, `src/server/request-log-conversation.ts`,
+`src/server/responses-undeclared-tool-guard.ts`, `src/providers/opencode-go-transport.ts`,
+`src/types/tools.ts`, and `docs-site/src/content/docs/reference/configuration/providers.md` (the page
+#4184 already edits). You do not own `codex-ws-exchange.ts` or `codex-ws-wire.ts` (L6) or
+`codex-auth-error.ts` (L3).
+
+1. **#4172 — OpenCode Go sessionless requests omit `x-opencode-session`.** Expected behaviour is
+   fixed by the issue: every request to the canonical Go destination carries the header; identity
+   keeps its stable per-conversation value; no identity gets an isolated per-request value rather
+   than none and rather than one shared global id; an explicit header still wins. Carry PR #4184 by
+   `chilung-cgu` (open, not a draft, `CHANGES_REQUESTED`); read the review first. Most urgent item in
+   the round: upstream ended the grace period on 09/06 and now errors without the header.
+2. **#4176 — a routed provider prefixes a bare Codex tool with `default.`.** **Decision: normalize
+   the invented prefix back at the undeclared-tool guard** — the #4181 shape, which is what the issue
+   states. #4181 by `chilung-cgu` is open, not a draft, `CHANGES_REQUESTED`; #4171 by `rrmlima` is an
+   open **draft** at `CHANGES_REQUESTED` and its unified-exec rewrite is out of round scope. Credit
+   `rrmlima` only if you reuse code from #4171.
+
+`core.ts` is contended by four open PRs. Keep the diff minimal; do not reformat around it.
+

docs-site/src/content/docs/reference/configuration/providers.md

@@ -949,6 +949,27 @@ receive the default only when the setting is absent; custom renamed entries keep
 value and do not acquire this default by destination matching. Chat model routes keep their
 existing protocol. The stateless flag does not force Responses streaming into JSON.
 
+## OpenCode Go session affinity
+
+Every request opencodex routes to an OpenCode Go destination carries an `x-opencode-session` header.
+The upstream began rejecting requests without it on 2026-09-06, so the header is not an optimization.
+
+The value depends on what the request already knows about itself:
+
+- An operator-configured `x-opencode-session` on the provider is preserved exactly as written.
+- A request that carries conversation identity — Codex thread headers, a Claude `metadata.user_id`,
+  a `session_id`, or an inbound `x-opencode-session` — is hashed into a stable per-conversation value,
+  so every turn of one conversation reaches Go under the same session.
+- A request with no identity at all, such as a model-availability probe or a first request before any
+  conversation metadata exists, receives a value allocated once for that request. It is isolated from
+  other requests rather than shared, and it survives the places opencodex rebuilds the request: the
+  translation to the internal Responses shape, compaction, combo children, and the policy-fallback
+  retry that hands the turn to the next candidate.
+
+Non-Go destinations are unaffected: opencodex never derives or adds the session header for them. A
+header an operator configured on such a provider is still sent, because opencodex leaves that
+configuration alone.
+
 ## OpenCode Go reasoning efforts
 
 Go catalog rows preserve their configured reasoning efforts exactly, including during

src/providers/opencode-go-transport.ts

@@ -22,7 +22,15 @@ export function deriveOpenCodeGoSessionId(sessionLane: string): string {
   return `ocx_${digest}`;
 }
 
-/** Add per-conversation Go affinity only to the canonical fixed-key destination. */
+/**
+ * Add Go affinity only to the canonical fixed-key destination.
+ *
+ * Callers on the request path resolve the lane with `getOrAllocateRequestSessionLane`, which returns
+ * real conversation identity when the client supplied it and a per-request value otherwise, so a
+ * request reaching this helper from the proxy always carries a lane. The `!sessionLane` guard stays
+ * for direct callers that have no request context; it is not a per-request identity of its own, and
+ * minting one here would hand each retry a different value.
+ */
 export function resolveOpenCodeGoTransport<T extends OcxProviderConfig>(
   provider: T,
   sessionLane: string | undefined,

src/server/chat-completions.ts

@@ -26,7 +26,10 @@ import { NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel }
 import { evidenceFromBody } from "../routing/request-evidence";
 import { resolveWireProtocolOverride } from "./adapter-resolve";
 import { resolveOpenCodeGoTransport } from "../providers/opencode-go-transport";
-import { normalizeLogConversationId, sessionLaneIdFromRequest } from "./request-log-conversation";
+import {
+  getOrAllocateRequestSessionLane,
+  linkRequestSessionLane,
+} from "./request-log-conversation";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import {
@@ -142,8 +145,7 @@ async function handleChatCompletionsWithBudget(
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
-    route.provider = resolveOpenCodeGoTransport(route.provider,
-      sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")));
+    route.provider = resolveOpenCodeGoTransport(route.provider, getOrAllocateRequestSessionLane(req));
     // Settle the wire once so every branch below reads the adapter this model will
     // actually use, not the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "chat");
@@ -305,6 +307,7 @@ async function handleChatCompletionsWithBudget(
     headers,
     body: internalBodyJson,
   });
+  linkRequestSessionLane(req, internalReq);
 
   let nativeLogged = false;
   const finalizeNativeLog = (status: number, meta: { terminalStatus?: RequestLogEntry["terminalStatus"]; closeReason: "terminal" | "client_cancel" | "non_stream" }) => {

src/server/claude-messages.ts

@@ -36,7 +36,12 @@ import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { addFinalRequestLog, httpStatusForRequestLogTerminal, recordFirstOutput, type RequestLogContext, type RequestLogEntry } from "./request-log";
-import { conversationIdFromClaudeMetadata, normalizeLogConversationId, sessionLaneIdFromRequest } from "./request-log-conversation";
+import {
+  conversationIdFromClaudeMetadata,
+  linkRequestSessionLane,
+  normalizeLogConversationId,
+  sessionLaneIdFromRequest,
+} from "./request-log-conversation";
 import { responseWithDeferredRequestLog } from "./relay";
 import { handleResponses } from "./responses";
 import {
@@ -897,6 +902,7 @@ async function handleClaudeMessagesWithBudget(
         headers,
         body: JSON.stringify(internalBody),
       });
+      linkRequestSessionLane(req, internalReq);
     } finally {
       reservation.release();
     }

src/server/request-log-conversation.ts

@@ -2,7 +2,7 @@
  * Best-effort chat/session correlation for Logs / usage.jsonl (#330).
  * Opaque ids only — never persist raw emails or Claude Desktop system-hash fallbacks.
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 /** Reject absurdly long client strings before hashing (DoS / JSONL bloat). */
 export const LOG_CONVERSATION_ID_INPUT_MAX = 4096;
@@ -217,3 +217,43 @@ export function summarizeConversationLogs(entries: readonly TotalsSource[]): Con
     unmeteredRequests,
   };
 }
+
+/**
+ * Request-scoped Go affinity for requests that carry no conversation identity.
+ *
+ * A sessionless request must still reach OpenCode Go with `x-opencode-session`, because the upstream
+ * began rejecting requests without it on 2026-09-06. It must not reuse one global value either, which
+ * would smear unrelated probes into a single conversation. So the lane is allocated once per admitted
+ * `Request` object and retained for that object's lifetime.
+ *
+ * The identity has to survive every place the proxy rebuilds a `Request`: translation to the internal
+ * Responses shape, compaction, and — the boundary that matters most — the policy fallback retry, where
+ * a second candidate would otherwise be handed a freshly minted lane after a retryable failure.
+ * `linkRequestSessionLane` carries the allocation across those boundaries.
+ */
+const requestAllocatedSessionLanes = new WeakMap<Request, string>();
+
+/**
+ * Resolve the session lane for a request: real conversation identity when the client supplied it,
+ * otherwise a per-request value allocated once and reused for retries on the same object.
+ */
+export function getOrAllocateRequestSessionLane(req: Request): string {
+  const explicit = sessionLaneIdFromRequest(req.headers)
+    ?? normalizeLogConversationId(req.headers.get("x-opencode-session"));
+  if (explicit) return explicit;
+
+  const existing = requestAllocatedSessionLanes.get(req);
+  if (existing) return existing;
+  const allocated = randomUUID();
+  requestAllocatedSessionLanes.set(req, allocated);
+  return allocated;
+}
+
+/**
+ * Carry a source request's lane onto a request the proxy built from it, so a rebuilt request keeps
+ * the conversation it belongs to instead of looking sessionless again.
+ */
+export function linkRequestSessionLane(sourceReq: Request, targetReq: Request): void {
+  requestAllocatedSessionLanes.set(targetReq, getOrAllocateRequestSessionLane(sourceReq));
+}
+

src/server/responses/compact.ts

@@ -157,7 +157,7 @@ import {
 } from "./core";
 import { fetchWithHeaderTimeout, providerFetch, safeHostLabel, safeOriginLabel } from "./fetch-helpers";
 import { mapCodexAuthContextErrorToResponse, nativeMainRefreshFailureResponse } from "./codex-auth-error";
-import { sessionLaneIdFromRequest } from "../request-log-conversation";
+import { linkRequestSessionLane, sessionLaneIdFromRequest } from "../request-log-conversation";
 import { recallComboForLane } from "./combo-session-recall";
 
 export const COMPACT_RESPONSE_MAX_BYTES = 32 * 1024 * 1024;
@@ -1149,6 +1149,7 @@ export async function handleResponsesCompact(
     headers: internalHeaders,
     body: JSON.stringify(internalBody),
   });
+  linkRequestSessionLane(req, internalReq);
   const response = await handleResponses(internalReq, config, logCtx, { abortSignal: req.signal, turnAdmissionLease, ...(admission ? { admission } : {}) });
   if (!response.ok) return response;
   let json: { output?: unknown[]; status?: unknown; error?: unknown };

src/server/responses/core.ts

@@ -320,6 +320,8 @@ import {
 } from "../request-log";
 import {
   conversationIdFromResponsesRequest,
+  getOrAllocateRequestSessionLane,
+  linkRequestSessionLane,
   normalizeLogConversationId,
   reasoningReplayConversationIdFromResponsesRequest,
   sessionLaneIdFromRequest,
@@ -2451,8 +2453,7 @@ async function applyFinalRouteRequestNormalization(args: {
 
   // Settle the wire once so logging, fast-mode, auth, and sidecars read the adapter
   // this request will actually use (#404).
-  route.provider = resolveOpenCodeGoTransport(route.provider,
-    sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")));
+  route.provider = resolveOpenCodeGoTransport(route.provider, getOrAllocateRequestSessionLane(req));
   route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
   if (preserveAnthropicResponseModel) parsed._responseModelId = responseModelId;
   logCtx.model = route.modelId;
@@ -2816,6 +2817,7 @@ export async function handleComboResponses(
       headers: childHeaders,
       body: JSON.stringify(childBody),
     });
+    linkRequestSessionLane(req, childRequest);
     let resolvedAuth: CodexAuthContext | undefined;
     let terminalRecorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined;
     const started = Date.now();

src/server/responses/policy-fallback.ts

@@ -2,6 +2,7 @@ import { comboFailureDecision } from "../../combos/failover";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "../request-decompress";
 import { finishRequestAttempt, type RequestLogContext } from "../request-log";
+import { linkRequestSessionLane } from "../request-log-conversation";
 import type { OcxConfig } from "../../types";
 import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
 import { handleResponses as handleResponsesCore } from "./core";
@@ -56,12 +57,17 @@ function requestWithCandidate(
   headers.delete("content-encoding");
   headers.delete("content-length");
   headers.set("content-type", "application/json");
-  return new Request(req.url, {
+  const retryRequest = new Request(req.url, {
     method: req.method,
     headers,
     body: JSON.stringify({ ...rawBody, model: `${candidate.provider}/${candidate.model}` }),
     signal: req.signal,
   });
+  // A sessionless request keeps the lane it was already allocated. Without this the second
+  // candidate reaches OpenCode Go under a different x-opencode-session than the first attempt,
+  // which is the same conversation split the header exists to prevent.
+  linkRequestSessionLane(req, retryRequest);
+  return retryRequest;
 }
 
 function errorCodeFromText(text: string): string | undefined {