@bitkyc08/opencodex 2.91.0 → 2.92.0

package/src/server/responses-phase-inference.ts

@@ -0,0 +1,267 @@
+import type { OcxMessagePhase } from "../types";
+import { Buffer } from "node:buffer";
+import type { TranslatorBudget } from "../lib/translator-budget";
+import type { SseBlockRewrite } from "./sse-payload-rewrite";
+import { replaceSseDataPayload, sseDataPayload } from "./sse-payload-rewrite";
+
+/**
+ * Opt-in per-provider phase inference for Responses passthrough streams.
+ *
+ * OpenAI models annotate assistant messages with a commentary/final_answer
+ * phase; the Codex desktop UI collapses commentary into progress rows and
+ * only fully renders the final answer. Third-party gateways forward plain
+ * Responses items without that field, so every narration chunk renders
+ * expanded. The wire has no phase field, so phase is inferred from what
+ * follows each completed message, mirroring the openai-chat bridge strategy:
+ * a message followed by tool-call work is commentary; a message at turn end
+ * is the final answer. Messages already carrying commentary or final_answer
+ * are left untouched and forwarded without buffering; a null or unknown phase
+ * is inferred like a missing one. Each rewritten message stays
+ * buffered until the next protocol event (SSE keepalives keep it pending).
+ * Live text deltas are not buffered, but message completion waits for that
+ * event. Snapshots reuse each item decision when their phase is absent,
+ * matched by item id or, when either side lacks an id, by output index;
+ * explicit snapshot phases take precedence, and failed snapshots are untouched.
+ */
+
+const TERMINAL_EVENT_TYPES = new Set([
+  "response.completed",
+  "response.incomplete",
+  "response.failed",
+]);
+const TOOL_CALL_ITEM_TYPES = new Set([
+  "function_call",
+  "custom_tool_call",
+  "local_shell_call",
+  "shell_call",
+  "apply_patch_call",
+  "mcp_call",
+  "tool_search_call",
+  "web_search_call",
+]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Only these two values are decisions; null or unknown phases count as missing. */
+function isMessagePhase(value: unknown): value is OcxMessagePhase {
+  return value === "commentary" || value === "final_answer";
+}
+
+function isToolCallItem(item: unknown): boolean {
+  if (!isPlainObject(item)) return false;
+  const type = item.type;
+  return typeof type === "string"
+    && (TOOL_CALL_ITEM_TYPES.has(type)
+      // Unknown hosted/extension call shapes still prove the turn continued.
+      || (type.endsWith("_call") && !type.endsWith("_call_output")));
+}
+
+function parseDataPayload(block: string): Record<string, unknown> | null {
+  const payload = sseDataPayload(block);
+  if (payload === null) return null;
+  try {
+    const parsed = JSON.parse(payload) as unknown;
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isDoneSentinel(block: string): boolean {
+  return sseDataPayload(block)?.trim() === "[DONE]";
+}
+
+function isMessageDoneBlock(block: string): boolean {
+  const parsed = parseDataPayload(block);
+  return parsed?.type === "response.output_item.done"
+    && isPlainObject(parsed.item) && parsed.item.type === "message";
+}
+
+function withMessagePhase(block: string, phase: OcxMessagePhase): string {
+  const parsed = parseDataPayload(block);
+  if (!parsed || parsed.type !== "response.output_item.done") return block;
+  if (!isPlainObject(parsed.item) || isMessagePhase(parsed.item.phase)) return block;
+  const patched = { ...parsed, item: { ...parsed.item, phase } };
+  return replaceSseDataPayload(block, JSON.stringify(patched));
+}
+
+/** One per-item decision, findable by item id and by output index. */
+interface PhaseDecision {
+  readonly id: string | null;
+  readonly index: number | null;
+  readonly phase: OcxMessagePhase;
+}
+
+interface PhaseDecisions {
+  readonly byId: ReadonlyMap<string, PhaseDecision>;
+  readonly byIndex: ReadonlyMap<number, PhaseDecision>;
+}
+
+function outputIndexOf(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+/**
+ * The phase already emitted on the wire for the snapshot item at `position`.
+ * An id match wins. A position match is used only when the event or the
+ * snapshot item lacks an id, so two different ids never share a decision.
+ */
+function decidedPhase(decisions: PhaseDecisions, id: string | null, position: number): OcxMessagePhase | undefined {
+  const byId = id !== null ? decisions.byId.get(id) : undefined;
+  if (byId) return byId.phase;
+  const byIndex = decisions.byIndex.get(position);
+  return byIndex && (byIndex.id === null || id === null) ? byIndex.phase : undefined;
+}
+
+function withSnapshotPhases(block: string, decisions: PhaseDecisions): string {
+  const parsed = parseDataPayload(block);
+  if (!parsed) return block;
+  const response = parsed.response;
+  if (!isPlainObject(response) || !Array.isArray(response.output)) return block;
+  let changed = false;
+  const output = response.output.map((item: unknown, position: number) => {
+    if (isPlainObject(item) && item.type === "message" && !isMessagePhase(item.phase)) {
+      // Mirror the decision already emitted for this item on the wire, so
+      // clients reconciling the final snapshot never re-expand a message
+      // whose output_item.done said commentary. Items the rewrite never saw
+      // (joined mid-stream, no buffered decision) fall back to final_answer.
+      const id = typeof item.id === "string" ? item.id : null;
+      const phase = decidedPhase(decisions, id, position) ?? "final_answer";
+      changed = true;
+      return { ...item, phase };
+    }
+    return item;
+  });
+  if (!changed) return block;
+  const patched = { ...parsed, response: { ...response, output } };
+  return replaceSseDataPayload(block, JSON.stringify(patched));
+}
+
+export function createResponsesPhaseInferenceBlockRewrite(budget: TranslatorBudget): SseBlockRewrite {
+  // At most one message-done block is held at a time; the next block decides
+  // its phase and is then processed itself. Malformed blocks pass through
+  // without consuming the pending decision. Per-item decisions fill missing
+  // snapshot phases. Both pending blocks and decisions share the request
+  // retention budget and are released at a terminal event or teardown.
+  let pending: string | null = null;
+  let pendingBytes = 0;
+  let decisionBytes = 0;
+  const byId = new Map<string, PhaseDecision>();
+  const byIndex = new Map<number, PhaseDecision>();
+  const decisions: PhaseDecisions = { byId, byIndex };
+  const scope = { kind: "retained_collectors" as const };
+
+  const clearState = (): void => {
+    budget.releaseRetained(pendingBytes + decisionBytes, scope);
+    pending = null;
+    pendingBytes = 0;
+    decisionBytes = 0;
+    byId.clear();
+    byIndex.clear();
+  };
+
+  const decisionSize = (decision: PhaseDecision): number =>
+    Buffer.byteLength(JSON.stringify([decision.id, decision.index, decision.phase]));
+
+  const rememberPhase = (item: unknown, outputIndex: unknown, phase: OcxMessagePhase): void => {
+    const id = isPlainObject(item) && typeof item.id === "string" ? item.id : null;
+    const index = outputIndexOf(outputIndex);
+    if (id === null && index === null) return;
+    const next: PhaseDecision = { id, index, phase };
+    const replaced = new Set<PhaseDecision>();
+    const previousById = id !== null ? byId.get(id) : undefined;
+    const previousByIndex = index !== null ? byIndex.get(index) : undefined;
+    if (previousById) replaced.add(previousById);
+    if (previousByIndex) replaced.add(previousByIndex);
+    let delta = decisionSize(next);
+    for (const previous of replaced) delta -= decisionSize(previous);
+    // Charge before mutating, so a budget rejection leaves state consistent.
+    if (delta > 0) budget.chargeRetained(delta, scope);
+    else if (delta < 0) budget.releaseRetained(-delta, scope);
+    for (const previous of replaced) {
+      if (previous.id !== null && byId.get(previous.id) === previous) byId.delete(previous.id);
+      if (previous.index !== null && byIndex.get(previous.index) === previous) byIndex.delete(previous.index);
+    }
+    if (id !== null) byId.set(id, next);
+    if (index !== null) byIndex.set(index, next);
+    decisionBytes += delta;
+  };
+
+  const releasePending = (phase: OcxMessagePhase): readonly string[] => {
+    if (pending === null) return [];
+    const block = pending;
+    const parsed = parseDataPayload(block);
+    rememberPhase(parsed?.item, parsed?.output_index, phase);
+    const patched = withMessagePhase(block, phase);
+    budget.releaseRetained(pendingBytes, scope);
+    pending = null;
+    pendingBytes = 0;
+    return [patched];
+  };
+
+  const rewrite = (block: string): readonly string[] => {
+    const parsed = parseDataPayload(block);
+    const type = typeof parsed?.type === "string" ? parsed.type : null;
+    if (TERMINAL_EVENT_TYPES.has(type!)) {
+      // Turn end: any still-buffered message is the final answer, and the
+      // terminal snapshot mirrors the same per-item decisions for consistency.
+      const released = releasePending("final_answer");
+      const snapshot = type === "response.failed" ? block : withSnapshotPhases(block, decisions);
+      clearState();
+      return [...released, snapshot];
+    }
+    if (type === "response.output_item.done" && isMessageDoneBlock(block)) {
+      const item = parsed?.item;
+      if (isPlainObject(item) && isMessagePhase(item.phase)) {
+        // An explicit upstream phase needs no inference: forward immediately
+        // instead of buffering a message that an abnormal teardown would
+        // otherwise drop before it was ever emitted.
+        const released = releasePending("commentary");
+        rememberPhase(item, parsed?.output_index, item.phase);
+        return [...released, block];
+      }
+      // A following message done means the turn continued past the buffered
+      // one (a phase change or a guarded continuation): commentary. Buffer
+      // the current block for classification by whatever comes next.
+      const released = releasePending("commentary");
+      const bytes = Buffer.byteLength(block);
+      budget.chargeRetained(bytes, scope);
+      pending = block;
+      pendingBytes = bytes;
+      return released;
+    }
+    if (type === null) {
+      // Comment keepalives and other non-JSON data blocks carry no
+      // classification evidence in either direction, so a still-buffered
+      // message stays pending across them. The [DONE] sentinel closes the
+      // stream cleanly, which proves the buffered message was the turn's
+      // final answer.
+      if (isDoneSentinel(block)) {
+        const released = releasePending("final_answer");
+        clearState();
+        return [...released, block];
+      }
+      return [block];
+    }
+    // Any other protocol event after a completed message proves the turn
+    // continued past it (tool calls, reasoning, a new item): commentary.
+    return [...releasePending("commentary"), block];
+  };
+
+  return Object.assign((block: string): readonly string[] => {
+    try { return rewrite(block); }
+    catch (error) {
+      clearState();
+      throw error;
+    }
+  }, {
+    dispose: () => {
+      // Relay teardown after a terminal event leaves nothing pending. An
+      // abnormal teardown before classification drops the retained block,
+      // since the stream is failing anyway and no phase was ever proven.
+      clearState();
+    },
+  });
+}

package/src/server/sse-payload-rewrite.ts

@@ -96,6 +96,8 @@ export function createSseBlockBuffer(
   let buffer = "";
   let offset = 0;
   let scanOffset = 0;
+  let needsScan = false;
+  let lastCodeUnit = Number.NaN;
   let bufferBytes = 0;
   const delimiterPattern = /(?:\r\n|\r(?!\n)|\n){2}/g;
 
@@ -111,7 +113,7 @@ export function createSseBlockBuffer(
       if (!fragment) return;
       let fragmentBytes = Buffer.byteLength(fragment, "utf8");
       // Decoder output never splits a surrogate pair, but keep the helper exact for string callers.
-      const last = buffer.charCodeAt(buffer.length - 1);
+      const last = lastCodeUnit;
       const first = fragment.charCodeAt(0);
       if (offset < buffer.length && last >= 0xd800 && last <= 0xdbff && first >= 0xdc00 && first <= 0xdfff) {
         fragmentBytes -= 2;
@@ -122,6 +124,8 @@ export function createSseBlockBuffer(
       try {
         compact();
         buffer += fragment;
+        lastCodeUnit = fragment.charCodeAt(fragment.length - 1);
+        needsScan ||= fragment.includes("\r") || fragment.includes("\n");
         reservation.commitRetained();
         budget.releaseRetained(bufferBytes, scope);
         bufferBytes = nextBytes;
@@ -131,11 +135,16 @@ export function createSseBlockBuffer(
       }
     },
     next() {
+      if (!needsScan) {
+        scanOffset = Math.max(offset, buffer.length - 3);
+        return null;
+      }
       delimiterPattern.lastIndex = scanOffset;
       const match = delimiterPattern.exec(buffer);
       if (!match) {
         // A delimiter is at most four code units. Revisit only its possible split prefix.
         scanOffset = Math.max(offset, buffer.length - 3);
+        needsScan = false;
         return null;
       }
       const start = match.index;
@@ -153,6 +162,8 @@ export function createSseBlockBuffer(
         buffer = "";
         offset = 0;
         scanOffset = 0;
+        needsScan = false;
+        lastCodeUnit = Number.NaN;
       }
       return { block, delimiter };
     },
@@ -164,6 +175,8 @@ export function createSseBlockBuffer(
       buffer = "";
       offset = 0;
       scanOffset = 0;
+      needsScan = false;
+      lastCodeUnit = Number.NaN;
       bufferBytes = 0;
     },
   };

package/src/service/definition.ts

@@ -7,7 +7,8 @@
  * route back through them (see `installedServiceListenPort` in `health.ts`, which
  * intentionally stays behind because it asks every backend).
  */
-import { loadConfig } from "../config";
+import { getConfigDir, loadConfig } from "../config";
+import { readClaudeInterceptProxyToken } from "../claude/intercept/proxy-auth";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { PROXY_ENV_KEYS } from "../lib/proxy-env";
 
@@ -87,19 +88,30 @@ export function parseBakedListenPort(read: () => string): number | null {
  * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
  * upper-case name is baked, so a definition never carries two spellings of one setting.
  */
-export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
+export function resolvedProxyEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  ownClaudeInterceptProxy?: string | null,
+): { name: string; value: string }[] {
+  const token = ownClaudeInterceptProxy === undefined ? readClaudeInterceptProxyToken(getConfigDir()) : null;
   const resolved: { name: string; value: string }[] = [];
   for (const key of PROXY_ENV_KEYS) {
-    const value = [env[key]?.trim(), env[key.toLowerCase()]?.trim()].find(v => v && !OWN_CLAUDE_INTERCEPT_PROXY.test(v));
+    const value = [env[key]?.trim(), env[key.toLowerCase()]?.trim()].find(v => v && (
+      ownClaudeInterceptProxy === undefined ? !isOwnedClaudeInterceptProxy(v, token) : v !== ownClaudeInterceptProxy
+    ));
     if (value) resolved.push({ name: key, value });
   }
   return resolved;
 }
 
 /**
- * The URL Claude first-party writes into `~/.claude/settings.json` (`claudeInterceptProxyUrl`),
- * which every process Claude Code starts inherits. Baked into the service, it would send the
- * proxy's own outbound traffic back through its intercept listener. Only the token-bearing form
- * is matched: a plain `http://127.0.0.1:<port>` is a user's local proxy client and is kept.
+ * Match this installation's credential and exact URL components without creating a token.
+ * An inherited URL can still use an old bound port after the persisted config changes.
+ * Shape alone cannot establish ownership: a user proxy may also use an `opencodex` username.
  */
-const OWN_CLAUDE_INTERCEPT_PROXY = /^http:\/\/opencodex:[^@/]+@127\.0\.0\.1:\d{1,5}\/?$/i;
+function isOwnedClaudeInterceptProxy(value: string, token: string | null): boolean {
+  if (!token) return false;
+  const prefix = `http://opencodex:${encodeURIComponent(token)}@127.0.0.1:`;
+  if (!value.startsWith(prefix)) return false;
+  const port = value.slice(prefix.length).replace(/\/$/, "");
+  return /^\d{1,5}$/.test(port) && Number(port) > 0 && Number(port) <= 65535;
+}

package/src/types/config.ts

@@ -1496,6 +1496,12 @@ export interface OcxComboConfig {
   decisionQuotaSignals?: boolean | null;
   /** Partial 0..100 tier overrides; defaults limited 70/nearlyExhausted 90. null clears. */
   decisionQuotaTiers?: import("../combos/jev-quota-config").JevQuotaTiers | null;
+  /**
+   * `strategy: "jev"` only, default off: keep an explicit client session on the target JEV chose
+   * for it while the session stays active, so the provider prompt cache stays warm (#7525).
+   * `ttlMs` is the idle window after the last successful turn (60000..86400000). null clears.
+   */
+  sessionPin?: import("../combos/jev-session-pin-config").JevSessionPinConfig | null;
 }
 
 export type OcxRoutingUnknownEvidenceMode = "allow" | "penalize" | "exclude";

package/src/types/provider.ts

@@ -871,6 +871,14 @@ export interface OcxProviderConfig {
    * SSE/JSON; raw inspection state remains authoritative.
    */
   responsesSnapshotRepair?: boolean;
+  /**
+   * Infer the commentary/final_answer phase on assistant messages for Responses passthrough
+   * providers whose upstream omits it (e.g. third-party gateways). Codex desktop collapses
+   * commentary into progress rows; without this every narration renders fully expanded.
+   * Disabled by default. Applies in the client-facing SSE rewrite chain, including
+   * buffered JSON reconstructed from upstream SSE; ordinary upstream JSON is unchanged.
+   */
+  messagePhaseInference?: boolean;
   /**
    * Opt-in hosted-web-search bridge for this KEY-auth Responses passthrough provider (#3761).
    * Absent or disabled leaves the passthrough byte-identical to today.
@@ -1116,7 +1124,7 @@ export interface OcxProviderConfig {
   googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
   /** Google tool-schema compatibility policy. Omitted preserves compatible report-only behavior. */
   googleToolSchemaPolicy?: "compatible" | "reject-lossy";
-  /** Vertex AI GCP project id. API keys use it to select the project endpoint; ADC falls back to GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env. */
+  /** Vertex AI GCP project id. API keys use it to select the project endpoint; "auto" resolves each API key's own project. ADC falls back to GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env. */
   project?: string;
   /** Vertex AI location, e.g. "us-central1" or "global". API-key project endpoints default to "global"; ADC falls back to GOOGLE_CLOUD_LOCATION env. */
   location?: string;

package/src/types/request.ts

@@ -148,6 +148,7 @@ export interface OcxParsedRequest {
   _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion" | "authType">;
   /** Account-scoped Zed user identity paired with the long-lived access token. */
   _zedAuthContext?: { userId: string };
+  _workbuddyAuthContext?: import("../oauth/types").WorkBuddyOAuthMetadata;
   /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
   _providerContinuation?: OcxProviderContinuationState;
   /** Persisted continuation considered only after the final physical route is known. */

package/src/types/wire.ts

@@ -101,6 +101,7 @@ function normalizedEndpoint(value: unknown): string | undefined {
  * URL. The empty prefix covers every model id.
  */
 const CREDENTIAL_PINNED_ADAPTERS: Readonly<Record<string, Readonly<Record<string, string>>>> = Object.freeze({
+  "workbuddy-ai": Object.freeze({ "": "workbuddy-ai" }),
   "dsh-account": Object.freeze({ "": "dsh-account" }),
 });
 

package/src/update/codex-cli-update-launch-policy.d.mts

@@ -16,3 +16,12 @@ export const CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS: readonly [
   "VOLTA_HOME",
 ];
 export function isCodexCliUpdateInspectionArgv(argv: readonly string[]): boolean;
+export const NODE_LAUNCH_CONTEXT_MAX_CHARS: number;
+export function codexCliInspectionLookupSeeds(
+  platform: string,
+  home: string | null,
+  nodePath: string | null,
+  serializedContextChars: number,
+): { home: string | null; nodePath: string | null };
+export const CODEX_CLI_TRANSPORT_ENV_KEYS: readonly string[];
+export function captureCodexCliTransportEnv(env: Readonly<NodeJS.ProcessEnv>): Record<string, string>;

package/src/update/codex-cli-update-launch-policy.mjs

@@ -16,6 +16,16 @@ export const CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS = Object.freeze([
   "VOLTA_HOME",
 ]);
 
+export const CODEX_CLI_TRANSPORT_ENV_KEYS = Object.freeze([
+  "http_proxy", "https_proxy", "all_proxy", "no_proxy", "node_extra_ca_certs",
+]);
+
+/** Preserve spelling, aliases and empty values before Bun loads project dotenv. */
+export function captureCodexCliTransportEnv(env) {
+  return Object.fromEntries(Object.entries(env).filter(([name, value]) =>
+    CODEX_CLI_TRANSPORT_ENV_KEYS.includes(name.toLowerCase()) && typeof value === "string"));
+}
+
 /**
  * Detect the read-only Codex CLI updater inspection namespace before Bun loads.
  * Keep this exact and argument-position based: malformed actions still inherit
@@ -28,3 +38,23 @@ export function isCodexCliUpdateInspectionArgv(argv) {
   const args = argv.slice(2).filter(value => !value.startsWith("--ocx-internal-launch-proof="));
   return args[0] === "system" && args[1] === "codex-cli-update";
 }
+
+/** Serialized OCX_NODE_LAUNCH_CONTEXT ceiling; src/cli/launcher-context.ts refuses above it. */
+export const NODE_LAUNCH_CONTEXT_MAX_CHARS = 64 * 1024;
+
+/**
+ * The HOME/NODE_PATH seeds the update inspection's modeled Node lookup needs,
+ * bounded against the launch-context budget. They are POSIX-only: a Windows
+ * inspection never models the global lookup, so the seeds are not sent at all
+ * (and their env copies stay inherited for the child's own use). If carrying
+ * them would push the serialized context past the reader's limit they are
+ * dropped instead of taking the whole snapshot down with them — absent seeds
+ * leave only the global lane unverifiable, which fails the content
+ * observation closed while the selection context survives.
+ */
+export function codexCliInspectionLookupSeeds(platform, home, nodePath, serializedContextChars) {
+  if (platform === "win32" || serializedContextChars > NODE_LAUNCH_CONTEXT_MAX_CHARS) {
+    return { home: null, nodePath: null };
+  }
+  return { home: home ?? null, nodePath: nodePath ?? null };
+}

package/src/usage/jev-stats.ts

@@ -1,4 +1,5 @@
 import { normalizeJevQuotaSummary, type JevQuotaDecisionSummary } from "../combos/jev-quota-config";
+import { JEV_SESSION_PIN_REASONS, type JevSessionPinReason } from "../combos/jev-session-pin-config";
 import type { OcxComboDefaultEffort } from "../types";
 import type { PersistedUsageEntry } from "./log";
 import { usageDisplayTotalTokens } from "./totals";
@@ -48,6 +49,10 @@ export interface PersistedJevDecisionV1 {
     outputTokens: number;
     totalTokens: number;
   };
+  /** The turn reused its session pin (#7525); no decision request was sent for it. */
+  pinned?: true;
+  /** `session` with `pinned`; otherwise why an existing session pin was released. */
+  pinReason?: JevSessionPinReason;
 }
 
 export interface JevStatsModelRow {
@@ -88,6 +93,8 @@ export interface JevStatsResponse {
     decisions: number;
     appliedDecisions: number;
     failOpenDecisions: number;
+    /** Requests that reused a session pin; they are not decisions and add only physical attempts. */
+    pinnedRequests: number;
     successfulRequests: number;
     requestsWithModelFallback: number;
     modelAttempts: number;
@@ -188,6 +195,13 @@ export function normalizePersistedJevDecision(value: unknown): PersistedJevDecis
   const backend = value.backend === "typesafe" || value.backend === "systemone" || value.backend === "model"
     ? value.backend
     : undefined;
+  const pinReason = typeof value.pinReason === "string"
+    && (JEV_SESSION_PIN_REASONS as readonly string[]).includes(value.pinReason)
+    ? value.pinReason as JevSessionPinReason
+    : undefined;
+  // A pinned turn always says so with `session`; any other pairing is not a record this writes.
+  const pinned = value.pinned === true && pinReason === "session";
+  if ((value.pinned === true || pinReason === "session") && !pinned) return undefined;
   return {
     version: 1,
     comboId,
@@ -203,6 +217,8 @@ export function normalizePersistedJevDecision(value: unknown): PersistedJevDecis
     ...(confidence !== undefined ? { confidence } : {}),
     ...(chosenProbability !== undefined ? { chosenProbability } : {}),
     ...(usage ? { usage } : {}),
+    ...(pinned ? { pinned: true as const } : {}),
+    ...(pinReason ? { pinReason } : {}),
   };
 }
 
@@ -210,6 +226,24 @@ interface MutableModelRow extends Omit<JevStatsModelRow, "efforts"> {
   effortCounts: Map<OcxComboDefaultEffort | null, number>;
 }
 
+interface SentAttempt {
+  attempt: NonNullable<PersistedUsageEntry["attempts"]>[number];
+  provider: string;
+  model: string;
+  sendCount: number;
+}
+
+/** Attempts that physically sent, with bounded identities; zero-send rows never count. */
+function sentAttempts(entry: PersistedUsageEntry): SentAttempt[] {
+  return (entry.attempts ?? []).flatMap(attempt => {
+    const sendCount = boundedCount(attempt.sendCount) ?? 0;
+    if (sendCount === 0) return [];
+    const provider = boundedIdentity(attempt.provider, MAX_TARGET_IDENTITY_CHARS);
+    const model = boundedIdentity(attempt.model, MAX_TARGET_IDENTITY_CHARS);
+    return provider && model ? [{ attempt, provider, model, sendCount }] : [];
+  });
+}
+
 interface JevStatsAccumulatorOptions {
   comboId?: string | null;
   since?: number | null;
@@ -291,6 +325,7 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
   private snapshotWindowStart: number | null = null;
   private snapshotWindowEnd: number | null = null;
   private decisions = 0;
+  private pinnedRequests = 0;
   private appliedDecisions = 0;
   private successfulRequests = 0;
   private requestsWithModelFallback = 0;
@@ -358,6 +393,21 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
       || (this.until !== undefined && entry.timestamp > this.until)) return;
     const decision = normalizePersistedJevDecision(entry.jevDecision);
     if (!decision || (this.comboId !== null && decision.comboId !== this.comboId)) return;
+    const attempts = sentAttempts(entry);
+    // Request-level outcomes count every JEV-routed request, pinned or decided.
+    if (entry.status >= 200 && entry.status < 400) {
+      this.successfulRequests = saturatingAdd(this.successfulRequests, 1);
+    }
+    if (attempts.some(({ provider, model }) => provider !== decision.selected.provider
+      || model !== decision.selected.model)) {
+      this.requestsWithModelFallback = saturatingAdd(this.requestsWithModelFallback, 1);
+    }
+    this.addAttempts(attempts);
+    if (decision.pinned) {
+      // A session-pinned turn sent no decision request, so it stays out of every decision total.
+      this.pinnedRequests = saturatingAdd(this.pinnedRequests, 1);
+      return;
+    }
 
     const backend = decision.backend ?? "unknown";
     const backendRow = this.backends.get(backend)
@@ -369,9 +419,6 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
     this.averageLatencyMs = nextMean(this.averageLatencyMs, this.decisions, decision.latencyMs);
     this.decisions = saturatingAdd(this.decisions, 1);
     if (decision.gate === "apply") this.appliedDecisions = saturatingAdd(this.appliedDecisions, 1);
-    if (entry.status >= 200 && entry.status < 400) {
-      this.successfulRequests = saturatingAdd(this.successfulRequests, 1);
-    }
     this.gates.set(decision.gate, saturatingAdd(this.gates.get(decision.gate) ?? 0, 1));
     if (decision.confidence !== undefined) {
       this.confidenceTotal = saturatingAdd(this.confidenceTotal, decision.confidence);
@@ -396,18 +443,9 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
       decision.selected.effort,
       saturatingAdd(selected.effortCounts.get(decision.selected.effort) ?? 0, 1),
     );
+  }
 
-    const attempts = (entry.attempts ?? []).flatMap(attempt => {
-      const sendCount = boundedCount(attempt.sendCount) ?? 0;
-      if (sendCount === 0) return [];
-      const provider = boundedIdentity(attempt.provider, MAX_TARGET_IDENTITY_CHARS);
-      const model = boundedIdentity(attempt.model, MAX_TARGET_IDENTITY_CHARS);
-      return provider && model ? [{ attempt, provider, model, sendCount }] : [];
-    });
-    if (attempts.some(({ provider, model }) => provider !== decision.selected.provider
-      || model !== decision.selected.model)) {
-      this.requestsWithModelFallback = saturatingAdd(this.requestsWithModelFallback, 1);
-    }
+  private addAttempts(attempts: readonly SentAttempt[]): void {
     for (const { attempt, provider, model: modelId, sendCount } of attempts) {
       const model = this.rowFor(provider, modelId);
       model.attempts = saturatingAdd(model.attempts, sendCount);
@@ -449,6 +487,7 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
     cloned.snapshotWindowStart = this.snapshotWindowStart;
     cloned.snapshotWindowEnd = this.snapshotWindowEnd;
     cloned.decisions = this.decisions;
+    cloned.pinnedRequests = this.pinnedRequests;
     cloned.appliedDecisions = this.appliedDecisions;
     cloned.successfulRequests = this.successfulRequests;
     cloned.requestsWithModelFallback = this.requestsWithModelFallback;
@@ -492,6 +531,7 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
         decisions: this.decisions,
         appliedDecisions: this.appliedDecisions,
         failOpenDecisions: this.decisions - this.appliedDecisions,
+        pinnedRequests: this.pinnedRequests,
         successfulRequests: this.successfulRequests,
         requestsWithModelFallback: this.requestsWithModelFallback,
         modelAttempts: this.modelAttempts,