@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/oauth/chatgpt-shared.ts

@@ -0,0 +1,83 @@
+import type { OAuthCredentials } from "./types";
+
+/**
+ * What the browser callback grant and the deviceauth grant share: the public PKCE client and the
+ * way a token response becomes credentials.
+ *
+ * This is a leaf on purpose. `./chatgpt-device` needs these, and `./chatgpt` needs the device
+ * grant for `flow: "device"`; importing them straight from `./chatgpt` made the pair a cycle.
+ */
+
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+
+/** Shared with the deviceauth grant in `./chatgpt-device`: same public PKCE client. */
+export const CHATGPT_CLIENT_ID = CLIENT_ID;
+export const CHATGPT_TOKEN_URL = TOKEN_URL;
+
+export function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[1]) return undefined;
+  try {
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractAccountId(idToken?: string, accessToken?: string): string | undefined {
+  for (const token of [idToken, accessToken]) {
+    if (!token) continue;
+    const payload = decodeJwtPayload(token);
+    if (!payload) continue;
+    if (typeof payload.chatgpt_account_id === "string") return payload.chatgpt_account_id;
+    const ns = payload["https://api.openai.com/auth"];
+    if (ns && typeof ns === "object" && typeof (ns as Record<string, unknown>).chatgpt_account_id === "string") {
+      return (ns as Record<string, unknown>).chatgpt_account_id as string;
+    }
+    const orgs = payload.organizations;
+    if (Array.isArray(orgs) && orgs[0] && typeof orgs[0].id === "string") return orgs[0].id as string;
+  }
+  return undefined;
+}
+
+export function extractEmail(idToken?: string, accessToken?: string): string | undefined {
+  for (const token of [idToken, accessToken]) {
+    if (!token) continue;
+    const payload = decodeJwtPayload(token);
+    if (!payload) continue;
+    if (typeof payload.email === "string") return payload.email.toLowerCase();
+  }
+  return undefined;
+}
+
+export function credsFromToken(data: Record<string, unknown>): OAuthCredentials {
+  const idToken = typeof data.id_token === "string" ? data.id_token : undefined;
+  // This parses a response from an external boundary, so the access token is
+  // validated rather than cast. A 200 carrying no access_token would otherwise
+  // resolve a login as successful with an undefined credential, which then gets
+  // silently declined at persistence — a success message and no account.
+  const accessToken = typeof data.access_token === "string" && data.access_token.length > 0
+    ? data.access_token
+    : undefined;
+  if (!accessToken) throw new Error("ChatGPT token response missing access token");
+  const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
+  // ?? only guards null/undefined; NaN or a string expires_in would otherwise
+  // produce a NaN expiry that never compares as expired, and a negative duration
+  // would stamp an already-past expiry — both block refresh semantics.
+  const expiresIn =
+    typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
+      ? data.expires_in
+      : 3600;
+  // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
+  // Number.isFinite but overflows to Infinity once multiplied by 1000.
+  const computedExpires = Date.now() + expiresIn * 1000;
+  const expires = Number.isFinite(computedExpires) ? computedExpires : Date.now() + 3600 * 1000;
+  return {
+    access: accessToken,
+    refresh: refreshToken,
+    expires,
+    accountId: extractAccountId(idToken, accessToken),
+    email: extractEmail(idToken, accessToken),
+  };
+}

package/src/oauth/chatgpt.ts

@@ -1,4 +1,5 @@
 import { OAuthCallbackFlow } from "./callback-server";
+import { CHATGPT_CLIENT_ID, CHATGPT_TOKEN_URL, credsFromToken, decodeJwtPayload, extractAccountId, extractEmail } from "./chatgpt-shared";
 import type { OAuthController, OAuthCredentials } from "./types";
 import { generatePKCE } from "./pkce";
 import { classifyChatgptRefreshFailure } from "../codex/chatgpt-refresh-failure";
@@ -102,44 +103,20 @@ function chatGptTokenError(status: number, body: string, label: string): ChatGpt
   );
 }
 
-const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+/**
+ * The client and token decoding live in a leaf shared with the device grant.
+ * Re-exported so existing import sites keep their public helper surface.
+ */
+export { CHATGPT_CLIENT_ID, CHATGPT_TOKEN_URL, credsFromToken, decodeJwtPayload, extractAccountId, extractEmail };
+const CLIENT_ID = CHATGPT_CLIENT_ID;
 const AUTH_URL = "https://auth.openai.com/oauth/authorize";
