Merge pull request #1117 from kaitranntt/kai/feat/1115-session-affinity

feat: add local CLIProxy session affinity controls

docs/project-roadmap.md

@@ -1,6 +1,6 @@
 # CCS Project Roadmap
 
-Last Updated: 2026-04-21
+Last Updated: 2026-04-28
 
 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
 
@@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 ### Recent Fixes
 
+- **2026-04-28**: **#1115** CCS now exposes upstream CLIProxy session affinity as a first-class local managed setting. Users can inspect and toggle local `session-affinity` plus TTL from `ccs cliproxy routing affinity`, from the `/cliproxy` dashboard routing card, and through the local dashboard API. The generated local CLIProxy config now persists `routing.session-affinity` and `routing.session-affinity-ttl`, help/copy explains that CLIProxy prefers explicit session or thread identifiers before falling back to prompt-history hashing, and remote session-affinity management stays explicitly unsupported until upstream management APIs expose more than `routing.strategy`.
 - **2026-04-24**: **#1065** Local CLIProxy Plus is available again as an explicit opt-in backend through the community-maintained `kaitranntt/CLIProxyAPIPlus` fork. CCS keeps `original` as the default backend, no longer downgrades saved `backend: plus` configs to `original`, updates Plus release lookups to the maintained fork, and documents Plus as a targeted path for plus-only providers.
 - **2026-04-21**: CLIProxy quota failover now quarantines exhausted Claude and Antigravity accounts out of live rotation when a healthy fallback exists. CCS persists those quota-triggered pauses across launches, automatically resumes them after the configured cooldown window, and deliberately avoids auto-pausing the last available account so single-account setups still degrade gracefully instead of hard-locking themselves.
 - **2026-04-20**: **#1051** Browser automation now defaults safe-off for new installs and upgrades that do not already carry explicit browser settings. CCS changes both Claude Browser Attach and Codex Browser Tools to start with `enabled: false` and `policy: manual`, normalizes missing browser policies on upgrade back to `manual`, preserves explicit existing enablement, and updates status/help/docs so browser tooling is never implied to auto-expose unless users opt in.

src/cliproxy/config/generator.ts

@@ -40,8 +40,9 @@ export const CCS_CONTROL_PANEL_SECRET = 'ccs';
  * v15: Prune stale generated Antigravity Gemini preview aliases during regeneration
  * v16: Narrow stale Gemini alias cleanup to broad multi-version guessed ranges
  * v17: Persist routing.strategy from CCS unified config
+ * v18: Persist routing.session-affinity and routing.session-affinity-ttl from CCS unified config
  */
