mixdog 0.9.145 → 0.9.147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.145",
+  "version": "0.9.147",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -60,7 +60,7 @@
     "test:tool-contracts": "npm run build:spawn:test && node scripts/tool-smoke.mjs",
     "smoke:patch": "node scripts/apply-patch-edit-smoke.mjs",
     "test:shellhardening": "npm run build:spawn:test && node --test scripts/suite-shellhardening-test.mjs scripts/suite-shell-direct-exe-test.mjs",
-    "test:providers": "node --test scripts/provider-toolcall-test.mjs scripts/provider-contract-test.mjs scripts/provider-stream-outcome-test.mjs scripts/cursor-provider-test.mjs",
+    "test:providers": "node --test scripts/provider-toolcall-test.mjs scripts/provider-contract-test.mjs scripts/provider-stream-outcome-test.mjs scripts/cursor-provider-test.mjs src/runtime/agent/orchestrator/providers/openai-codex-identity.test.mjs src/runtime/agent/orchestrator/providers/openai-ws-delta-parity.test.mjs",
     "test:embedding-runtime:warmup": "node scripts/verify-embedding-runtime.mjs --warmup",
     "test:release-assets": "node --check scripts/verify-release-assets.mjs && node --check scripts/release-gate-test.mjs && node --check scripts/prepare-native-assets.mjs && node --test scripts/release-gate-test.mjs scripts/prepare-native-assets-test.mjs",
     "test:native-edit-wire": "node scripts/native-edit-wire-test.mjs",

package/src/lib/rules-builder.cjs

@@ -180,7 +180,9 @@ function buildProfilePreferencesContent(dataDir) {
     lines.push(`- Development experience: ${experience.label}. ${experience.prompt}`);
     lines.push('- Adapt vocabulary and assumed background to this level without adding lessons, examples, or tips unless the task needs them; output style still controls information depth.');
   }