-const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const TOKEN_URL = CHATGPT_TOKEN_URL;
 
-/** Shared with the deviceauth grant in `./chatgpt-device`: same public PKCE client. */
-export const CHATGPT_CLIENT_ID = CLIENT_ID;
-export const CHATGPT_TOKEN_URL = TOKEN_URL;
 const SCOPE = "openid profile email offline_access api.connectors.read api.connectors.invoke";
 const CALLBACK_PORT = 1455;
 const CALLBACK_PATH = "/auth/callback";
 const ORIGINATOR = "opencodex";
 
-export function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
-  const parts = token.split(".");
-  if (parts.length !== 3 || !parts[1]) return undefined;
-  try {
-    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as Record<string, unknown>;
-  } catch {
-    return undefined;
-  }
-}
-
-export function extractAccountId(idToken?: string, accessToken?: string): string | undefined {
-  for (const token of [idToken, accessToken]) {
-    if (!token) continue;
-    const payload = decodeJwtPayload(token);
-    if (!payload) continue;
-    if (typeof payload.chatgpt_account_id === "string") return payload.chatgpt_account_id;
-    const ns = payload["https://api.openai.com/auth"];
-    if (ns && typeof ns === "object" && typeof (ns as Record<string, unknown>).chatgpt_account_id === "string") {
-      return (ns as Record<string, unknown>).chatgpt_account_id as string;
-    }
-    const orgs = payload.organizations;
-    if (Array.isArray(orgs) && orgs[0] && typeof orgs[0].id === "string") return orgs[0].id as string;
-  }
-  return undefined;
-}
-
 /**
  * Three-way answer to "is this token marked as belonging to the ChatGPT account domain".
  * Only ChatGPT-specific claims count as markers: a top-level chatgpt_account_id or the
@@ -196,16 +173,6 @@ export function inspectChatGptDomainClaim(token: string): ChatGptDomainClaim {
   return accountId ? { kind: "valid", accountId } : { kind: "invalid" };
 }
 
-export function extractEmail(idToken?: string, accessToken?: string): string | undefined {
-  for (const token of [idToken, accessToken]) {
-    if (!token) continue;
-    const payload = decodeJwtPayload(token);
-    if (!payload) continue;
-    if (typeof payload.email === "string") return payload.email.toLowerCase();
-  }
-  return undefined;
-}
-
 /**
  * Identity-agreement view of one token for security-sensitive bindings. `accountId` follows the
  * existing extractAccountId precedence (top-level, then namespaced, then organizations[0]).
@@ -233,37 +200,6 @@ export function extractAccountIdClaims(token?: string): { accountId: string | un
   };
 }
 
-export function credsFromToken(data: Record<string, unknown>): OAuthCredentials {
-  const idToken = typeof data.id_token === "string" ? data.id_token : undefined;
-  // This parses a response from an external boundary, so the access token is
-  // validated rather than cast. A 200 carrying no access_token would otherwise
-  // resolve a login as successful with an undefined credential, which then gets
-  // silently declined at persistence — a success message and no account.
-  const accessToken = typeof data.access_token === "string" && data.access_token.length > 0
-    ? data.access_token
-    : undefined;
-  if (!accessToken) throw new Error("ChatGPT token response missing access token");
-  const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
-  // ?? only guards null/undefined; NaN or a string expires_in would otherwise
-  // produce a NaN expiry that never compares as expired, and a negative duration
-  // would stamp an already-past expiry — both block refresh semantics.
-  const expiresIn =
-    typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
-      ? data.expires_in
-      : 3600;
-  // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
-  // Number.isFinite but overflows to Infinity once multiplied by 1000.
-  const computedExpires = Date.now() + expiresIn * 1000;
-  const expires = Number.isFinite(computedExpires) ? computedExpires : Date.now() + 3600 * 1000;
-  return {
-    access: accessToken,
-    refresh: refreshToken,
-    expires,
-    accountId: extractAccountId(idToken, accessToken),
-    email: extractEmail(idToken, accessToken),
-  };
-}
-
 export class ChatGPTOAuthFlow extends OAuthCallbackFlow {
   #verifier = "";
   forceLogin = false;

package/src/oauth/dsh.ts

@@ -0,0 +1,203 @@
+/**
+ * DeepSeek Harness Account OAuth implementation (Import-first).
+ *
+ * Imports existing authenticated account from DeepSeek Harness Desktop
+ * (`$DSH_HOME/.credentials.yaml`, default `~/.dsh/.credentials.yaml`).
+ *
+ * Invariant: The DSH credential store is strictly READ-ONLY to OpenCodeX.
+ * OpenCodeX NEVER mutates, overwrites, deletes, or changes permissions of `~/.dsh/.credentials.yaml`.
+ */
+
+import type { OAuthController, OAuthCredentials } from "./types";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+export const DSH_PLATFORM_ORIGIN = "https://platform.deepseek.com";
+export const DSH_INFERENCE_ORIGIN = "https://api.deepseek.com/anthropic";
+
+export interface DshAccountDetectionResult {
+  detected: boolean;
+  token?: string;
+  issuer?: string;
+  error?: string;
+}
+
+export interface DshValidatedAccountIdentity {
+  valid: boolean;
+  accountId?: string;
+  email?: string;
+  name?: string;
+  error?: string;
+}
+
+export function resolveDshCredentialsPath(): string {
+  const dshHome = process.env.DSH_HOME?.trim() || join(homedir(), ".dsh");
+  return join(dshHome, ".credentials.yaml");
+}
+
+/**
+ * Pure read-only probe to detect whether DeepSeek Harness Desktop is installed
+ * and signed in on this machine.
+ * NEVER writes, creates, mutates, or deletes any file.
+ */
+export function detectDshAccount(): DshAccountDetectionResult {
+  const filePath = resolveDshCredentialsPath();
+  if (!existsSync(filePath)) {
+    return { detected: false };
+  }
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const data = Bun.YAML.parse(content) as Record<string, unknown> | null;
+    if (!data || typeof data !== "object") {
+      return { detected: false };
+    }
+    const records = data.records as Record<string, unknown> | undefined;
+    const accountRecord = records?.["deepseek-account-platform/default"] as {
+      kind?: string;
+      payload?: { version?: number; token?: string; issuer?: string };
+    } | undefined;
+
+    if (accountRecord?.kind === "grant" && typeof accountRecord.payload?.token === "string" && accountRecord.payload.token.length > 0) {
+      return {
+        detected: true,
+        token: accountRecord.payload.token,
+        issuer: accountRecord.payload.issuer ?? DSH_PLATFORM_ORIGIN,
+      };
+    }
+    return { detected: false };
+  } catch {
+    return { detected: false, error: "CREDENTIAL_FILE_READ_FAILED" };
+  }
+}
+
+/**
+ * Validate token against DeepSeek's authoritative profile endpoint:
+ * GET https://platform.deepseek.com/auth-api/v0/users/current
+ */
+export async function validateDshAccountToken(
+  token: string,
+  signal?: AbortSignal,
+): Promise<DshValidatedAccountIdentity> {
+  try {
+    const timeoutSignal = AbortSignal.timeout(10_000);
+    const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    const response = await fetch(`${DSH_PLATFORM_ORIGIN}/auth-api/v0/users/current`, {
+      method: "GET",
+      headers: {
+        "x-dsh-auth-token": token,
+        "accept": "application/json",
+      },
+      redirect: "manual",
+      signal: combinedSignal,
+    });
+
+    if (response.status === 401) {
+      return { valid: false, error: "ACCOUNT_TOKEN_INVALID" };
+    }
+    if (!response.ok) {
+      return { valid: false, error: `Platform returned HTTP ${response.status}` };
+    }
+
+    const body = (await response.json()) as {
+      code?: number;
+      data?: {
+        biz_code?: number;
+        biz_data?: {
+          id?: string | null;
+          email?: string;
+          id_profile?: { name?: string | null; picture?: string | null };
+        };
+      };
+    };
+
+    if (body.code !== 0 || body.data?.biz_code !== 0 || !body.data.biz_data) {
+      return { valid: false, error: `Platform error code: ${body.code ?? "unknown"}` };
+    }
+
+    const biz = body.data.biz_data;
+    // Account-store slot matching and reauthentication require the same stable upstream ID.
+    // Email/phone/display names and a shared fallback must never identify an imported account.
+    const accountId = typeof biz.id === "string" ? biz.id.trim() : "";
+    if (!accountId) return { valid: false, error: "ACCOUNT_IDENTITY_UNVERIFIED" };
+    const email = typeof biz.email === "string" ? biz.email.trim() || undefined : undefined;
+    const name = typeof biz.id_profile?.name === "string" ? biz.id_profile.name.trim() || undefined : undefined;
+
+    return {
+      valid: true,
+      accountId,
+      email,
+      name,
+    };
+  } catch {
+    if (signal?.aborted) throw signal.reason ?? new DOMException("DSH login aborted", "AbortError");
+    // Parser and transport errors may contain profile data or credential-file contents.
+    return { valid: false, error: "PROFILE_VALIDATION_FAILED" };
+  }
+}
+
+export interface DshLoginOptions {
+  forceLogin?: boolean;
+}
+
+/**
+ * Explicit user login action for DSH Account.
+ * Reuses the existing DSH local credential after live authoritative validation.
+ */
+export async function loginDshAccount(
+  ctrl: OAuthController,
+  _opts: DshLoginOptions = {},
+): Promise<OAuthCredentials> {
+  if (ctrl.signal?.aborted) {
+    throw ctrl.signal.reason ?? new DOMException("DSH login aborted", "AbortError");
+  }
+
+  const detection = detectDshAccount();
+  if (!detection.detected || !detection.token) {
+    throw new Error(
+      "DeepSeek Harness account not found in ~/.dsh/.credentials.yaml. " +
+      "Please sign in to DeepSeek Harness Desktop first, then import your account.",
+    );
+  }
+
+  const validation = await validateDshAccountToken(detection.token, ctrl.signal);
+  if (!validation.valid || !validation.accountId) {
+    throw new Error(
+      `DeepSeek Harness account token in ~/.dsh/.credentials.yaml is invalid or expired (${validation.error ?? "unknown"}). ` +
+      "Please re-login in DeepSeek Harness Desktop, then try again.",
+    );
+  }
+
+  return {
+    access: detection.token,
+    refresh: detection.token,
+    expires: Number.MAX_SAFE_INTEGER,
+    accountId: validation.accountId,
+    email: validation.email,
+    source: "credential-file",
+  };
+}
+
+/**
+ * Token refresh for DSH Account.
+ * DSH accounts use long-lived session grant tokens without an automatic rotation endpoint.
+ * In accordance with the explicit-import contract, background or automatic refresh MUST NOT
+ * automatically re-read or adopt new credentials from ~/.dsh/.credentials.yaml.
+ * If the grant is rejected or expires, this throws a terminal error so the account transitions
+ * to needsReauth, requiring explicit user re-import.
+ */
+export async function refreshDshAccountToken(
+  _refreshToken: string,
+  _signal?: AbortSignal,
+  _credential?: OAuthCredentials,
+  _accountId?: string,
+): Promise<OAuthCredentials> {
+  throw new Error("DeepSeek Harness account session expired or revoked. Please sign in to DeepSeek Harness Desktop and re-import.");
+}
+
+/** Provider-owned auth hooks keep the shared OAuth registry within its line budget. */
+export const DSH_ACCOUNT_AUTH = {
+  login: loginDshAccount,
+  refresh: refreshDshAccountToken,
+  defaultRefreshPolicy: "disabled" as const,
+};