-export const CLIPROXY_CONFIG_VERSION = 17;
+export const CLIPROXY_CONFIG_VERSION = 18;
 
 interface RegenerateConfigOptions {
   configPath?: string;
@@ -98,6 +99,8 @@ const MIN_STALE_HIGH_ONLY_GEMINI_MINOR_VERSIONS = 3;
 const MIN_STALE_GUESSED_GEMINI_AVERAGE_VARIANTS_PER_MINOR = 2;
 const LEGACY_GEMINI_STALE_ALIAS_MIGRATION_VERSION = 16;
 const MAX_LEGACY_MANUAL_GEMINI_MINOR_VERSION = 2;
+const GO_DURATION_SEGMENT = String.raw`(?:\d+(?:\.\d+)?(?:ns|us|µs|μs|ms|s|m|h))`;
+const GO_DURATION_PATTERN = new RegExp(`^${GO_DURATION_SEGMENT}+$`);
 
 /**
  * Get provider configuration
@@ -132,6 +135,27 @@ function getRoutingStrategy(): 'round-robin' | 'fill-first' {
   return config.cliproxy?.routing?.strategy === 'fill-first' ? 'fill-first' : 'round-robin';
 }
 
+function getSessionAffinityEnabled(): boolean {
+  return loadOrCreateUnifiedConfig().cliproxy?.routing?.session_affinity ?? false;
+}
+
+function getSessionAffinityTtl(): string {
+  const ttl = loadOrCreateUnifiedConfig().cliproxy?.routing?.session_affinity_ttl?.trim();
+  return ttl && GO_DURATION_PATTERN.test(ttl) && hasPositiveDuration(ttl) ? ttl : '1h';
+}
+
+function hasPositiveDuration(value: string): boolean {
+  const segments = value.match(new RegExp(GO_DURATION_SEGMENT, 'g'));
+  if (!segments) {
+    return false;
+  }
+
+  return segments.some((segment) => {
+    const numeric = parseFloat(segment);
+    return Number.isFinite(numeric) && numeric > 0;
+  });
+}
+
 function sanitizeYamlScalar(rawValue: string): string {
   const trimmed = rawValue.trim();
   if (
@@ -552,6 +576,8 @@ function generateUnifiedConfigContent(
   // Get logging settings from user config (disabled by default)
   const { loggingToFile, requestLog } = getLoggingSettings();
   const routingStrategy = getRoutingStrategy();
+  const sessionAffinityEnabled = getSessionAffinityEnabled();
+  const sessionAffinityTtl = getSessionAffinityTtl();
 
   // Get effective auth tokens (respects user customization)
   const effectiveApiKey = getEffectiveApiKey();
@@ -627,6 +653,8 @@ quota-exceeded:
 # Credential selection strategy when multiple matching accounts are available
 routing:
   strategy: ${routingStrategy}
+  session-affinity: ${sessionAffinityEnabled}
+  session-affinity-ttl: "${sessionAffinityTtl}"
 
 # =============================================================================
 # Authentication

src/cliproxy/routing-strategy.ts

@@ -9,6 +9,11 @@ import {
 import type { CliproxyRoutingStrategy } from './types';
 
 export const DEFAULT_CLIPROXY_ROUTING_STRATEGY: CliproxyRoutingStrategy = 'round-robin';
+export const DEFAULT_CLIPROXY_SESSION_AFFINITY_ENABLED = false;
+export const DEFAULT_CLIPROXY_SESSION_AFFINITY_TTL = '1h';
+
+const GO_DURATION_SEGMENT = String.raw`(?:\d+(?:\.\d+)?(?:ns|us|µs|μs|ms|s|m|h))`;
+const GO_DURATION_PATTERN = new RegExp(`^${GO_DURATION_SEGMENT}+$`);
 
 export interface CliproxyRoutingState {
   strategy: CliproxyRoutingStrategy;
@@ -22,6 +27,25 @@ export interface CliproxyRoutingApplyResult extends CliproxyRoutingState {
   applied: 'live' | 'live-and-config' | 'config-only';
 }
 
+export interface CliproxySessionAffinitySettings {
+  enabled: boolean;
+  ttl?: string;
+}
+
+export interface CliproxySessionAffinityState {
+  enabled?: boolean;
+  ttl?: string;
+  source: 'config' | 'unsupported';
+  target: 'local' | 'remote';
+  reachable: boolean;
+  manageable: boolean;
+  message?: string;
+}
+
+export interface CliproxySessionAffinityApplyResult extends CliproxySessionAffinityState {
+  applied: 'config-only' | 'unsupported';
+}
+
 export function normalizeCliproxyRoutingStrategy(value: unknown): CliproxyRoutingStrategy | null {
   if (typeof value !== 'string') {
     return null;
@@ -41,6 +65,47 @@ export function normalizeCliproxyRoutingStrategy(value: unknown): CliproxyRoutin
   }
 }
 
+export function normalizeCliproxySessionAffinityEnabled(value: unknown): boolean | null {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  switch (value.trim().toLowerCase()) {
+    case 'true':
+    case '1':
+    case 'yes':
+    case 'on':
+    case 'enable':
+    case 'enabled':
+      return true;
+    case 'false':
+    case '0':
+    case 'no':
+    case 'off':
+    case 'disable':
+    case 'disabled':
+      return false;
+    default:
+      return null;
+  }
+}
+
+export function normalizeCliproxySessionAffinityTtl(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed || !GO_DURATION_PATTERN.test(trimmed) || !hasPositiveDuration(trimmed)) {
+    return null;
+  }
+
+  return trimmed;
+}
+
 export function getConfiguredCliproxyRoutingStrategy(): CliproxyRoutingStrategy {
   return (
     normalizeCliproxyRoutingStrategy(loadOrCreateUnifiedConfig().cliproxy?.routing?.strategy) ??
@@ -48,6 +113,18 @@ export function getConfiguredCliproxyRoutingStrategy(): CliproxyRoutingStrategy
   );
 }
 
+export function getConfiguredCliproxySessionAffinitySettings(): Required<CliproxySessionAffinitySettings> {
+  const routing = loadOrCreateUnifiedConfig().cliproxy?.routing;
+  return {
+    enabled:
+      normalizeCliproxySessionAffinityEnabled(routing?.session_affinity) ??
+      DEFAULT_CLIPROXY_SESSION_AFFINITY_ENABLED,
+    ttl:
+      normalizeCliproxySessionAffinityTtl(routing?.session_affinity_ttl) ??
+      DEFAULT_CLIPROXY_SESSION_AFFINITY_TTL,
+  };
+}
+
 export async function fetchLiveCliproxyRoutingStrategy(): Promise<CliproxyRoutingStrategy> {
   const response = await fetchCliproxyRoutingResponse(getCliproxyRoutingTarget(), 'GET');
   if (!response.ok) {
@@ -95,6 +172,38 @@ export async function readCliproxyRoutingState(): Promise<CliproxyRoutingState>
   }
 }
 
+export async function readCliproxySessionAffinityState(): Promise<CliproxySessionAffinityState> {
+  const target = getCliproxyRoutingTarget();
+
+  if (target.isRemote) {
+    const reachable = await isLiveCliproxyRoutingReachable();
+    return {
+      source: 'unsupported',
+      target: 'remote',
+      reachable,
+      manageable: false,
+      message: reachable
+        ? 'Remote session-affinity management is not supported from CCS yet because upstream management APIs only expose routing.strategy.'
+        : 'Remote session-affinity management is not supported from CCS yet, and the remote CLIProxy routing endpoint is not reachable.',
+    };
+  }
+
+  const settings = getConfiguredCliproxySessionAffinitySettings();
+  const reachable = await isLiveCliproxyRoutingReachable();
+
+  return {
+    enabled: settings.enabled,
+    ttl: settings.ttl,
+    source: 'config',
+    target: 'local',
+    reachable,
+    manageable: true,
+    message: reachable
+      ? 'Showing the saved local session-affinity setting. Running local CLIProxy may hot-reload config changes, but CCS does not verify live selector state.'
+      : 'Local CLIProxy is not reachable. Showing the saved local startup default.',
+  };
+}
+
 export async function applyCliproxyRoutingStrategy(
   strategy: CliproxyRoutingStrategy
 ): Promise<CliproxyRoutingApplyResult> {
@@ -116,7 +225,7 @@ export async function applyCliproxyRoutingStrategy(
 
   mutateUnifiedConfig((config) => {
     if (config.cliproxy) {
-      config.cliproxy.routing = { strategy };
+      config.cliproxy.routing = { ...config.cliproxy.routing, strategy };
     }
   });
   regenerateConfig(target.port, { configPath, authDir });
@@ -143,6 +252,58 @@ export async function applyCliproxyRoutingStrategy(
   }
 }
 
+export async function applyCliproxySessionAffinitySettings(
+  settings: CliproxySessionAffinitySettings
+): Promise<CliproxySessionAffinityApplyResult> {
+  const target = getCliproxyRoutingTarget();
+  if (target.isRemote) {
+    const reachable = await isLiveCliproxyRoutingReachable();
+    return {
+      source: 'unsupported',
+      target: 'remote',
+      reachable,
+      manageable: false,
+      applied: 'unsupported',
+      message: reachable
+        ? 'Remote session-affinity management is not supported from CCS yet because upstream management APIs only expose routing.strategy.'
+        : 'Remote session-affinity management is not supported from CCS yet, and the remote CLIProxy routing endpoint is not reachable.',
+    };
+  }
+
+  const configPath = getConfigPathForPort(target.port);
+  const authDir = getAuthDir();
+  const current = getConfiguredCliproxySessionAffinitySettings();
+  const ttl =
+    normalizeCliproxySessionAffinityTtl(settings.ttl) ??
+    current.ttl ??
+    DEFAULT_CLIPROXY_SESSION_AFFINITY_TTL;
+
+  mutateUnifiedConfig((config) => {
+    if (config.cliproxy) {
+      config.cliproxy.routing = {
+        ...config.cliproxy.routing,
+        session_affinity: settings.enabled,
+        session_affinity_ttl: ttl,
+      };
+    }
+  });
+  regenerateConfig(target.port, { configPath, authDir });
+
+  const reachable = await isLiveCliproxyRoutingReachable();
+  return {
+    enabled: settings.enabled,
+    ttl,
+    source: 'config',
+    target: 'local',
+    reachable,
+    manageable: true,
+    applied: 'config-only',
+    message: reachable
+      ? 'Saved the local startup default. Running local CLIProxy may hot-reload the session-affinity setting, but CCS does not verify live selector state yet.'
+      : 'Saved the local startup default. It will apply the next time local CLIProxy starts.',
+  };
+}
+
 async function updateLiveCliproxyRoutingStrategy(strategy: CliproxyRoutingStrategy): Promise<void> {
   const response = await fetchCliproxyRoutingResponse(getCliproxyRoutingTarget(), 'PUT', {
     value: strategy,
@@ -156,3 +317,24 @@ async function updateLiveCliproxyRoutingStrategy(strategy: CliproxyRoutingStrate
     );
   }
 }
+
+function hasPositiveDuration(value: string): boolean {
+  const segments = value.match(new RegExp(GO_DURATION_SEGMENT, 'g'));
+  if (!segments) {
+    return false;
+  }
+
+  return segments.some((segment) => {
+    const numeric = parseFloat(segment);
+    return Number.isFinite(numeric) && numeric > 0;
+  });
+}
+
+async function isLiveCliproxyRoutingReachable(): Promise<boolean> {
+  try {
+    await fetchLiveCliproxyRoutingStrategy();
+    return true;
+  } catch {
+    return false;
+  }
+}

src/cliproxy/types.ts

@@ -194,6 +194,9 @@ export interface CLIProxyConfig {
   debug: boolean;
   routing?: {
     strategy?: CliproxyRoutingStrategy;
+    'session-affinity'?: boolean;
+    'session-affinity-ttl'?: string;
+    'claude-code-session-affinity'?: boolean;
   };
   'gemini-api-key'?: Array<{
     'api-key': string;

src/commands/cliproxy/help-subcommand.ts

@@ -59,8 +59,10 @@ export async function showHelp(): Promise<void> {
         ['quota', 'Show quota status for all providers (Codex/Claude include 5h + weekly reset)'],
         ['quota --provider <name>', `Filter by provider (${QUOTA_PROVIDER_HELP_TEXT})`],
         ['routing', 'Show current routing strategy and manual guidance'],
-        ['routing explain', 'Explain round-robin vs fill-first'],
+        ['routing explain', 'Explain strategy vs session-affinity and how sessions are recognized'],
         ['routing set <mode>', 'Explicitly set round-robin or fill-first'],
+        ['routing affinity', 'Show local session-affinity status and TTL'],
+        ['routing affinity <on|off> [--ttl <duration>]', 'Toggle local session-affinity settings'],
       ],
     ],
     [

src/commands/cliproxy/index.ts

@@ -34,7 +34,14 @@ import {
 } from './proxy-lifecycle-subcommand';
 import { showStatus, handleInstallVersion, handleInstallLatest } from './install-subcommand';
 import { showHelp } from './help-subcommand';
-import { handleRoutingStatus, handleRoutingExplain, handleRoutingSet } from './routing-subcommand';
+import {
+  handleRoutingStatus,
+  handleRoutingExplain,
+  handleRoutingSet,
+  handleRoutingAffinityStatus,
+  handleRoutingAffinityHelp,
+  handleRoutingAffinitySet,
+} from './routing-subcommand';
 import {
   handleCatalogStatus,
   handleCatalogRefresh,
@@ -189,6 +196,18 @@ export async function handleCliproxyCommand(args: string[]): Promise<void> {
       await handleRoutingExplain();
       return;
     }
+    if (subcommand === 'affinity') {
+      if (hasAnyFlag(remainingArgs.slice(2), ['--help', '-h'])) {
+        await handleRoutingAffinityHelp();
+        return;
+      }
+      if (remainingArgs[2]) {
+        await handleRoutingAffinitySet(remainingArgs.slice(2));
+        return;
+      }
+      await handleRoutingAffinityStatus();
+      return;
+    }
     await handleRoutingStatus();
     return;
   }

src/commands/cliproxy/routing-subcommand.ts

@@ -1,8 +1,13 @@
 import { initUI, header, subheader, color, dim, ok, fail, infoBox } from '../../utils/ui';
+import { extractOption } from '../arg-extractor';
 import {
   applyCliproxyRoutingStrategy,
+  applyCliproxySessionAffinitySettings,
   normalizeCliproxyRoutingStrategy,
+  normalizeCliproxySessionAffinityEnabled,
+  normalizeCliproxySessionAffinityTtl,
   readCliproxyRoutingState,
+  readCliproxySessionAffinityState,
 } from '../../cliproxy/routing-strategy';
 
 function printStrategyGuide(): void {
@@ -23,13 +28,52 @@ function printStrategyGuide(): void {
   console.log('');
 }
 
+function printSessionAffinityGuide(): void {
+  console.log(subheader('Session Affinity:'));
+  console.log(
+    `  ${color('session-affinity off', 'command')} Each request follows the base routing strategy.`
+  );
+  console.log(`  ${dim('    Best when you want pure proxy-wide balancing behavior.')}`);
+  console.log('');
+  console.log(
+    `  ${color('session-affinity on', 'command')} Keep one conversation pinned to the same account when possible.`
+  );
+  console.log(
+    `  ${dim('    Best when you want stronger prompt-cache locality for a single conversation.')}`
+  );
+  console.log('');
+}
+
+function printSessionRecognitionGuide(): void {
+  console.log(subheader('How CLIProxy Knows A Session Is New:'));
+  console.log(
+    `  ${dim('  CLIProxy prefers explicit session or thread identifiers when clients send them.')}`
+  );
+  console.log(
+    `  ${dim('  Common examples: Claude session UUIDs, X-Session-ID, or provider-specific thread ids.')}`
+  );
+  console.log(
+    `  ${dim('  If no explicit identifier is present, it can fall back to fields such as metadata.user_id or conversation_id.')}`
+  );
+  console.log(
+    `  ${dim('  Last resort: it derives a stable key from the opening prompt history.')}`
+  );
+  console.log(
+    `  ${dim('  Exact precedence can vary by upstream backend/runtime version, so CCS does not promise one universal order.')}`
+  );
+  console.log('');
+}
+
 export async function handleRoutingStatus(): Promise<void> {
   await initUI();
   console.log('');
   console.log(header('CLIProxy Routing Strategy'));
   console.log('');
 
-  const state = await readCliproxyRoutingState();
+  const [state, sessionAffinity] = await Promise.all([
+    readCliproxyRoutingState(),
+    readCliproxySessionAffinityState(),
+  ]);
   console.log(`  Current: ${color(state.strategy, 'command')}`);
   console.log(`  Target:  ${color(state.target, 'info')}`);
   console.log(
@@ -39,8 +83,28 @@ export async function handleRoutingStatus(): Promise<void> {
     console.log('');
     console.log(infoBox(state.message, state.reachable ? 'INFO' : 'WARNING'));
   }
+  console.log(
+    `  Session Affinity: ${
+      sessionAffinity.manageable
+        ? color(sessionAffinity.enabled ? 'on' : 'off', 'command')
+        : color('unsupported', 'warning')
+    }`
+  );
+  if (sessionAffinity.ttl) {
+    console.log(`  Affinity TTL: ${color(sessionAffinity.ttl, 'info')}`);
+  }
+  if (sessionAffinity.message) {
+    console.log('');
+    console.log(
+      infoBox(
+        sessionAffinity.message,
+        sessionAffinity.manageable && sessionAffinity.reachable ? 'INFO' : 'WARNING'
+      )
+    );
+  }
   console.log('');
   printStrategyGuide();
+  printSessionAffinityGuide();
 }
 
 export async function handleRoutingExplain(): Promise<void> {
@@ -49,6 +113,8 @@ export async function handleRoutingExplain(): Promise<void> {
   console.log(header('CLIProxy Routing Guide'));
   console.log('');
   printStrategyGuide();
+  printSessionAffinityGuide();
+  printSessionRecognitionGuide();
 }
 
 export async function handleRoutingSet(args: string[]): Promise<void> {
@@ -78,3 +144,105 @@ export async function handleRoutingSet(args: string[]): Promise<void> {
   }
   console.log('');
 }
+
+export async function handleRoutingAffinityStatus(): Promise<void> {
+  await initUI();
+  console.log('');
+  console.log(header('CLIProxy Session Affinity'));
+  console.log('');
+
+  const state = await readCliproxySessionAffinityState();
+  if (!state.manageable) {
+    console.log(`  Status: ${color('unsupported', 'warning')}`);
+  } else {
+    console.log(`  Status: ${color(state.enabled ? 'on' : 'off', 'command')}`);
+  }
+  console.log(
+    `  Source: ${state.manageable ? color('saved local setting', 'info') : color('unsupported', 'warning')}`
+  );
+  console.log(`  Target: ${color(state.target, 'info')}`);
+  if (state.ttl) {
+    console.log(`  TTL:    ${color(state.ttl, 'info')}`);
+  }
+  if (state.message) {
+    console.log('');
+    console.log(infoBox(state.message, state.manageable && state.reachable ? 'INFO' : 'WARNING'));
+  }
+  console.log('');
+  printSessionAffinityGuide();
+  printSessionRecognitionGuide();
+}
+
+export async function handleRoutingAffinityHelp(): Promise<void> {
+  await initUI();
+  console.log('');
+  console.log(header('CLIProxy Session Affinity'));
+  console.log('');
+  console.log(subheader('Usage:'));
+  console.log(`  ${color('ccs cliproxy routing affinity', 'command')}`);
+  console.log(`  ${color('ccs cliproxy routing affinity on', 'command')}`);
+  console.log(`  ${color('ccs cliproxy routing affinity off', 'command')}`);
+  console.log(`  ${color('ccs cliproxy routing affinity on --ttl 1h', 'command')}`);
+  console.log('');
+  printSessionAffinityGuide();
+  console.log(`  ${dim('Accepted TTL examples: 30m, 1h, 2h30m')}`);
+  console.log('');
+  printSessionRecognitionGuide();
+}
+
+export async function handleRoutingAffinitySet(args: string[]): Promise<void> {
+  const requested = normalizeCliproxySessionAffinityEnabled(args[0]);
+  const extractedTtl = extractOption(args.slice(1), ['--ttl']);
+  const remainingArgs = extractedTtl.remainingArgs.filter((token) => token.trim().length > 0);
+  const ttl: string | undefined =
+    extractedTtl.found && !extractedTtl.missingValue
+      ? (normalizeCliproxySessionAffinityTtl(extractedTtl.value) ?? undefined)
+      : undefined;
+
+  if (
+    requested === null ||
+    extractedTtl.missingValue ||
+    (extractedTtl.found && !ttl) ||
+    remainingArgs.length > 0
+  ) {
+    await initUI();
+    console.log('');
+    console.log(
+      fail('Invalid session affinity command. Use: routing affinity <on|off> [--ttl 1h]')
+    );
+    console.log('');
+    printSessionAffinityGuide();
+    console.log(`  ${dim('Accepted TTL examples: 30m, 1h, 2h30m')}`);
+    console.log('');
+    process.exitCode = 1;
+    return;
+  }
+
+  await initUI();
+  console.log('');
+  console.log(header('Update CLIProxy Session Affinity'));
+  console.log('');
+
+  const result = await applyCliproxySessionAffinitySettings({
+    enabled: requested,
+    ttl,
+  });
+
+  if (!result.manageable) {
+    console.log(fail(result.message || 'Session affinity is not supported for this target.'));
+    console.log('');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(ok(`Session affinity ${requested ? 'enabled' : 'disabled'}`));
+  if (result.ttl) {
+    console.log(`  TTL:     ${color(result.ttl, 'info')}`);
+  }
+  console.log(`  Applied: ${color(result.applied, 'info')}`);
+  if (result.message) {
+    console.log('');
+    console.log(infoBox(result.message, result.reachable ? 'SUCCESS' : 'INFO'));
+  }
+  console.log('');
+}

src/commands/completion-backend.ts

@@ -168,10 +168,27 @@ function getSuggestionsForCommand(tokensBeforeCurrent: string[]): CompletionSugg
           '-h',
         ]);
       if (subcommand === 'routing') {
+        const routingSubcommand = tokensBeforeCurrent[2];
+        const routingAffinityMode = tokensBeforeCurrent[3];
         if (lastToken === 'set') {
           return completeSubcommands(['round-robin', 'fill-first']);
         }
-        return completeSubcommands(['set', 'explain']);
+        if (routingSubcommand === 'affinity') {
+          if (!routingAffinityMode || lastToken === 'affinity') {
+            return completeSubcommands(['on', 'off']);
+          }
+          if (
+            (routingAffinityMode === 'on' || routingAffinityMode === 'off') &&
+            !tokensBeforeCurrent.includes('--ttl')
+          ) {
+            return completeSubcommands([], ['--ttl']);
+          }
+          if (lastToken === '--ttl') {
+            return [];
+          }
+          return completeSubcommands([]);
+        }
+        return completeSubcommands(['set', 'explain', 'affinity']);
       }
       if (['remove', 'edit'].includes(subcommand)) {
         return completeSubcommands(getProfileNames('cliproxyVariants'), ['--yes', '-y']);

src/config/unified-config-loader.ts

@@ -59,6 +59,8 @@ const CONFIG_YAML = 'config.yaml';
 const CONFIG_JSON = 'config.json';
 const CONFIG_LOCK = 'config.yaml.lock';
 const LOCK_STALE_MS = 5000; // Lock is stale after 5 seconds
+const GO_DURATION_SEGMENT = String.raw`(?:\d+(?:\.\d+)?(?:ns|us|µs|μs|ms|s|m|h))`;
+const GO_DURATION_PATTERN = new RegExp(`^${GO_DURATION_SEGMENT}+$`);
 
 function normalizeBrowserDevtoolsPort(value: number | undefined): number {
   if (!Number.isFinite(value)) {
@@ -112,6 +114,31 @@ function canonicalizeBrowserConfig(
   };
 }
 
+function normalizeSessionAffinityTtl(value: unknown, fallback: string): string {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed || !GO_DURATION_PATTERN.test(trimmed) || !hasPositiveDuration(trimmed)) {
+    return fallback;
+  }
+
+  return trimmed;
+}
+
+function hasPositiveDuration(value: string): boolean {
+  const segments = value.match(new RegExp(GO_DURATION_SEGMENT, 'g'));
+  if (!segments) {
+    return false;
+  }
+
+  return segments.some((segment) => {
+    const numeric = parseFloat(segment);
+    return Number.isFinite(numeric) && numeric > 0;
+  });
+}
+
 /**
  * Get path to unified config.yaml
  */
@@ -440,6 +467,14 @@ function mergeWithDefaults(partial: Partial<UnifiedConfig>): UnifiedConfig {
           partial.cliproxy?.routing?.strategy === 'round-robin'
             ? partial.cliproxy.routing.strategy
             : defaults.cliproxy.routing?.strategy,
+        session_affinity:
+          typeof partial.cliproxy?.routing?.session_affinity === 'boolean'
+            ? partial.cliproxy.routing.session_affinity
+            : defaults.cliproxy.routing?.session_affinity,
+        session_affinity_ttl: normalizeSessionAffinityTtl(
+          partial.cliproxy?.routing?.session_affinity_ttl,
+          defaults.cliproxy.routing?.session_affinity_ttl ?? '1h'
+        ),
       },
     },
     proxy: {

src/config/unified-config-types.ts

@@ -205,6 +205,10 @@ export interface TokenRefreshSettings {
 export interface CLIProxyRoutingConfig {
   /** Credential selection strategy when multiple accounts match */
   strategy?: CliproxyRoutingStrategy;
+  /** Keep one conversation pinned to the same account when possible */
+  session_affinity?: boolean;
+  /** Go-style duration for session-affinity binding retention */
+  session_affinity_ttl?: string;
 }
 
 /**
@@ -1034,6 +1038,8 @@ export function createEmptyUnifiedConfig(): UnifiedConfig {
       auto_sync: true,
       routing: {
         strategy: 'round-robin',
+        session_affinity: false,
+        session_affinity_ttl: '1h',
       },
     },
     proxy: {

src/web-server/routes/cliproxy-routing-routes.ts

@@ -1,8 +1,12 @@
 import { Router, Request, Response } from 'express';
 import {
   applyCliproxyRoutingStrategy,
+  applyCliproxySessionAffinitySettings,
   normalizeCliproxyRoutingStrategy,
+  normalizeCliproxySessionAffinityEnabled,
+  normalizeCliproxySessionAffinityTtl,
   readCliproxyRoutingState,
+  readCliproxySessionAffinityState,
 } from '../../cliproxy/routing-strategy';
 import { requireLocalAccessWhenAuthDisabled } from '../middleware/auth-middleware';
 
@@ -42,4 +46,42 @@ router.put('/routing/strategy', async (req: Request, res: Response): Promise<voi
   }
 });
 
+router.get('/routing/session-affinity', async (_req: Request, res: Response): Promise<void> => {
+  try {
+    res.json(await readCliproxySessionAffinityState());
+  } catch (error) {
+    res.status(502).json({ error: (error as Error).message });
+  }
+});
+
+router.put('/routing/session-affinity', async (req: Request, res: Response): Promise<void> => {
+  const enabled = normalizeCliproxySessionAffinityEnabled(req.body?.enabled ?? req.body?.value);
+  const ttl = req.body?.ttl;
+  const normalizedTtl: string | undefined =
+    ttl === undefined ? undefined : (normalizeCliproxySessionAffinityTtl(ttl) ?? undefined);
+
+  if (enabled === null || (ttl !== undefined && !normalizedTtl)) {
+    res.status(400).json({
+      error: 'Invalid session affinity payload. Use enabled=true|false and ttl like 30m or 1h.',
+    });
+    return;
+  }
+
+  try {
+    const result = await applyCliproxySessionAffinitySettings({
+      enabled,
+      ttl: normalizedTtl,
+    });
+    if (!result.manageable || result.applied === 'unsupported') {
+      res.status(400).json({
+        error: result.message || 'Session affinity is not supported for this target.',
+      });
+      return;
+    }
+    res.json(result);
+  } catch (error) {
+    res.status(502).json({ error: (error as Error).message });
+  }
+});
+
 export default router;

tests/unit/cliproxy/routing-strategy.test.ts

@@ -151,4 +151,138 @@ describe('cliproxy routing strategy service', () => {
       expect(methodCount).toBe(2);
     });
   });
+
+  it('normalizes session-affinity booleans and TTL values', async () => {
+    await withScopedConfig(async () => {
+      const mod = await loadRoutingModule();
+
+      expect(mod.normalizeCliproxySessionAffinityEnabled(true)).toBe(true);
+      expect(mod.normalizeCliproxySessionAffinityEnabled('on')).toBe(true);
+      expect(mod.normalizeCliproxySessionAffinityEnabled('false')).toBe(false);
+      expect(mod.normalizeCliproxySessionAffinityEnabled('maybe')).toBeNull();
+
+      expect(mod.normalizeCliproxySessionAffinityTtl('1h')).toBe('1h');
+      expect(mod.normalizeCliproxySessionAffinityTtl('2h30m')).toBe('2h30m');
+      expect(mod.normalizeCliproxySessionAffinityTtl('  15m  ')).toBe('15m');
+      expect(mod.normalizeCliproxySessionAffinityTtl('0s')).toBeNull();
+      expect(mod.normalizeCliproxySessionAffinityTtl('tomorrow')).toBeNull();
+    });
+  });
+
+  it('reads saved local session-affinity settings when live CLIProxy is unavailable', async () => {
+    await withScopedConfig(async () => {
+      const { mutateUnifiedConfig } = await import('../../../src/config/unified-config-loader');
+      mutateUnifiedConfig((config) => {
+        if (config.cliproxy) {
+          config.cliproxy.routing = {
+            strategy: 'round-robin',
+            session_affinity: true,
+            session_affinity_ttl: '2h30m',
+          };
+        }
+      });
+
+      const mod = await loadRoutingModule();
+      const state = await mod.readCliproxySessionAffinityState();
+
+      expect(state.enabled).toBe(true);
+      expect(state.ttl).toBe('2h30m');
+      expect(state.source).toBe('config');
+      expect(state.target).toBe('local');
+      expect(state.manageable).toBe(true);
+      expect(state.reachable).toBe(false);
+    });
+  });
+
+  it('persists local session-affinity settings even when live CLIProxy is unavailable', async () => {
+    await withScopedConfig(async () => {
+      const mod = await loadRoutingModule();
+      const result = await mod.applyCliproxySessionAffinitySettings({
+        enabled: true,
+        ttl: '2h',
+      });
+
+      expect(result.applied).toBe('config-only');
+      expect(result.enabled).toBe(true);
+      expect(result.ttl).toBe('2h');
+
+      const { loadUnifiedConfig } = await import('../../../src/config/unified-config-loader');
+      const persisted = loadUnifiedConfig();
+      expect(persisted?.cliproxy?.routing?.session_affinity).toBe(true);
+      expect(persisted?.cliproxy?.routing?.session_affinity_ttl).toBe('2h');
+    });
+  });
+
+  it('does not claim live session-affinity application just because local CLIProxy is reachable', async () => {
+    await withScopedConfig(async () => {
+      responseFactory = async () =>
+        new Response(JSON.stringify({ strategy: 'round-robin' }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+
+      const mod = await loadRoutingModule();
+      const result = await mod.applyCliproxySessionAffinitySettings({
+        enabled: true,
+        ttl: '30m',
+      });
+
+      expect(result.reachable).toBe(true);
+      expect(result.applied).toBe('config-only');
+      expect(result.message).toContain('does not verify live selector state yet');
+    });
+  });
+
+  it('reports remote session-affinity management as unsupported', async () => {
+    await withScopedConfig(async () => {
+      routingTarget = {
+        host: 'remote.example.com',
+        port: 8080,
+        protocol: 'http',
+        isRemote: true,
+      };
+
+      responseFactory = async () =>
+        new Response(JSON.stringify({ strategy: 'round-robin' }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+
+      const mod = await loadRoutingModule();
+      const state = await mod.readCliproxySessionAffinityState();
+
+      expect(state.source).toBe('unsupported');
+      expect(state.target).toBe('remote');
+      expect(state.manageable).toBe(false);
+      expect(state.reachable).toBe(true);
+      expect(state.enabled).toBeUndefined();
+
+      const result = await mod.applyCliproxySessionAffinitySettings({
+        enabled: true,
+        ttl: '1h',
+      });
+
+      expect(result.applied).toBe('unsupported');
+      expect(result.manageable).toBe(false);
+    });
+  });
+
+  it('reports unsupported remote session-affinity as unreachable when remote routing probe fails', async () => {
+    await withScopedConfig(async () => {
+      routingTarget = {
+        host: 'remote.example.com',
+        port: 8080,
+        protocol: 'http',
+        isRemote: true,
+      };
+      responseFactory = null;
+
+      const mod = await loadRoutingModule();
+      const state = await mod.readCliproxySessionAffinityState();
+
+      expect(state.source).toBe('unsupported');
+      expect(state.reachable).toBe(false);
+      expect(state.message).toContain('not reachable');
+    });
+  });
 });

tests/unit/commands/completion-backend.test.ts

@@ -128,6 +128,22 @@ describe('completion backend', () => {
     expect(values).toContain('my-codex');
   });
 
+  test('suggests the correct routing affinity completion shape', () => {
+    expect(suggestionValues(['cliproxy', 'routing'])).toEqual(
+      expect.arrayContaining(['set', 'explain', 'affinity'])
+    );
+    expect(suggestionValues(['cliproxy', 'routing', 'affinity'])).toEqual(
+      expect.arrayContaining(['on', 'off'])
+    );
+    expect(suggestionValues(['cliproxy', 'routing', 'affinity', 'on'])).toEqual(
+      expect.arrayContaining(['--ttl'])
+    );
+    expect(suggestionValues(['cliproxy', 'routing', 'affinity', 'off'])).toEqual(
+      expect.arrayContaining(['--ttl'])
+    );
+    expect(suggestionValues(['cliproxy', 'routing', 'affinity', '--ttl'])).not.toContain('--ttl');
+  });
+
   test('suggests env format values after the format flag', () => {
     const values = suggestionValues(['env', '--format']);
     expect(values).toEqual(

tests/unit/unified-config.test.ts

@@ -285,6 +285,74 @@ describe('continuity-inheritance-config', () => {
   });
 });
 
+describe('cliproxy session-affinity ttl normalization', () => {
+  it('normalizes invalid stored ttl values back to the safe default', () => {
+    const originalCcsHome = process.env.CCS_HOME;
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-affinity-ttl-home-'));
+    const ccsDir = path.join(tempHome, '.ccs');
+    fs.mkdirSync(ccsDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(ccsDir, 'config.yaml'),
+      [
+        'version: 8',
+        'cliproxy:',
+        '  routing:',
+        '    strategy: round-robin',
+        '    session_affinity: true',
+        '    session_affinity_ttl: forever',
+        '',
+      ].join('\n')
+    );
+
+    process.env.CCS_HOME = tempHome;
+    try {
+      const config = loadOrCreateUnifiedConfig();
+      expect(config.cliproxy.routing.session_affinity_ttl).toBe('1h');
+    } finally {
+      if (originalCcsHome === undefined) {
+        delete process.env.CCS_HOME;
+      } else {
+        process.env.CCS_HOME = originalCcsHome;
+      }
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+  });
+
+  it('normalizes non-positive stored ttl values back to the safe default', () => {
+    const originalCcsHome = process.env.CCS_HOME;
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-affinity-zero-ttl-home-'));
+    const ccsDir = path.join(tempHome, '.ccs');
+    fs.mkdirSync(ccsDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(ccsDir, 'config.yaml'),
+      [
+        'version: 8',
+        'cliproxy:',
+        '  routing:',
+        '    strategy: round-robin',
+        '    session_affinity: true',
+        '    session_affinity_ttl: 0s',
+        '',
+      ].join('\n')
+    );
+
+    process.env.CCS_HOME = tempHome;
+    try {
+      const config = loadOrCreateUnifiedConfig();
+      expect(config.cliproxy.routing.session_affinity_ttl).toBe('1h');
+    } finally {
+      if (originalCcsHome === undefined) {
+        delete process.env.CCS_HOME;
+      } else {
+        process.env.CCS_HOME = originalCcsHome;
+      }
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('official-channels-config', () => {
   it('keeps explicit channels.selected empty even when legacy discord_channels.enabled is true', () => {
     const originalCcsHome = process.env.CCS_HOME;

tests/unit/web-server/cliproxy-routing-routes.test.ts

@@ -7,6 +7,8 @@ describe('cliproxy routing routes', () => {
   let baseUrl = '';
   let readStateMock: ReturnType<typeof mock>;
   let applyStrategyMock: ReturnType<typeof mock>;
+  let readAffinityStateMock: ReturnType<typeof mock>;
+  let applyAffinityMock: ReturnType<typeof mock>;
 
   beforeEach(async () => {
     readStateMock = mock(async () => ({
@@ -22,16 +24,43 @@ describe('cliproxy routing routes', () => {
       reachable: true,
       applied: 'live-and-config',
     }));
+    readAffinityStateMock = mock(async () => ({
+      enabled: true,
+      ttl: '1h',
+      source: 'config',
+      target: 'local',
+      reachable: true,
+      manageable: true,
+    }));
+    applyAffinityMock = mock(async () => ({
+      enabled: false,
+      ttl: '30m',
+      source: 'config',
+      target: 'local',
+      reachable: true,
+      manageable: true,
+      applied: 'config-only',
+    }));
 
     mock.module('../../../src/cliproxy/routing-strategy', () => ({
       readCliproxyRoutingState: readStateMock,
       applyCliproxyRoutingStrategy: applyStrategyMock,
+      readCliproxySessionAffinityState: readAffinityStateMock,
+      applyCliproxySessionAffinitySettings: applyAffinityMock,
       normalizeCliproxyRoutingStrategy: (value: unknown) => {
         if (value === 'round-robin' || value === 'fill-first') {
           return value;
         }
         return null;
       },
+      normalizeCliproxySessionAffinityEnabled: (value: unknown) => {
+        if (value === true || value === false) return value;
+        return null;
+      },
+      normalizeCliproxySessionAffinityTtl: (value: unknown) => {
+        if (value === '30m' || value === '1h') return value;
+        return null;
+      },
     }));
 
     const { default: routingRoutes } = await import(
@@ -103,4 +132,52 @@ describe('cliproxy routing routes', () => {
       applied: 'live-and-config',
     });
   });
+
+  it('returns the current session-affinity state', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/session-affinity`);
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      enabled: true,
+      ttl: '1h',
+      source: 'config',
+      target: 'local',
+      reachable: true,
+      manageable: true,
+    });
+    expect(readAffinityStateMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects invalid session-affinity payloads', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/session-affinity`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ enabled: 'auto', ttl: 'forever' }),
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({
+      error: 'Invalid session affinity payload. Use enabled=true|false and ttl like 30m or 1h.',
+    });
+    expect(applyAffinityMock).not.toHaveBeenCalled();
+  });
+
+  it('applies valid session-affinity settings', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/session-affinity`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ enabled: false, ttl: '30m' }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(applyAffinityMock).toHaveBeenCalledWith({ enabled: false, ttl: '30m' });
+    expect(await response.json()).toEqual({
+      enabled: false,
+      ttl: '30m',
+      source: 'config',
+      target: 'local',
+      reachable: true,
+      manageable: true,
+      applied: 'config-only',
+    });
+  });
 });

ui/src/components/cliproxy/routing-guidance-card.tsx

@@ -1,8 +1,12 @@
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { ArrowRightLeft, ChevronDown, ChevronUp, RefreshCw } from 'lucide-react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
-import type { CliproxyRoutingState, RoutingStrategy } from '@/lib/api-client';
+import type {
+  CliproxyRoutingState,
+  RoutingStrategy,
+  CliproxySessionAffinityState,
+} from '@/lib/api-client';
 import { cn } from '@/lib/utils';
 import { useTranslation } from 'react-i18next';
 
@@ -10,10 +14,12 @@ interface RoutingGuidanceCardProps {
   className?: string;
   compact?: boolean;
   state?: CliproxyRoutingState;
+  sessionAffinityState?: CliproxySessionAffinityState;
   isLoading: boolean;
   isSaving: boolean;
   error?: Error | null;
   onApply: (strategy: RoutingStrategy) => void;
+  onApplyAffinity: (data: { enabled: boolean; ttl?: string }) => void;
 }
 
 const STRATEGY_COPY: Record<RoutingStrategy, { title: string; description: string }> = {
@@ -31,18 +37,82 @@ export function RoutingGuidanceCard({
   className,
   compact = false,
   state,
+  sessionAffinityState,
   isLoading,
   isSaving,
   error,
   onApply,
+  onApplyAffinity,
 }: RoutingGuidanceCardProps) {
   const { t } = useTranslation();
   const currentStrategy = state?.strategy ?? 'round-robin';
+  const currentAffinityEnabled = sessionAffinityState?.enabled ?? false;
+  const currentAffinityTtl = sessionAffinityState?.ttl ?? '1h';
+  const sessionAffinityManageable = sessionAffinityState?.manageable ?? true;
   const [selected, setSelected] = useState<RoutingStrategy>(currentStrategy);
+  const [selectedAffinityEnabled, setSelectedAffinityEnabled] = useState(currentAffinityEnabled);
+  const [selectedAffinityTtl, setSelectedAffinityTtl] = useState(currentAffinityTtl);
   const [detailsOpen, setDetailsOpen] = useState(false);
   const sourceLabel = state?.source === 'live' ? 'Live CLIProxy' : 'Saved startup default';
   const saveDisabled = isLoading || isSaving || !state || selected === currentStrategy;
   const detailToggleLabel = detailsOpen ? 'Hide details' : 'Show details';
+  const affinityControlDisabled = isLoading || isSaving || !!error || !sessionAffinityManageable;
+  const affinityActionLabel = sessionAffinityManageable
+    ? selectedAffinityEnabled
+      ? t('routingGuidance.disableSessionAffinity')
+      : t('routingGuidance.enableSessionAffinity')
+    : t('routingGuidance.sessionAffinityUnavailable');
+  const pendingAffinityRef = useRef<{ enabled: boolean; ttl: string } | null>(null);
+  const suppressNextAffinityBlurRef = useRef(false);
+
+  useEffect(() => {
+    setSelected(currentStrategy);
+  }, [currentStrategy]);
+
+  useEffect(() => {
+    setSelectedAffinityEnabled(currentAffinityEnabled);
+    setSelectedAffinityTtl(currentAffinityTtl);
+  }, [currentAffinityEnabled, currentAffinityTtl]);
+
+  useEffect(() => {
+    if (isSaving || !pendingAffinityRef.current) {
+      return;
+    }
+
+    const pending = pendingAffinityRef.current;
+    const succeeded =
+      pending.enabled === currentAffinityEnabled && pending.ttl === currentAffinityTtl;
+
+    if (!succeeded) {
+      setSelectedAffinityEnabled(currentAffinityEnabled);
+      setSelectedAffinityTtl(currentAffinityTtl);
+    }
+
+    pendingAffinityRef.current = null;
+  }, [isSaving, currentAffinityEnabled, currentAffinityTtl]);
+
+  const handleAffinityToggle = () => {
+    if (!sessionAffinityManageable) return;
+    const nextEnabled = !selectedAffinityEnabled;
+    const nextTtl = selectedAffinityTtl.trim() || '1h';
+    pendingAffinityRef.current = { enabled: nextEnabled, ttl: nextTtl };
+    setSelectedAffinityEnabled(nextEnabled);
+    onApplyAffinity({ enabled: nextEnabled, ttl: nextTtl });
+  };
+
+  const handleAffinityTtlBlur = () => {
+    if (!sessionAffinityManageable || !!error) return;
+    if (suppressNextAffinityBlurRef.current) {
+      suppressNextAffinityBlurRef.current = false;
+      return;
+    }
+    const nextTtl = selectedAffinityTtl.trim() || '1h';
+    if (nextTtl === currentAffinityTtl) {
+      return;
+    }
+    pendingAffinityRef.current = { enabled: selectedAffinityEnabled, ttl: nextTtl };
+    onApplyAffinity({ enabled: selectedAffinityEnabled, ttl: nextTtl });
+  };
 
   if (compact) {
     const handleApply = (s: RoutingStrategy) => {
@@ -53,57 +123,107 @@ export function RoutingGuidanceCard({
     };
 
     return (
-      <div
-        className={cn(
-          'group/routing flex items-center justify-between mt-1 p-1 -mx-1 rounded-lg transition-colors hover:bg-primary/5',
-          className
-        )}
-      >
-        <div className="flex items-center gap-2 text-xs font-medium text-foreground">
-          <div className="relative flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-background border border-border/60 text-muted-foreground shadow-sm overflow-hidden transition-all duration-300 group-hover/routing:border-primary/40 group-hover/routing:text-primary group-hover/routing:shadow-[0_0_12px_rgba(59,130,246,0.15)] dark:group-hover/routing:shadow-[0_0_12px_rgba(59,130,246,0.1)]">
-            <div className="absolute inset-0 bg-primary/10 translate-y-full group-hover/routing:translate-y-0 transition-transform duration-300 ease-out" />
-            <ArrowRightLeft className="relative z-10 h-3.5 w-3.5 transition-transform duration-300 group-hover/routing:scale-110" />
+      <div className={cn('group/routing mt-1 space-y-2 -mx-1 rounded-lg p-1', className)}>
+        <div className="flex items-center justify-between rounded-lg transition-colors hover:bg-primary/5">
+          <div className="flex items-center gap-2 px-1 text-xs font-medium text-foreground">
+            <div className="relative flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-background border border-border/60 text-muted-foreground shadow-sm overflow-hidden transition-all duration-300 group-hover/routing:border-primary/40 group-hover/routing:text-primary group-hover/routing:shadow-[0_0_12px_rgba(59,130,246,0.15)] dark:group-hover/routing:shadow-[0_0_12px_rgba(59,130,246,0.1)]">
+              <div className="absolute inset-0 bg-primary/10 translate-y-full group-hover/routing:translate-y-0 transition-transform duration-300 ease-out" />
+              <ArrowRightLeft className="relative z-10 h-3.5 w-3.5 transition-transform duration-300 group-hover/routing:scale-110" />
+            </div>
+            <span className="tracking-tight transition-colors duration-300 group-hover/routing:text-primary group-hover/routing:font-semibold">
+              Routing
+            </span>
+            {isSaving && <RefreshCw className="ml-1 h-3 w-3 shrink-0 animate-spin text-primary" />}
+          </div>
+
+          <div className="relative grid grid-cols-2 p-0.5 gap-0.5 rounded-lg border border-border/60 bg-muted/30 shadow-[inset_0_1px_2px_rgba(0,0,0,0.05)] dark:shadow-[inset_0_1px_3px_rgba(0,0,0,0.2)] transition-colors duration-300 group-hover/routing:border-primary/20 group-hover/routing:bg-primary/5">
+            <div
+              className={cn(
+                'absolute inset-y-0.5 left-0.5 w-[calc(50%-0.1875rem)] rounded bg-background shadow-[0_1px_3px_rgba(0,0,0,0.1),0_1px_2px_rgba(0,0,0,0.06)] ring-1 ring-black/5 dark:ring-white/10 transition-all duration-300',
+                selected === 'fill-first' ? 'translate-x-[calc(100%+0.125rem)]' : 'translate-x-0',
+                'group-hover/routing:shadow-[0_0_8px_rgba(59,130,246,0.15)] dark:group-hover/routing:shadow-[0_0_8px_rgba(59,130,246,0.1)] group-hover/routing:ring-primary/30'
+              )}
+              style={{ transitionTimingFunction: 'cubic-bezier(0.175, 0.885, 0.32, 1.275)' }}
+            />
+            {(
+              Object.entries(STRATEGY_COPY) as Array<
+                [RoutingStrategy, { title: string; description: string }]
+              >
+            ).map(([strategy, copy]) => {
+              const active = selected === strategy;
+              return (
+                <button
+                  key={strategy}
+                  type="button"
+                  className={cn(
+                    'relative z-10 flex items-center justify-center rounded px-2.5 py-0.5 text-[10px] font-medium whitespace-nowrap transition-colors duration-200',
+                    active
+                      ? 'text-foreground group-hover/routing:text-primary'
+                      : 'text-muted-foreground/70 hover:text-foreground/90 group-hover/routing:text-muted-foreground/90'
+                  )}
+                  onClick={() => handleApply(strategy)}
+                  disabled={isLoading || isSaving || !!error}
+                  title={copy.description}
+                >
+                  {copy.title}
+                </button>
+              );
+            })}
           </div>
-          <span className="tracking-tight transition-colors duration-300 group-hover/routing:text-primary group-hover/routing:font-semibold">
-            Routing
-          </span>
-          {isSaving && <RefreshCw className="ml-1 h-3 w-3 shrink-0 animate-spin text-primary" />}
         </div>
 
-        <div className="relative grid grid-cols-2 p-0.5 gap-0.5 rounded-lg border border-border/60 bg-muted/30 shadow-[inset_0_1px_2px_rgba(0,0,0,0.05)] dark:shadow-[inset_0_1px_3px_rgba(0,0,0,0.2)] transition-colors duration-300 group-hover/routing:border-primary/20 group-hover/routing:bg-primary/5">
-          <div
-            className={cn(
-              'absolute inset-y-0.5 left-0.5 w-[calc(50%-0.1875rem)] rounded bg-background shadow-[0_1px_3px_rgba(0,0,0,0.1),0_1px_2px_rgba(0,0,0,0.06)] ring-1 ring-black/5 dark:ring-white/10 transition-all duration-300',
-              selected === 'fill-first' ? 'translate-x-[calc(100%+0.125rem)]' : 'translate-x-0',
-              'group-hover/routing:shadow-[0_0_8px_rgba(59,130,246,0.15)] dark:group-hover/routing:shadow-[0_0_8px_rgba(59,130,246,0.1)] group-hover/routing:ring-primary/30'
-            )}
-            style={{ transitionTimingFunction: 'cubic-bezier(0.175, 0.885, 0.32, 1.275)' }}
-          />
-          {(
-            Object.entries(STRATEGY_COPY) as Array<
-              [RoutingStrategy, { title: string; description: string }]
+        <div className="flex items-center justify-between gap-2 rounded-lg border border-border/60 bg-muted/20 px-2 py-1.5">
+          <div className="min-w-0">
+            <div className="text-[10px] font-medium text-foreground">
+              {t('routingGuidance.sessionAffinity')}
+            </div>
+            <div className="text-[10px] text-muted-foreground">
+              {sessionAffinityManageable
+                ? t('routingGuidance.ttlBadge', { ttl: currentAffinityTtl })
+                : t('routingGuidance.localOnlySetting')}
+            </div>
+          </div>
+          <div className="flex items-center gap-1">
+            {sessionAffinityManageable ? (
+              <input
+                aria-label="Session affinity TTL"
+                className="h-6 w-14 rounded border border-border/70 bg-background px-2 text-[10px] text-foreground"
+                value={selectedAffinityTtl}
+                onChange={(event) => setSelectedAffinityTtl(event.target.value)}
+                onBlur={handleAffinityTtlBlur}
+                disabled={affinityControlDisabled}
+              />
+            ) : null}
+            <button
+              type="button"
+              aria-label={affinityActionLabel}
+              className={cn(
+                'rounded border px-2 py-1 text-[10px] font-medium transition-colors',
+                sessionAffinityManageable
+                  ? 'border-border/70 bg-background text-foreground hover:border-primary/40 hover:text-primary'
+                  : 'border-border/60 bg-muted/40 text-muted-foreground'
+              )}
+              onMouseDown={() => {
+                suppressNextAffinityBlurRef.current = true;
+              }}
+              onClick={handleAffinityToggle}
+              disabled={affinityControlDisabled}
+              title={sessionAffinityState?.message}
             >
-          ).map(([strategy, copy]) => {
-            const active = selected === strategy;
-            return (
-              <button
-                key={strategy}
-                type="button"
-                className={cn(
-                  'relative z-10 flex items-center justify-center rounded px-2.5 py-0.5 text-[10px] font-medium whitespace-nowrap transition-colors duration-200',
-                  active
-                    ? 'text-foreground group-hover/routing:text-primary'
-                    : 'text-muted-foreground/70 hover:text-foreground/90 group-hover/routing:text-muted-foreground/90'
-                )}
-                onClick={() => handleApply(strategy)}
-                disabled={isLoading || isSaving || !!error}
-                title={copy.description}
-              >
-                {copy.title}
-              </button>
-            );
-          })}
+              {sessionAffinityManageable
+                ? selectedAffinityEnabled
+                  ? t('routingGuidance.sessionAffinityOn')
+                  : t('routingGuidance.sessionAffinityOff')
+                : t('routingGuidance.sessionAffinityUnavailable')}
+            </button>
+          </div>
         </div>
+
+        {sessionAffinityState?.message ? (
+          <div className="rounded-lg border border-border/60 bg-muted/20 px-2 py-1.5 text-[10px] text-muted-foreground">
+            {sessionAffinityState.message}
+          </div>
+        ) : null}
       </div>
     );
   }
@@ -181,6 +301,55 @@ export function RoutingGuidanceCard({
           <span>{t('routingGuidance.fillFirst')}</span>
         </div>
 
+        <div className="grid gap-3 rounded-lg border border-border/70 bg-muted/20 px-3 py-3 xl:col-span-2">
+          <div className="flex flex-wrap items-center gap-2">
+            <div className="text-sm font-medium">{t('routingGuidance.sessionAffinity')}</div>
+            <Badge variant="secondary">
+              {selectedAffinityEnabled
+                ? t('routingGuidance.sessionAffinityOn')
+                : t('routingGuidance.sessionAffinityOff')}
+            </Badge>
+            {sessionAffinityState?.ttl ? (
+              <Badge variant="outline">
+                {t('routingGuidance.ttlBadge', { ttl: currentAffinityTtl })}
+              </Badge>
+            ) : null}
+            {!sessionAffinityManageable ? (
+              <Badge variant="outline">{t('routingGuidance.localOnly')}</Badge>
+            ) : null}
+          </div>
+          <p className="text-xs leading-5 text-muted-foreground">
+            {t('routingGuidance.sessionAffinityDescription')}
+          </p>
+          <div className="flex flex-wrap items-center gap-2">
+            <input
+              aria-label="Session affinity TTL"
+              className="h-9 w-24 rounded-md border border-border/70 bg-background px-3 text-sm text-foreground"
+              value={selectedAffinityTtl}
+              onChange={(event) => setSelectedAffinityTtl(event.target.value)}
+              onBlur={handleAffinityTtlBlur}
+              disabled={affinityControlDisabled}
+            />
+            <Button
+              type="button"
+              variant="outline"
+              onMouseDown={() => {
+                suppressNextAffinityBlurRef.current = true;
+              }}
+              onClick={handleAffinityToggle}
+              disabled={affinityControlDisabled}
+              aria-label={affinityActionLabel}
+            >
+              {affinityActionLabel}
+            </Button>
+          </div>
+          {sessionAffinityState?.message ? (
+            <div className="rounded-lg border border-border/70 bg-background/70 px-3 py-2 text-xs text-muted-foreground">
+              {sessionAffinityState.message}
+            </div>
+          ) : null}
+        </div>
+
         {error ? (
           <div className="rounded-lg border border-destructive/25 bg-destructive/5 px-3 py-2 text-sm xl:col-span-2">
             {error.message}
@@ -210,6 +379,14 @@ export function RoutingGuidanceCard({
                 </div>
               );
             })}
+            <div className="space-y-1 md:col-span-2">
+              <div className="text-sm font-medium">
+                {t('routingGuidance.sessionRecognitionTitle')}
+              </div>
+              <p className="text-xs leading-5 text-muted-foreground">
+                {t('routingGuidance.sessionRecognitionDescription')}
+              </p>
+            </div>
           </div>
         ) : null}
       </div>

ui/src/components/monitoring/proxy-status-widget.tsx

@@ -61,7 +61,9 @@ import {
   useInstallVersion,
   useRestartProxy,
   useCliproxyRoutingStrategy,
+  useCliproxySessionAffinity,
   useUpdateCliproxyRoutingStrategy,
+  useUpdateCliproxySessionAffinity,
 } from '@/hooks/use-cliproxy';
 import { useSyncStatus, useExecuteSync } from '@/hooks/use-cliproxy-sync';
 import { cn } from '@/lib/utils';
@@ -159,6 +161,14 @@ export function ProxyStatusWidget() {
     error: routingError,
   } = useCliproxyRoutingStrategy();
   const updateRouting = useUpdateCliproxyRoutingStrategy();
+  const {
+    data: sessionAffinityState,
+    isLoading: sessionAffinityLoading,
+    error: sessionAffinityError,
+  } = useCliproxySessionAffinity();
+  const updateSessionAffinity = useUpdateCliproxySessionAffinity();
+  const isSavingRoutingConfig = updateRouting.isPending || updateSessionAffinity.isPending;
+  const routingConfigError = routingError instanceof Error ? routingError : null;
   const startProxy = useStartProxy();
   const stopProxy = useStopProxy();
   const restartProxy = useRestartProxy();
@@ -190,6 +200,19 @@ export function ProxyStatusWidget() {
   // Determine if remote mode is enabled
   const remoteConfig = cliproxyConfig?.remote;
   const isRemoteMode = remoteConfig?.enabled && remoteConfig?.host;
+  const effectiveSessionAffinityState =
+    sessionAffinityState ??
+    (sessionAffinityError instanceof Error
+      ? {
+          source: 'unsupported' as const,
+          target: (routingState?.target ?? (isRemoteMode ? 'remote' : 'local')) as
+            | 'local'
+            | 'remote',
+          reachable: false,
+          manageable: false,
+          message: sessionAffinityError.message,
+        }
+      : undefined);
 
   const isRunning = status?.running ?? false;
   const isActioning =
@@ -315,14 +338,16 @@ export function ProxyStatusWidget() {
         </div>
 
         <RoutingGuidanceCard
-          key={`remote:${routingState?.strategy ?? 'round-robin'}`}
+          key={`remote:${routingState?.strategy ?? 'round-robin'}:${effectiveSessionAffinityState?.enabled ?? 'na'}:${effectiveSessionAffinityState?.ttl ?? 'na'}:${effectiveSessionAffinityState?.manageable ?? 'na'}`}
           compact
           className="mt-3"
           state={routingState}
-          isLoading={routingLoading}
-          isSaving={updateRouting.isPending}
-          error={routingError instanceof Error ? routingError : null}
+          sessionAffinityState={effectiveSessionAffinityState}
+          isLoading={routingLoading || sessionAffinityLoading}
+          isSaving={isSavingRoutingConfig}
+          error={routingConfigError}
           onApply={(strategy) => updateRouting.mutate(strategy)}
+          onApplyAffinity={(data) => updateSessionAffinity.mutate(data)}
         />
       </div>
     );
@@ -471,14 +496,16 @@ export function ProxyStatusWidget() {
         </div>
 
         <RoutingGuidanceCard
-          key={`local:${routingState?.strategy ?? 'round-robin'}`}
+          key={`local:${routingState?.strategy ?? 'round-robin'}:${effectiveSessionAffinityState?.enabled ?? 'na'}:${effectiveSessionAffinityState?.ttl ?? 'na'}:${effectiveSessionAffinityState?.manageable ?? 'na'}`}
           compact
           className="mt-3"
           state={routingState}
-          isLoading={routingLoading}
-          isSaving={updateRouting.isPending}
-          error={routingError instanceof Error ? routingError : null}
+          sessionAffinityState={effectiveSessionAffinityState}
+          isLoading={routingLoading || sessionAffinityLoading}
+          isSaving={isSavingRoutingConfig}
+          error={routingConfigError}
           onApply={(strategy) => updateRouting.mutate(strategy)}
+          onApplyAffinity={(data) => updateSessionAffinity.mutate(data)}
         />
 
         {/* Expanded section: Version Management (available even when not running) */}

ui/src/hooks/use-cliproxy.ts

@@ -11,6 +11,7 @@ import {
   type UpdateVariant,
   type CreatePreset,
   type RoutingStrategy,
+  type CliproxySessionAffinityApplyResult,
 } from '@/lib/api-client';
 import { toast } from 'sonner';
 import { useTranslation } from 'react-i18next';
@@ -18,6 +19,7 @@ import { useTranslation } from 'react-i18next';
 function invalidateCliproxyRoutingQueries(queryClient: ReturnType<typeof useQueryClient>): void {
   queryClient.invalidateQueries({ queryKey: ['cliproxy-catalog'] });
   queryClient.invalidateQueries({ queryKey: ['cliproxy-models'] });
+  queryClient.invalidateQueries({ queryKey: ['cliproxy-session-affinity'] });
 }
 
 function invalidateCliproxyAccountQueries(queryClient: ReturnType<typeof useQueryClient>): void {
@@ -74,6 +76,36 @@ export function useUpdateCliproxyRoutingStrategy() {
   });
 }
 