-  return `# Profile Preferences${lines.length ? `\n\n${lines.join('\n')}` : ''}`;
+  // No configured preference means no section: a bare heading would ship an
+  // empty block to every model that has neither a title nor an experience level.
+  return lines.length ? `# Profile Preferences\n\n${lines.join('\n')}` : '';
 }
 
 function buildLanguageSection(dataDir) {
@@ -192,9 +194,16 @@ function buildLanguageSection(dataDir) {
     : '';
   const lines = [
     `- Default user-facing language${source}: ${language.prompt}. Use it for all user-facing text (preambles, progress, questions, reports, notices), overriding output style; switch only when the user does or asks.`,
-    `- Keep code identifiers, paths, commands, symbols, API names, and exact errors in original form.`,
-    `- Never coin a word-for-word translation of source jargon; use the established original term or a plain functional description.`,
   ];
+  // Translation guards only bind when the output language differs from the
+  // language of code, docs, and errors. English output has nothing to
+  // mistranslate, so the two clauses would be dead text.
+  if (language.prompt !== 'English') {
+    lines.push(
+      `- Keep code identifiers, paths, commands, symbols, API names, and exact errors in original form.`,
+      `- Never coin a word-for-word translation of source jargon; use the established original term or a plain functional description.`,
+    );
+  }
   return `# Language\n\n${lines.join('\n')}`;
 }
 

package/src/output-styles/common.md

@@ -10,20 +10,18 @@ partial: true
 - Lead with the answer or action, then the context needed to understand it and
   lower-priority detail. Use complete sentences and a register suited to the
   reader.
-- Select content by the active depth variation before formatting it; omitted
-  content stays omitted.
 - Choose the shape from the content and the reader. Prose, lists, headings,
   tables, and code may combine, and no response shape is a default. Output uses
   GitHub-flavored Markdown with `$$…$$` math in a proportional-width surface;
   use tables or fenced blocks instead of spacing. Use tables only for short
   enumerable or quantitative facts, with explanation outside the cells.
-- Keep simple answers visually simple. Never produce an essay-shaped wall of
-  text or overcorrect into fragments, decorative emphasis, tiny headings,
-  needless nesting, or a recurring template.
+- Keep simple answers visually simple; never sprawl into an essay or
+  overcorrect into fragments, decorative structure, or a recurring template.
 - Give each paragraph or list item one idea and keep the flow linear.
 - Keep established facts separate from plausible inference. Never invent
   certainty, preserve exact technical literals, and show references only where
-  useful.
-- State each material point once and stop when the request is covered. Do not
-  restate the request, close with a recap, or append unrequested recommendations
-  or offers; avoid emojis, raw output dumps, and process narration unless asked.
+  useful — code as `file:line`, issues as `owner/repo#123`, URLs bare so they
+  stay clickable.
+- State each point once and stop when the request is covered: no restatement,
+  unrequested advice or offers, emojis, raw dumps, or process narration as the
+  answer.

package/src/output-styles/simple.md

@@ -12,4 +12,4 @@ Simple — concise summary.
 - Retain: the answer, core causal sequence, strongest evidence, direct
   consequences, and material scope or caveat. Keep it self-contained.
 - Omit: secondary evidence, implementation detail, examples, edge cases,
-  adjacent implications, alternatives, and unrequested remediation.
+  adjacent implications, and unrequested remediation.

package/src/rules/shared/10-tool-workflow.md

@@ -1,43 +1,33 @@
 # Tool Workflow
 
+- Determine the required outcome and its gaps — requirements are not evidence —
+  gather only what is missing, act, then verify the affected facets.
 - Investigate, build, and verify only what the requested outcome requires, at
-  the level it requires; trust internal and framework guarantees.
+  the level it requires; internal and framework guarantees are trusted.
 - Minimize tool turns through maximal useful parallelism. Cost is counted in
   rounds, not calls: a batch is one round, so a call-count saving never
-  justifies a worse-routed call. Plan the fewest evidence-complete dependent
-  rounds first, then the fewest calls within each round.
+  justifies a worse-routed call.
 - In each round, issue every necessary non-overlapping call whose inputs are
   already known; defer a call only when its target or arguments require an
-  earlier result.
-- Route each remaining evidence facet once to its primary owner, preferring the
-  operation that directly returns the evidence needed for the next decision. A
-  summary, overview, or enumeration is not a prerequisite when that operation's
-  complete inputs are already known; if independently required, batch it with
-  the detailed operation.
-- Never duplicate a facet, widen retrieval speculatively, or arbitrarily omit
-  required fanout. Respect tool/schema limits; split only when necessary, and
+  earlier result. Respect tool/schema limits, never omit required fanout, and
   apply one analysis to many targets as one parameterized call when supported.
-1. Determine the required outcome and missing information; requirements are
-   not evidence.
-2. If needed, gather only missing information through Research or Exploration;
-   use Execution when the information can only be produced by running a program
-   or observing runtime state.
-3. Perform the required answer, edit, or execution in the fewest safe coherent
-   calls.
-4. Verify only affected facets and essential invariants when required.
+- Route each evidence facet once to its primary owner, preferring the operation
+  that directly returns the evidence needed for the next decision. A summary,
+  overview, or enumeration is not a prerequisite when that operation's complete
+  inputs are already known; if independently required, batch it with the
+  detailed operation.
 - Known state — system guarantees, supplied facts, visible tool returns,
   applied patches, and passed checks — is never re-found, re-derived, or
   re-verified at any granularity: no re-query call, no confirmation subcommand
   inside a shell command, no availability probe for what the operation itself
   would report, no reopening a file to confirm an edit, no rerun of a passed
   check.
-- Mine each returned result fully before opening the next round. A follow-up
-  is valid only for evidence a result omitted, invalidated, or newly made
-  necessary; an independently required call that no result created belonged in
-  the earlier batch.
+- Mine each returned result fully before opening the next round; a follow-up is
+  valid only for evidence a result omitted, invalidated, or newly made
+  necessary.
 - Evidence that determines the answer, edit, or deliverable ends retrieval.
-- Treat failure as new evidence and repeat steps 1–4 only for affected facets.
-  Report a blocker when no deterministic next action remains.
-- Use only named tools present in the current tool surface.
-- Deferred tools auto-load on a direct call; when their exact arguments are
-  not visible, call `load_tool` first and read the surfaced schema.
+- Treat failure as new evidence and re-enter that loop only for the affected
+  facets. Report a blocker when no deterministic next action remains.
+- Use only named tools present in the current tool surface; deferred tools
+  auto-load on a direct call, and when their exact arguments are not visible,
+  call `load_tool` first and read the surfaced schema.

package/src/rules/shared/40-editing.md

@@ -1,16 +1,28 @@
 # Editing
 
+<!-- tools: apply_patch -->
 - A required new file is created directly: Add File is itself the atomic
   absence check, so inspect only if it reports the target already exists.
+<!-- tools: edit -->
+- A required new file is created directly: an empty `old_string` is itself the
+  atomic absence check, so inspect only if it reports the target already exists.
 - Source: use exact current target text from any visible evidence, including
   user input, tool output, or an applied edit result; never reconstruct it from
   another file, a sample, or expectation.
-- Placement: with `edit`, use an exact unique target string, expanding exact
-  surrounding text when needed; with `apply_patch`, use exact unchanged context
-  and add a class/function locator when context alone is not unique.
+<!-- tools: edit -->
+- Placement: use an exact unique target string, expanding exact surrounding
+  text when needed.
+<!-- tools: apply_patch -->
+- Placement: use exact unchanged context and add a class/function locator when
+  context alone is not unique.
 - Apply all determined changes in the fewest safe calls the active tool
   supports; a file written in one call is written complete.
-- Batch scope: never split one file across concurrent edit calls. Group
-  same-intent changes with exact context into coherent calls; issue disjoint
-  calls together in one turn, and defer ambiguous or result-dependent changes.
+<!-- tools: apply_patch -->
+- One file, several changes: one Update File block carries every hunk.
+<!-- tools: edit -->
+- One file, several changes: issue the calls together in one turn — they apply
+  in call order — while no target overlaps another and none depends on text an
+  earlier call creates. Widening one target across the gap is equivalent only
+  while every spanned line stays verbatim.
+- Defer only ambiguous or result-dependent changes.
 

package/src/rules/shared/60-verification.md

@@ -4,7 +4,6 @@
 - Run only checks that directly cover the changed behavior or essential
   invariants; use an umbrella suite only when the user explicitly requests it
   or a documented project or release process requires it.
-- Issue all independent checks in one turn.
 - Blocking checks cover only essential integrity, security, compatibility, and
   buildability invariants. Treat mutable behavior, UX, exact text, snapshots,
   and implementation shape as advisory specifications; update them when the

package/src/rules/shared/70-delivery.md

@@ -2,4 +2,7 @@
 
 - Commit, push, release, and deployment happen only on the user's explicit
   request.
-- Every Git operation→`git`; source-file edits stay with `edit`/`apply_patch`.
+<!-- tools: edit -->
+- Every Git operation→`git`; source-file edits stay with `edit`.
+<!-- tools: apply_patch -->
+- Every Git operation→`git`; source-file edits stay with `apply_patch`.

package/src/runtime/agent/orchestrator/agent-runtime/cache-strategy.mjs

@@ -266,7 +266,10 @@ function codexThreadPromptCacheKey(opts, namespace) {
     if (process.env.MIXDOG_OAI_CACHE_KEY_SHARED === '1') {
         return fitPromptCacheKey(explicit || namespace, 'mixdog-codex');
     }
-    const sessionKey = cleanString(opts?.sessionId || opts?.session?.id);
+    const codexIdentity = cleanString(opts?.codexSessionId)
+        || cleanString(opts?.codexThreadId)
+        || cleanString(opts?.session?.codexWireSessionId);
+    const sessionKey = codexIdentity || cleanString(opts?.sessionId || opts?.session?.id);
     return fitPromptCacheKey(sessionKey || explicit || namespace, namespace);
 }
 

package/src/runtime/agent/orchestrator/providers/codex-client-meta.mjs

@@ -88,18 +88,25 @@ function _arch() {
 }
 
 /**
- * Originator token codex sends on every request (`codex_cli_rs`).
+ * Originator token codex sends on every request.
  *
  * Opt-in parity override: an operator can pin the exact originator a known-good
  * codex build reports via MIXDOG_CODEX_ORIGINATOR when the backend fingerprints
- * on it. Unset (default) keeps `codex_cli_rs`, so wire behavior is unchanged.
+ * on it. Default is the interactive CLI's `codex_cli_rs`, which is also what
+ * the User-Agent is built from.
  */
 export function codexOriginator() {
     const override = String(process.env.MIXDOG_CODEX_ORIGINATOR || '').trim();
     return override || 'codex_cli_rs';
 }
 
-/** codex_cli_rs/<version> (<os> <ver>; <arch>) <terminal> */
+/**
+ * <originator>/<version> (<os> <ver>; <arch>) <terminal>
+ *
+ * The reference client derives its User-Agent FROM the originator, so the two
+ * can never disagree: pinning the exec originator while advertising the
+ * interactive CLI agent would produce a pair no real client build sends.
+ */
 export function codexUserAgent() {
     // Opt-in parity override: pin an exact codex User-Agent string
     // (MIXDOG_CODEX_USER_AGENT) when the auto-derived os/arch/terminal tuple
@@ -107,7 +114,7 @@ export function codexUserAgent() {
     const override = String(process.env.MIXDOG_CODEX_USER_AGENT || '').trim();
     if (override) return override;
     const terminal = String(process.env.TERM_PROGRAM || 'unknown').trim() || 'unknown';
-    return `codex_cli_rs/${codexClientVersionSync()} (${_osType()} ${os.release()}; ${_arch()}) ${terminal}`;
+    return `${codexOriginator()}/${codexClientVersionSync()} (${_osType()} ${os.release()}; ${_arch()}) ${terminal}`;
 }
 
 /** Bare version header value — codex built-in provider http_headers "version". */

package/src/runtime/agent/orchestrator/providers/openai-codex-identity.test.mjs

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+    codexWireSendOpts,
+    ensureCodexWireSessionId,
+    isUuidV7,
+    mintUuidV7,
+} from '../session/manager/session-id.mjs';
+import { buildStableProviderPromptCacheKey } from '../agent-runtime/cache-strategy.mjs';
+import { _withCodexWsClientMetadata } from './openai-codex-metadata.mjs';
+import { codexOriginator, codexUserAgent } from './codex-client-meta.mjs';
+
+test('Codex wire identity is a real time-based UUIDv7 and remains session-stable', () => {
+    const now = Date.now();
+    const first = mintUuidV7(now);
+    const second = mintUuidV7(now);
+    assert.equal(isUuidV7(first), true);
+    assert.equal(isUuidV7(second), true);
+    assert.notEqual(first, second);
+    assert.equal(Number.parseInt(first.replace(/-/g, '').slice(0, 12), 16), now);
+
+    const session = { provider: 'openai-oauth' };
+    const sessionId = ensureCodexWireSessionId(session);
+    assert.equal(isUuidV7(sessionId), true);
+    assert.equal(ensureCodexWireSessionId(session), sessionId);
+});
+
+test('Codex cache key and every wire session identity use the same UUIDv7', (t) => {
+    const previousParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY;
+    process.env.MIXDOG_OAI_CODEX_WIRE_PARITY = '1';
+    t.after(() => {
+        if (previousParity == null) delete process.env.MIXDOG_OAI_CODEX_WIRE_PARITY;
+        else process.env.MIXDOG_OAI_CODEX_WIRE_PARITY = previousParity;
+    });
+
+    const sessionId = mintUuidV7();
+    const turnStartedAtUnixMs = Date.now();
+    const turnId = mintUuidV7(turnStartedAtUnixMs);
+    const session = {
+        provider: 'openai-oauth',
+        id: 'exec_internal_id',
+        codexWireSessionId: sessionId,
+        promptCacheKey: 'mixdog-codex',
+    };
+    const promptCacheKey = buildStableProviderPromptCacheKey('openai-oauth', {
+        sessionId: session.id,
+        codexSessionId: sessionId,
+        codexThreadId: sessionId,
+        session,
+    });
+    assert.equal(promptCacheKey, sessionId);
+    // The reference client derives its User-Agent from the originator, so the
+    // pair can never disagree on the wire.
+    assert.equal(codexUserAgent().startsWith(`${codexOriginator()}/`), true);
+
+    const frame = _withCodexWsClientMetadata(
+        { prompt_cache_key: promptCacheKey },
+        {},
+        true,
+        {
+            cacheKey: promptCacheKey,
+            poolKey: session.id,
+            sendOpts: {
+                codexSessionId: sessionId,
+                codexThreadId: sessionId,
+                turnId,
+                windowId: `${sessionId}:0`,
+                turnStartedAtUnixMs,
+                session,
+            },
+        },
+    );
+    assert.equal(frame.prompt_cache_key, sessionId);
+    assert.equal(frame.client_metadata.session_id, sessionId);
+    assert.equal(frame.client_metadata.thread_id, sessionId);
+    assert.equal(frame.client_metadata.turn_id, turnId);
+    assert.equal(frame.client_metadata['x-codex-window-id'], `${sessionId}:0`);
+    const turnMetadata = JSON.parse(frame.client_metadata['x-codex-turn-metadata']);
+    assert.equal(turnMetadata.session_id, sessionId);
+    assert.equal(turnMetadata.thread_id, sessionId);
+    assert.equal(turnMetadata.turn_id, turnId);
+    assert.equal(turnMetadata.agent_name, '/root');
+    assert.equal(turnMetadata.sandbox, 'none');
+    assert.equal(turnMetadata.sandbox_mode, 'danger-full-access');
+    assert.equal(turnMetadata.auto_review_enabled, false);
+    assert.equal(turnMetadata.turn_started_at_unix_ms, turnStartedAtUnixMs);
+});
+
+// A compaction summary is a request of the same session: same thread identity,
+// same window, same prompt-cache slot — only the request kind and turn id move.
+test('compaction shares the session identity and cache slot with its turns', () => {
+    const session = { provider: 'openai-oauth', id: 'sess_internal_1' };
+    const turn = codexWireSendOpts(session, {
+        turnId: mintUuidV7(),
+        startedAtMs: Date.now(),
+    });
+    const compaction = codexWireSendOpts(session, { requestKind: 'compaction' });
+
+    assert.equal(compaction.codexSessionId, turn.codexSessionId);
+    assert.equal(compaction.codexThreadId, turn.codexThreadId);
+    assert.equal(compaction.windowId, turn.windowId);
+    assert.equal(turn.requestKind, 'turn');
+    assert.equal(compaction.requestKind, 'compaction');
+    assert.notEqual(compaction.turnId, turn.turnId);
+    assert.equal(isUuidV7(compaction.turnId), true);
+
+    // The compaction call runs on its own socket bucket (`:compact` session id)
+    // yet must still resolve to the turn's prompt-cache key.
+    assert.equal(
+        buildStableProviderPromptCacheKey('openai-oauth', {
+            sessionId: `${session.id}:compact`,
+            session,
+            ...compaction,
+        }),
+        buildStableProviderPromptCacheKey('openai-oauth', {
+            sessionId: session.id,
+            session,
+            ...turn,
+        }),
+    );
+
+    const frame = _withCodexWsClientMetadata({}, {}, true, {
+        cacheKey: compaction.codexSessionId,
+        poolKey: `${session.id}:compact`,
+        sendOpts: { ...compaction, session },
+    });
+    const turnMetadata = JSON.parse(frame.client_metadata['x-codex-turn-metadata']);
+    assert.equal(turnMetadata.request_kind, 'compaction');
+    assert.equal(turnMetadata.session_id, turn.codexSessionId);
+    assert.equal(turnMetadata.thread_id, turn.codexThreadId);
+});

package/src/runtime/agent/orchestrator/providers/openai-codex-metadata.mjs

@@ -8,12 +8,30 @@ function _cleanMetaString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
 
+function _codexUuidV7(value) {
+    const clean = String(value || '').trim().toLowerCase();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(clean)) {
+        return clean;
+    }
+    const digest = createHash('sha256').update(clean).digest();
+    const bytes = Buffer.from(digest.subarray(0, 16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 export function _hashText(value, chars = 24) {
     return createHash('sha256').update(String(value || '')).digest('hex').slice(0, chars);
 }
 
 // Session ids embed their creation stamp; fall back to now for foreign shapes.
 function _sessionStartedAtUnixMs(sessionId) {
+    const compactUuid = String(sessionId || '').trim().replace(/-/g, '');
+    if (/^[0-9a-f]{12}7[0-9a-f]{19}$/i.test(compactUuid)) {
+        const timestamp = Number.parseInt(compactUuid.slice(0, 12), 16);
+        if (Number.isFinite(timestamp) && timestamp > 0) return timestamp;
+    }
     const parts = String(sessionId || '').split('_');
     for (const part of parts) {
         if (/^\d{12,}$/.test(part)) {
@@ -39,25 +57,49 @@ function _codexInstallationId(sendOpts) {
 // socket, or a later turn would
 // replay the first turn's identity.
 function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = false } = {}) {
-    const sessionId = _cleanMetaString(sendOpts?.codexSessionId || sendOpts?.session?.codexSessionId || poolKey || cacheKey)
+    const rawSessionId = _cleanMetaString(
+        sendOpts?.codexSessionId
+        || sendOpts?.session?.codexWireSessionId
+        || sendOpts?.session?.codexSessionId
+        || poolKey
+        || cacheKey,
+    )
         || 'mixdog-session';
-    const threadId = _cleanMetaString(sendOpts?.threadId || sendOpts?.codexThreadId || sendOpts?.session?.threadId || cacheKey || sessionId)
-        || sessionId;
-    const installationId = _codexInstallationId(sendOpts);
+    const rawThreadId = _cleanMetaString(
+        sendOpts?.threadId
+        || sendOpts?.codexThreadId
+        || sendOpts?.session?.codexWireSessionId
+        || sendOpts?.session?.threadId
+        || cacheKey
+        || rawSessionId,
+    )
+        || rawSessionId;
+    const rawInstallationId = _codexInstallationId(sendOpts);
+    const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
+    const sessionId = wireParity ? _codexUuidV7(rawSessionId) : rawSessionId;
+    const threadId = wireParity ? _codexUuidV7(rawThreadId) : rawThreadId;
+    const installationId = wireParity ? _codexUuidV7(rawInstallationId) : rawInstallationId;
     const startedAt = Number.isFinite(Number(sendOpts?.turnStartedAtUnixMs))
         ? Math.floor(Number(sendOpts.turnStartedAtUnixMs))
-        : _sessionStartedAtUnixMs(sessionId);
-    const requestKind = _codexRequestKind(sendOpts, sessionId);
-    const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
+        : _sessionStartedAtUnixMs(rawSessionId);
+    const requestKind = _codexRequestKind(sendOpts, rawSessionId);
     // The reference client opens the WS with a prewarm (empty turn_id) BEFORE
     // the real turn. Under wire parity the handshake IS that prewarm, so its
     // turn_id empties and its request_kind becomes 'prewarm' instead of
     // presenting the handshake as a live turn. Parity off is unchanged.
     const isPrewarm = requestKind === 'prewarm' || handshake === true;
-    const explicitTurnId = _cleanMetaString(sendOpts?.turnId || sendOpts?.codexTurnId || sendOpts?.session?.turnId);
+    const rawExplicitTurnId = _cleanMetaString(sendOpts?.turnId || sendOpts?.codexTurnId || sendOpts?.session?.turnId);
     const explicitWindowId = _cleanMetaString(sendOpts?.windowId || sendOpts?.codexWindowId || sendOpts?.session?.windowId);
-    const turnId = wireParity && isPrewarm ? '' : (explicitTurnId || sessionId);
+    const turnId = wireParity && isPrewarm
+        ? ''
+        : wireParity
+            ? _codexUuidV7(rawExplicitTurnId || `${rawSessionId}:turn`)
+            : (rawExplicitTurnId || sessionId);
     const effectiveRequestKind = wireParity && isPrewarm ? 'prewarm' : requestKind;
+    // Window id is `<thread-id>:<auto-compact window number>`, and that counter
+    // starts at 0: a thread that never auto-compacted reports generation 0 and
+    // only advances when a new context window opens. The legacy non-parity
+    // wire kept :1 and is left alone so measured default behavior is unchanged.
     const windowId = explicitWindowId || `${threadId}:${wireParity ? 0 : 1}`;
     const turnMetadata = {
         installation_id: installationId,
@@ -66,13 +108,17 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = fa
         turn_id: turnId,
         window_id: windowId,
         request_kind: effectiveRequestKind,
-        // Richer turn-metadata. A/B
-        // 2026-07-04 showed no effect, so it stays behind a knob for future
-        // probes; wire parity implies it.
-        ...((process.env.MIXDOG_OAI_TURN_METADATA_RICH === '1' || wireParity) ? {
-            thread_source: 'user',
-            sandbox: 'read-only',
-        } : {}),
+        // Turn-metadata fields the reference client fills on every request.
+        // They were behind a probe knob after a 2026-07-04 A/B showed no
+        // isolated effect; they are unconditional now because a partial blob is
+        // a shape no real client sends. Absolute agent path, not a bare name;
+        // the sandbox pair reports this runtime honestly (tools run with full
+        // host access, so there is no sandbox to declare).
+        agent_name: '/root',
+        thread_source: 'user',
+        sandbox: 'none',
+        sandbox_mode: 'danger-full-access',
+        auto_review_enabled: false,
         turn_started_at_unix_ms: startedAt,
     };
     return {
@@ -98,36 +144,32 @@ export function _metadataTrace(metadata) {
     };
 }
 
-// Handshake projection of the same identity. These ride on every
-// request; A/B 2026-07-04
-// showed the turn-metadata blob alone lifts prefix-cache hits, so it is ON by
-// default. MIXDOG_OAI_TURN_METADATA overrides:
-//   unset|1|turn-metadata : window-id + turn-metadata + installation-id
-//   parent                : + x-codex-parent-thread-id
-//   window                : window-id only (drop the blob)
-//   0|off|false|no        : pre-2026-07-04 baseline (drop the blob)
+// Handshake projection of the same identity: window id, the turn-metadata
+// blob, the installation id, and the routing hint. The reference client sends
+// all of them on every request, and a 2026-07-04 A/B measured the blob alone
+// lifting prefix-cache hits.
 export function _codexWsCompatibilityHeaders(context = {}) {
     const metadata = _codexMetadataBase(null, context);
     const headers = {};
     if (metadata['x-codex-window-id']) headers['x-codex-window-id'] = metadata['x-codex-window-id'];
     if (metadata['x-codex-turn-metadata']) headers['x-codex-turn-metadata'] = metadata['x-codex-turn-metadata'];
     if (metadata['x-codex-installation-id']) headers['x-codex-installation-id'] = metadata['x-codex-installation-id'];
-    const parentThreadId = () => _cleanMetaString(context?.sendOpts?.parentThreadId
-        || context?.sendOpts?.codexParentThreadId
-        || metadata.thread_id);
-    const probe = String(process.env.MIXDOG_OAI_TURN_METADATA || '').trim().toLowerCase();
-    if (probe === '0' || probe === 'off' || probe === 'false' || probe === 'no' || probe === 'window') {
-        delete headers['x-codex-turn-metadata'];
-    } else if (probe === 'parent') {
-        const parent = parentThreadId();
-        if (parent) headers['x-codex-parent-thread-id'] = parent;
-    }
-    // Turn-state gate probe: attach the parent header independent of the knob
-    // above (hypothesis: x-codex-turn-state issuance wants it). Default OFF.
-    const gate = String(process.env.MIXDOG_OAI_CODEX_TURN_STATE_GATE || '').trim().toLowerCase();
-    if (['1', 'true', 'yes', 'on'].includes(gate) && !headers['x-codex-parent-thread-id']) {
-        const parent = parentThreadId();
-        if (parent) headers['x-codex-parent-thread-id'] = parent;
+    // Routing hint. The reference client attaches this to EVERY request whose
+    // auth is the ChatGPT backend — no flag, no mode, and with `model=` alone
+    // when no service tier is selected. It is how the backend lands the request
+    // on a node that already holds this model's prefix, so leaving it off makes
+    // node selection arbitrary and the first call of a session pays a cold
+    // prefix. Measured 2026-08-22: without the hint, 3 of 8 parallel sessions
+    // started with 0 cached tokens and 6 warm calls missed; the run that
+    // happened to carry a priority tier (its own routing signal) missed none.
+    const model = _cleanMetaString(context?.model || context?.sendOpts?.model);
+    if (model) {
+        const serviceTier = _cleanMetaString(context?.serviceTier
+            || context?.sendOpts?.serviceTier
+            || context?.sendOpts?.service_tier);
+        headers['x-codex-routing-hint'] = serviceTier
+            ? `model=${model};tier=${serviceTier}`
+            : `model=${model}`;
     }
     return headers;
 }