package/src/oauth/generic-account-failover.ts

@@ -7,9 +7,9 @@ import { isBuiltinAnthropicInstanceRow } from "../providers/anthropic-instance";
  * exists is Anthropic's — behind its own opt-in. So xAI, Cursor, Kimi, GitHub Copilot,
  * Antigravity and Nous have no recovery path on a 429 even with several accounts logged in.
  *
- * Deliberately narrower than the Anthropic pool: no session affinity, no quota-ranked selection,
- * no probe leases. Those carry provider-specific meaning; this module only answers "the account
- * that just 429'd is cooled, is there another one we may use".
+ * Conversation ownership lives in generic-session-affinity.ts; this module owns account
+ * eligibility, quota-ranked preference and bounded refusal recovery. Probe leases remain
+ * provider-specific.
  *
  * NOT a home for Codex (`codex/routing.ts` owns quota scopes and probe leases) or Anthropic
  * (`oauth/anthropic-routing.ts` owns affinity and a fail-closed local-cli credential rule).
@@ -25,6 +25,7 @@ import {
   hasHeadroomEvidence,
   isAccountQuotaExhausted,
   rankAccountsByHeadroom,
+  rankAccountsByResetFirst,
   classifyModelFamilyForQuota,
   type QuotaModelFamily,
 } from "./account-quota-rank";