+export function useCliproxySessionAffinity() {
+  return useQuery({
+    queryKey: ['cliproxy-session-affinity'],
+    queryFn: () => api.cliproxy.getSessionAffinity(),
+  });
+}
+
+export function useUpdateCliproxySessionAffinity() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation({
+    mutationFn: (data: { enabled: boolean; ttl?: string }) =>
+      api.cliproxy.updateSessionAffinity(data),
+    onSuccess: (result: CliproxySessionAffinityApplyResult) => {
+      queryClient.setQueryData(['cliproxy-session-affinity'], result);
+      queryClient.invalidateQueries({ queryKey: ['cliproxy-session-affinity'] });
+      const stateLabel = result.enabled
+        ? t('routingGuidance.sessionAffinityEnabled')
+        : t('routingGuidance.sessionAffinityDisabled');
+      toast.success(
+        result.message || t('toasts.sessionAffinityUpdated', { state: stateLabel.toLowerCase() })
+      );
+    },
+    onError: (error: Error) => {
+      toast.error(error.message);
+    },
+  });
+}
+
 export function useCreateVariant() {
   const queryClient = useQueryClient();
   const { t } = useTranslation();

ui/src/lib/api-client.ts

@@ -521,6 +521,20 @@ export interface CliproxyRoutingApplyResult extends CliproxyRoutingState {
   applied: 'live' | 'live-and-config' | 'config-only';
 }
 
+export interface CliproxySessionAffinityState {
+  enabled?: boolean;
+  ttl?: string;
+  source: 'config' | 'unsupported';
+  target: 'local' | 'remote';
+  reachable: boolean;
+  manageable: boolean;
+  message?: string;
+}
+
+export interface CliproxySessionAffinityApplyResult extends CliproxySessionAffinityState {
+  applied: 'config-and-live' | 'config-only' | 'unsupported';
+}
+
 /** Auth file info for Config tab */
 export interface AuthFile {
   name: string;
@@ -1269,6 +1283,13 @@ export const api = {
         method: 'PUT',
         body: JSON.stringify({ value: strategy }),
       }),
+    getSessionAffinity: () =>
+      request<CliproxySessionAffinityState>('/cliproxy/routing/session-affinity'),
+    updateSessionAffinity: (data: { enabled: boolean; ttl?: string }) =>
+      request<CliproxySessionAffinityApplyResult>('/cliproxy/routing/session-affinity', {
+        method: 'PUT',
+        body: JSON.stringify(data),
+      }),
     aiProviders: {
       list: () => request<ListAiProvidersResult>('/cliproxy/ai-providers'),
       create: (family: AiProviderFamilyId, data: UpsertAiProviderEntryInput) =>

ui/src/lib/i18n.ts

@@ -1823,6 +1823,22 @@ const resources = {
         fillFirst: 'Fill first keeps backup accounts cold until they are needed.',
         routingStrategy: 'Routing strategy',
         optionalRouting: 'Optional routing',
+        sessionAffinity: 'Session affinity',
+        sessionAffinityOn: 'On',
+        sessionAffinityOff: 'Off',
+        sessionAffinityEnabled: 'Enabled',
+        sessionAffinityDisabled: 'Disabled',
+        enableSessionAffinity: 'Enable session affinity',
+        disableSessionAffinity: 'Disable session affinity',
+        sessionAffinityUnavailable: 'Session affinity unavailable',
+        localOnly: 'Local only',
+        localOnlySetting: 'Local-only setting',
+        ttlBadge: 'TTL {{ttl}}',
+        sessionAffinityDescription:
+          'Keep one conversation pinned to the same account when possible. CLIProxy prefers explicit session or thread identifiers when clients send them, then falls back to request metadata or the opening prompt history when it has to infer a stable key.',
+        sessionRecognitionTitle: 'Session recognition',
+        sessionRecognitionDescription:
+          'CCS does not promise one universal precedence order here. In practice, upstream backends prefer explicit session or thread IDs first, then fall back to metadata fields and finally a hash based on the opening prompt history.',
       },
       extendedContext: {
         extendedContext: 'Extended Context',
@@ -2173,6 +2189,7 @@ const resources = {
         accountsUpdated: 'Accounts updated',
         noProfilesToSync: 'No profiles to sync',
         syncFailed: 'Sync failed: {{error}}',
+        sessionAffinityUpdated: 'Session affinity {{state}}.',
         providerAuthSuccess: '{{provider}} authentication successful',
         providerDeviceCodeInCallback: 'Provider returned Device Code flow in callback mode',
         providerAuthTimeout: 'Authentication timed out. Please try again.',
@@ -4289,6 +4306,22 @@ const resources = {
         fillFirst: '优先填满模式让备用账号保持冷启动直到需要时。',
         routingStrategy: '路由策略',
         optionalRouting: '可选路由',
+        sessionAffinity: '会话粘性',
+        sessionAffinityOn: '开启',
+        sessionAffinityOff: '关闭',
+        sessionAffinityEnabled: '已启用',
+        sessionAffinityDisabled: '已禁用',
+        enableSessionAffinity: '启用会话粘性',
+        disableSessionAffinity: '禁用会话粘性',
+        sessionAffinityUnavailable: '会话粘性不可用',
+        localOnly: '仅本地',
+        localOnlySetting: '仅限本地设置',
+        ttlBadge: 'TTL {{ttl}}',
+        sessionAffinityDescription:
+          '尽量将同一对话固定到同一个账号。CLIProxy 会优先使用客户端显式提供的会话或线程标识；如果没有，再回退到请求元数据或开场提示历史来推断稳定键。',
+        sessionRecognitionTitle: '会话识别',
+        sessionRecognitionDescription:
+          'CCS 不承诺所有后端都使用同一优先级顺序。通常上游会优先使用显式会话或线程 ID，然后回退到元数据字段，最后再回退到基于开场提示历史的哈希。',
       },
       extendedContext: {
         extendedContext: '扩展上下文',
@@ -4624,6 +4657,7 @@ const resources = {
         accountsUpdated: '账号已更新',
         noProfilesToSync: '没有可同步的配置',
         syncFailed: '同步失败：{{error}}',
+        sessionAffinityUpdated: '会话粘性已{{state}}。',
         providerAuthSuccess: '{{provider}} 认证成功',
         providerDeviceCodeInCallback: '提供商在回调模式中返回了设备码流程',
         providerAuthTimeout: '认证超时，请重试。',
@@ -6825,6 +6859,22 @@ const resources = {
         fillFirst: 'Fill-first giữ tài khoản dự phòng cho đến khi cần thiết.',
         routingStrategy: 'Chiến lược định tuyến',
         optionalRouting: 'Định tuyến tùy chọn',
+        sessionAffinity: 'Ghim phiên',
+        sessionAffinityOn: 'Bật',
+        sessionAffinityOff: 'Tắt',
+        sessionAffinityEnabled: 'bật',
+        sessionAffinityDisabled: 'tắt',
+        enableSessionAffinity: 'Bật ghim phiên',
+        disableSessionAffinity: 'Tắt ghim phiên',
+        sessionAffinityUnavailable: 'Ghim phiên không khả dụng',
+        localOnly: 'Chỉ cục bộ',
+        localOnlySetting: 'Thiết lập chỉ cục bộ',
+        ttlBadge: 'TTL {{ttl}}',
+        sessionAffinityDescription:
+          'Giữ một cuộc hội thoại trên cùng một tài khoản khi có thể. CLIProxy ưu tiên mã phiên hoặc luồng mà client gửi rõ ràng; nếu không có, nó sẽ dùng metadata của request hoặc lịch sử prompt mở đầu để suy ra khóa ổn định.',
+        sessionRecognitionTitle: 'Nhận diện phiên',
+        sessionRecognitionDescription:
+          'CCS không cam kết một thứ tự ưu tiên chung cho mọi backend. Trên thực tế, backend upstream thường ưu tiên session hoặc thread id tường minh, rồi mới fallback sang metadata và cuối cùng là hàm băm của lịch sử prompt mở đầu.',
       },
       extendedContext: {
         extendedContext: 'Ngữ cảnh mở rộng',
@@ -7163,6 +7213,7 @@ const resources = {
         accountsUpdated: 'Tài khoản đã được cập nhật',
         noProfilesToSync: 'Không có hồ sơ để đồng bộ',
         syncFailed: 'Đồng bộ thất bại: {{error}}',
+        sessionAffinityUpdated: 'Ghim phiên đã {{state}}.',
         providerAuthSuccess: 'Xác thực {{provider}} thành công',
         providerDeviceCodeInCallback: 'Nhà cung cấp trả về Device Code flow trong chế độ callback',
         providerAuthTimeout: 'Đã hết thời gian xác thực. Vui lòng thử lại.',
@@ -9790,6 +9841,22 @@ const resources = {
         fillFirst: 'Fill first は、バックアップアカウントが必要になるまで待機させます。',
         routingStrategy: 'ルーティング戦略',
         optionalRouting: 'オプションのルーティング',
+        sessionAffinity: 'セッション固定',
+        sessionAffinityOn: 'オン',
+        sessionAffinityOff: 'オフ',
+        sessionAffinityEnabled: '有効',
+        sessionAffinityDisabled: '無効',
+        enableSessionAffinity: 'セッション固定を有効化',
+        disableSessionAffinity: 'セッション固定を無効化',
+        sessionAffinityUnavailable: 'セッション固定は利用できません',
+        localOnly: 'ローカルのみ',
+        localOnlySetting: 'ローカル専用設定',
+        ttlBadge: 'TTL {{ttl}}',
+        sessionAffinityDescription:
+          '可能な場合は 1 つの会話を同じアカウントに固定します。CLIProxy はクライアントが明示的に送るセッション ID やスレッド ID を優先し、それがない場合はリクエストのメタデータや冒頭プロンプト履歴から安定キーを推定します。',
+        sessionRecognitionTitle: 'セッション認識',
+        sessionRecognitionDescription:
+          'CCS はすべてのバックエンドで同一の優先順位を保証しません。一般に上流バックエンドは明示的なセッション / スレッド ID を優先し、その後にメタデータ、最後に冒頭プロンプト履歴のハッシュへフォールバックします。',
       },
       settingsDialog: {
         editProfile: 'プロファイルを編集: {{name}}',
@@ -10015,6 +10082,7 @@ const resources = {
         accountsUpdated: 'アカウントを更新しました',
         noProfilesToSync: '同期するプロファイルがありません',
         syncFailed: '同期に失敗しました: {{error}}',
+        sessionAffinityUpdated: 'セッション固定を{{state}}にしました。',
         providerAuthSuccess: '{{provider}} の認証に成功しました',
         providerDeviceCodeInCallback:
           'コールバックモードでプロバイダーがデバイスコードフローを返しました',

ui/tests/unit/components/cliproxy/routing-guidance-card.test.tsx

@@ -5,6 +5,7 @@ import { RoutingGuidanceCard } from '@/components/cliproxy/routing-guidance-card
 describe('RoutingGuidanceCard', () => {
   it('shows the current strategy and applies an explicit change', async () => {
     const onApply = vi.fn();
+    const onApplyAffinity = vi.fn();
 
     render(
       <RoutingGuidanceCard
@@ -14,19 +15,33 @@ describe('RoutingGuidanceCard', () => {
           target: 'local',
           reachable: true,
         }}
+        sessionAffinityState={{
+          enabled: true,
+          ttl: '1h',
+          source: 'config',
+          target: 'local',
+          reachable: true,
+          manageable: true,
+        }}
         isLoading={false}
         isSaving={false}
         onApply={onApply}
+        onApplyAffinity={onApplyAffinity}
       />
     );
 
     expect(screen.getByText('Routing strategy')).toBeInTheDocument();
     expect(screen.getAllByText('round-robin').length).toBeGreaterThan(0);
+    expect(screen.getByText('Session affinity')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('1h')).toBeInTheDocument();
 
     fireEvent.click(screen.getByRole('button', { name: /fill first/i }));
     fireEvent.click(screen.getByRole('button', { name: /use fill-first/i }));
 
     expect(onApply).toHaveBeenCalledWith('fill-first');
+
+    fireEvent.click(screen.getByRole('button', { name: /disable session affinity/i }));
+    expect(onApplyAffinity).toHaveBeenCalledWith({ enabled: false, ttl: '1h' });
   });
 
   it('shows the error state and disables apply', () => {
@@ -36,10 +51,40 @@ describe('RoutingGuidanceCard', () => {
         isSaving={false}
         error={new Error('Remote CLIProxy is not reachable')}
         onApply={() => undefined}
+        onApplyAffinity={() => undefined}
       />
     );
 
     expect(screen.getByText('Remote CLIProxy is not reachable')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: /use round-robin/i })).toBeDisabled();
   });
+
+  it('shows remote session-affinity guidance when the setting is not manageable', () => {
+    render(
+      <RoutingGuidanceCard
+        state={{
+          strategy: 'round-robin',
+          source: 'live',
+          target: 'remote',
+          reachable: true,
+        }}
+        sessionAffinityState={{
+          source: 'unsupported',
+          target: 'remote',
+          reachable: true,
+          manageable: false,
+          message: 'Remote session-affinity management is not supported from CCS yet.',
+        }}
+        isLoading={false}
+        isSaving={false}
+        onApply={() => undefined}
+        onApplyAffinity={() => undefined}
+      />
+    );
+
+    expect(
+      screen.getByText('Remote session-affinity management is not supported from CCS yet.')
+    ).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /session affinity unavailable/i })).toBeDisabled();
+  });
 });