@@ -351,7 +352,7 @@ export function rotateAntigravityAccountOnAuthRefusal(
 }
 
 /** Generic pool strategies the kernel can actually run. `quota` IS the pre-kernel path. */
-type ActiveGenericStrategy = "round-robin" | "fill-first" | "least-loaded";
+type ActiveGenericStrategy = "round-robin" | "fill-first" | "reset-first" | "least-loaded";
 
 /** Matches the Codex and Anthropic pools; the DTO still reports `null` for "not stored". */
 const DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD = 80;
@@ -365,10 +366,13 @@ const DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD = 80;
  * branch instead of a four-way one.
  */
 function activeGenericStrategy(config: OcxConfig, providerName: string): ActiveGenericStrategy | null {
+  // All pool strategies run behind the kernel flag; `quota` is the pre-kernel path.
+  // Letting `reset-first` bypass it would change 429 selection for pools that never
+  // opted into kernel-gated strategies.
   if (config.pool?.kernel !== true) return null;
   const raw = config.providers?.[providerName]?.oauthAccountFailover?.strategy;
   if (providerName === "kiro" && raw === "least-loaded") return raw;
-  return raw === "round-robin" || raw === "fill-first" ? raw : null;
+  return raw === "round-robin" || raw === "fill-first" || raw === "reset-first" ? raw : null;
 }
 
 function genericStickyLimit(config: OcxConfig, providerName: string): number {
@@ -416,6 +420,7 @@ function pickFillFirstGenericAccount(
   now: number,
   requestedModelId?: string | null,
   accountRows?: ReadonlyMap<string, ProviderAccount>,
+  preferBelowThreshold = false,
 ): string | null {
   const stableAll = stableGenericRoster(providerName);
   if (stableAll.length < 2) return null;
@@ -431,6 +436,11 @@ function pickFillFirstGenericAccount(
   }
   const start = activeId ? stableAll.indexOf(activeId) : -1;
   const ring = start >= 0 ? [...stableAll.slice(start + 1), ...stableAll.slice(0, start)] : stableAll;
+  if (preferBelowThreshold) {
+    const below = ring.find(id => id !== activeId && eligible.has(id)
+      && !isOverAutoSwitchThreshold(providerName, id, threshold, requestedModelId, accountRows?.get(id)));
+    if (below) return below;
+  }
   for (const id of ring) {
     if (id !== activeId && eligible.has(id)) return id;
   }
@@ -574,6 +584,10 @@ export function rotateGenericOAuthAccountOnRefusal(
     }
     return null;
   }
+  if (strategy === "reset-first") {
+    return rankAccountsByResetFirst(providerName, candidates, requestedModelId, now,
+      new Map(set.accounts.map(account => [account.id, account])))[0] ?? null;
+  }
   // With no quota evidence this returns the ring untouched, so providers without
   // per-account quota keep exactly the traversal they have today.
   return rankAccountsByHeadroom(providerName, candidates, requestedModelId,
@@ -634,6 +648,7 @@ export function preferredInitialAccount(
   providerName: string,
   now = Date.now(),
   requestedModelId?: string | null,
+  activeAccountOverride?: string,
 ): string | null {
   // The PROACTIVE predicate, not the reactive one: this steers a request upstream has not
   // refused, so `oauthAccountFailover.enabled: false` must still be able to refuse it.
@@ -642,7 +657,7 @@ export function preferredInitialAccount(
   // active id separately would delay manual selection and account removal.
   const selected = getAccountSet(providerName);
   if (!selected) return null;
-  const active = selected.activeAccountId;
+  const active = activeAccountOverride ?? selected.activeAccountId;
   const accountRows = new Map(selected.accounts.map(account => [account.id, account]));
   const order = selected.accounts
     .filter(account => account.paused !== true && account.needsReauth !== true)
@@ -694,9 +709,20 @@ export function preferredInitialAccount(
     return picked && picked !== active ? picked : null;
   }
   if (strategy === "fill-first") {
-    const picked = pickFillFirstGenericAccount(config, providerName, active, now, requestedModelId, accountRows);
+    const picked = pickFillFirstGenericAccount(config, providerName, active, now, requestedModelId, accountRows, activeAccountOverride !== undefined);
     return picked && picked !== active ? picked : null;
   }
+  if (strategy === "reset-first") {
+    // Same candidate set as round-robin: paused, reauth-needed and cooled accounts are out,
+    // and an account whose model listing omits the requested model loses to one that has it.
+    // Reset ordering needs quota evidence; without it the ordinary active-account path runs.
+    const family = classifyModelFamilyForQuota(providerName, requestedModelId);
+    const eligibleNow = preferKiroModelSupport(providerName,
+      eligibleFailoverAccounts(providerName, now, family), requestedModelId, config);
+    if (eligibleNow.length === 0 || !hasHeadroomEvidence(providerName, eligibleNow, requestedModelId, accountRows)) return null;
+    const best = rankAccountsByResetFirst(providerName, eligibleNow, requestedModelId, now, accountRows)[0] ?? null;
+    return best && best !== active ? best : null;
+  }
 
   const activeRow = selected.accounts.find(account => account.id === active);
   if (activeRow && activeRow.paused !== true && activeRow.needsReauth !== true

package/src/oauth/generic-session-affinity.ts

@@ -0,0 +1,125 @@
+/** Request-local conversation ownership for opt-in generic OAuth pools. No credentials are retained. */
+import { createHash } from "node:crypto";
+import { getConfigDir } from "../config/paths";
+import { subscribeAccountSelections } from "../lib/account-selection-events";
+import type { OcxConfig } from "../types";
+import { classifyModelFamilyForQuota } from "./account-quota-rank";
+import { eligibleFailoverAccounts, isGenericFailoverProvider, preferKiroModelSupport, preferredInitialAccount } from "./generic-account-failover";
+import type { OAuthAccessSnapshot } from "./index";
+import { captureOAuthAccountSelection, credentialGeneration, getAccountCredentialWithStatus } from "./store";
+import type { OAuthAccountSelection } from "./types";
+
+const IDLE_TTL_MS = 24 * 60 * 60_000;
+const MAX_ENTRIES = 2_000;
+const bindings = new Map<string, { accountId: string; lastUsedAt: number; selection: OAuthAccountSelection }>();
+const prefix = (provider: string) => `${JSON.stringify([getConfigDir(), provider])}\u0000`;
+const key = (provider: string, session: string) => prefix(provider) + "session:" + createHash("sha256").update(session).digest("hex");
+const cursorKey = (provider: string) => prefix(provider) + "fill-first";
+
+/** A persisted operator/roster/policy change revokes old session choices before its writer returns. */
+export function clearGenericSessionAffinity(provider?: string): void {
+  if (!provider) { bindings.clear(); return; }
+  const scope = prefix(provider);
+  for (const id of bindings.keys()) if (id.startsWith(scope)) bindings.delete(id);
+}
+subscribeAccountSelections(event => { if (event.kind === "oauth") clearGenericSessionAffinity(event.provider); });
+
+/** Unlike new-session strategy selection, keeping the surviving account needs no 2+ quorum. */
+export function genericSessionAffinityEnabled(config: OcxConfig, provider: string): boolean {
+  const row = config.providers[provider];
+  const enabled = !!row && row.disabled !== true && provider !== "anthropic2" && isGenericFailoverProvider(provider, row)
+    && row.oauthAccountFailover?.sessionAffinity === "conversation"
+    && (row.oauthAccountFailover.enabled ?? config.oauthAccountFailover?.enabled) === true;
+  if (!enabled) clearGenericSessionAffinity(provider);
+  return enabled;
+}
+
+export function genericSessionAccountEligible(
+  config: OcxConfig, provider: string, accountId: string, model?: string | null, now = Date.now(), allowActiveFallback = false,
+): boolean {
+  const eligible = eligibleFailoverAccounts(provider, now, classifyModelFamilyForQuota(provider, model));
+  // Existing conversation ownership is independent of transient per-account load.
+  if (preferKiroModelSupport(provider, eligible, model).includes(accountId)) return true;
+  // Cached automatic exclusions remain preferences when no alternative exists. Preserve the
+  // ordinary active/singleton attempt and its upstream refusal instead of inventing a conflict.
+  if (!allowActiveFallback || eligible.length > 0 || captureOAuthAccountSelection(provider)?.accountId !== accountId) return false;
+  const row = getAccountCredentialWithStatus(provider, accountId);
+  return !!row && !row.paused && !row.needsReauth;
+}
+
+/** Peek only. The admitted snapshot, never a speculative token lookup, establishes ownership. */
+export function genericSessionAccount(
+  config: OcxConfig, provider: string, session: string | null, model?: string | null, now = Date.now(),
+): string | null {
+  if (!genericSessionAffinityEnabled(config, provider) || !session) return null;
+  return readBinding(config, provider, key(provider, session), model, now);
+}
+
+function readBinding(config: OcxConfig, provider: string, id: string, model: string | null | undefined, now: number): string | null {
+  const bound = bindings.get(id);
+  if (!bound) return null;
+  const current = captureOAuthAccountSelection(provider);
+  if (!current || current.accountId !== bound.selection.accountId || current.revision !== bound.selection.revision
+    || now - bound.lastUsedAt >= IDLE_TTL_MS || now < bound.lastUsedAt
+    || !genericSessionAccountEligible(config, provider, bound.accountId, model, now)) {
+    bindings.delete(id);
+    return null;
+  }
+  return bound.accountId;
+}
+
+/** New sessions use the configured strategy; an ineligible active account cannot defeat release. */
+export function preferredGenericSessionAccount(
+  config: OcxConfig, provider: string, session: string | null, model?: string | null, now = Date.now(),
+): string | null {
+  if (!genericSessionAffinityEnabled(config, provider)) return null;
+  const bound = genericSessionAccount(config, provider, session, model, now);
+  if (bound) return bound;
+  const cursor = readBinding(config, provider, cursorKey(provider), model, now);
+  const active = cursor ?? captureOAuthAccountSelection(provider)?.accountId;
+  const preferred = preferredInitialAccount(config, provider, now, model, active);
+  if (preferred) return preferred;
+  if (active && genericSessionAccountEligible(config, provider, active, model, now)) return active;
+  return preferKiroModelSupport(provider,
+    eligibleFailoverAccounts(provider, now, classifyModelFamilyForQuota(provider, model)), model, config)[0]
+    ?? captureOAuthAccountSelection(provider)?.accountId ?? null;
+}
+
+/**
+ * Validate against the operator's persisted selection without moving it. ALL automatic choices
+ * in affinity mode use this receipt, including unkeyed requests and failovers, so concurrent
+ * conversations cannot invalidate each other's selection revision. Manual A→B→A still fences.
+ */
+export function admitGenericSessionAccount(
+  config: OcxConfig, provider: string, expected: OAuthAccountSelection,
+  snapshot: OAuthAccessSnapshot, model?: string | null, modeEnabled = genericSessionAffinityEnabled(config, provider),
+): OAuthAccountSelection | null {
+  if (!modeEnabled || snapshot.provider !== provider) return null;
+  const current = captureOAuthAccountSelection(provider);
+  if (!current || current.accountId !== expected.accountId || current.revision !== expected.revision) return null;
+  const row = getAccountCredentialWithStatus(provider, snapshot.accountId);
+  if (!row || row.paused || row.needsReauth || credentialGeneration(row.credential) !== snapshot.generation
+    || !genericSessionAccountEligible(config, provider, snapshot.accountId, model, Date.now(), true)) return null;
+  return current;
+}
+
+export function bindGenericSessionAccount(
+  config: OcxConfig, provider: string, session: string | null, accountId: string, model?: string | null, now = Date.now(),
+): void {
+  if (!genericSessionAffinityEnabled(config, provider)
+    || !genericSessionAccountEligible(config, provider, accountId, model, now)) return;
+  for (const [id, entry] of bindings) {
+    if (now - entry.lastUsedAt >= IDLE_TTL_MS || now < entry.lastUsedAt) bindings.delete(id);
+  }
+  const selection = captureOAuthAccountSelection(provider);
+  if (!selection) return;
+  const keep = (id: string) => {
+    bindings.delete(id);
+    bindings.set(id, { accountId, lastUsedAt: now, selection });
+  };
+  const hit = session && genericSessionAccount(config, provider, session, model, now) === accountId;
+  if (!hit && config.pool?.kernel === true && config.providers[provider]?.oauthAccountFailover?.strategy === "fill-first")
+    keep(cursorKey(provider));
+  if (session) keep(key(provider, session));
+  while (bindings.size > MAX_ENTRIES) bindings.delete(bindings.keys().next().value!);
+}