fix: Codex session completion must not inject metadata by ding113 · Pull Request #601 · ding113/claude-code-hub

ding113 · 2026-01-12T19:40:34Z

Why\nCodex upstream rejects the request body field `metadata` (400: Unsupported parameter: metadata). The session completion feature must only write the supported Codex fields: header `session_id` and body `prompt_cache_key`.\n\n## What\n- Stop writing/creating `metadata` in Codex request bodies\n- Keep completion strictly to:\n - request header: `session_id` (and preserve compatibility with inbound `x-session-id`)\n - request body: `prompt_cache_key`\n\n## Tests\n- Updated unit tests to assert `metadata` is never added/modified\n- Coverage gate (>=80%): `bun run test:coverage:codex-session-id-completer`

Greptile Overview

Greptile Summary

This PR successfully addresses the Codex upstream requirement by implementing a session ID completion system that strictly avoids writing to the metadata field, which Codex rejects with a 400 error.

Key Changes

Core Implementation (session-completer.ts - 297 new lines)

Implements completeCodexSessionIdentifiers() that ensures both required Codex fields are present:
- Header: session_id (+ x-session-id for compatibility)
- Body: prompt_cache_key
Never writes to or modifies metadata - verification confirmed through code inspection and explicit test assertions
Completion strategy with three actions:
1. completed_missing_fields: Copies existing value when one field is present
2. generated_uuid_v7: Creates new UUID v7 when both fields are missing
3. reused_fingerprint_cache: Retrieves stable session ID from Redis based on fingerprint (keyId + IP + User-Agent + message hash)
Custom UUID v7 implementation follows RFC 9562 specification correctly
Robust Redis error handling with fallback to UUID v7 generation

Integration & Configuration

Session completer integrated into ProxySessionGuard before session tracking
Only triggers for Codex requests (detected by input array field)
New system setting enableCodexSessionIdCompletion (default: true) allows toggling
Full stack implementation: database migration, schema, types, validation, repository, actions, and UI
Special settings audit tracking for completion actions

Testing & Quality

Comprehensive test suite (555 lines) with 80% coverage gate
All 19 tests explicitly verify metadata is never added or modified
Tests cover: UUID v7 generation, fingerprint stability, Redis race conditions, header/body completion, edge cases
Dedicated Vitest config isolates session-completer coverage from heavy dependencies

Consistency Across Stack
All 28 files properly updated across the full stack, including:

Database: migration + schema
Backend: types, validation, repository, actions
Frontend: UI form + i18n (5 languages)
Infrastructure: special settings, system config cache, message service

Minor Issue Found

One style comment left regarding type definition inconsistency in special-settings.ts - the source union includes body_metadata_session_id which the completer never returns (it only reads, never writes metadata). This is a minor type hygiene issue with no runtime impact.

Confidence Score: 5/5

This PR is safe to merge with very high confidence
The implementation fully achieves its goal of avoiding metadata writes while ensuring Codex session identifiers are properly completed. The code quality is excellent with comprehensive test coverage (555 lines, 80% threshold), proper error handling, and defensive programming throughout. All 28 files are consistently updated across the entire stack. The single style issue found is minor and non-blocking (type definition includes unused source value). The feature is safely opt-in with a default-enabled toggle, and the implementation follows RFC 9562 for UUID v7 generation. No logic errors, security vulnerabilities, or edge cases were identified during thorough analysis.
No files require special attention - all implementations are clean and well-tested

Important Files Changed

File Analysis

Filename	Score	Overview
src/app/v1/_lib/codex/session-completer.ts	5/5	New file implementing Codex session ID completion. Ensures both session_id (header) and prompt_cache_key (body) are present. Never writes to metadata field per PR requirements. Includes UUID v7 generation and Redis-based fingerprint caching for session stability.
tests/unit/codex/session-completer.test.ts	5/5	Comprehensive test coverage (555 lines) for session completer. Verifies metadata is never added/modified, tests UUID v7 generation, fingerprint caching, Redis race conditions, and edge cases. All tests explicitly assert metadata remains undefined.
src/app/v1/_lib/proxy/session-guard.ts	5/5	Integrates session completer into proxy flow. Only triggers for Codex requests (detected by input array). Respects enableCodexSessionIdCompletion setting. Tracks completion action in special settings for audit purposes.
src/types/special-settings.ts	4/5	Adds CodexSessionIdCompletionSpecialSetting type for auditing completion actions. Minor type inconsistency: includes body_metadata_session_id source that completer never returns (completer only reads, never writes metadata).
src/drizzle/schema.ts	5/5	Adds enableCodexSessionIdCompletion boolean column with default true. Clean addition with proper comments explaining purpose.
drizzle/0054_tidy_winter_soldier.sql	5/5	Database migration adds enable_codex_session_id_completion column. Safe migration with DEFAULT true and NOT NULL, backward compatible with existing rows.
src/app/[locale]/settings/config/_components/system-settings-form.tsx	5/5	Adds UI toggle for Codex session ID completion feature. Properly wired with state management, form submission, and i18n labels.
vitest.codex-session-id-completer.config.ts	5/5	Dedicated Vitest config for session-completer with 80% coverage thresholds. Properly isolates test scope and excludes heavy modules from coverage calculation.

Sequence Diagram

sequenceDiagram
    participant Client as Codex Client
    participant Guard as ProxySessionGuard
    participant Completer as CodexSessionCompleter
    participant Redis as Redis Cache
    participant Upstream as Codex Upstream

    Client->>Guard: Request (may have session_id OR prompt_cache_key OR neither)
    
    Guard->>Guard: Check enableCodexSessionIdCompletion
    Guard->>Guard: Detect Codex request (has input array)
    
    Guard->>Completer: completeCodexSessionIdentifiers()
    
    alt Both session_id header AND prompt_cache_key body exist
        Completer->>Completer: Validate both values
        Completer->>Guard: Return (applied: false, action: "none")
    else One identifier exists
        Completer->>Completer: Copy existing value to missing field
        Completer->>Completer: Ensure both session_id and x-session-id headers present
        Completer->>Guard: Return (applied: true, action: "completed_missing_fields")
    else Neither identifier exists
        Completer->>Completer: Calculate fingerprint (keyId + IP + UA + messageHash)
        Completer->>Redis: Check if fingerprint exists in cache
        alt Fingerprint found in Redis
            Redis->>Completer: Return cached session_id
            Completer->>Guard: Return (applied: true, action: "reused_fingerprint_cache")
        else Fingerprint not found OR Redis unavailable
            Completer->>Completer: Generate UUID v7
            Completer->>Redis: Store fingerprint->session_id mapping (if Redis available)
            Completer->>Guard: Return (applied: true, action: "generated_uuid_v7")
        end
        Completer->>Completer: Set session_id and x-session-id headers
        Completer->>Completer: Set prompt_cache_key in body
    end
    
    Guard->>Guard: Record completion action in special settings
    Guard->>Upstream: Forward request with completed identifiers
    Note over Guard,Upstream: Body NEVER contains metadata field
    Note over Guard,Upstream: Only session_id (header) and prompt_cache_key (body)

coderabbitai · 2026-01-12T19:40:46Z

📝 Walkthrough

概览

本PR引入Codex会话ID完成功能，包括数据库架构扩展、多语言消息支持、验证规则、类型定义，以及用于自动填充缺失的会话标识符和缓存管理的核心会话完成器逻辑。

变更

队列 / 文件	变更摘要
数据库迁移与架构 `drizzle/0054_tidy_winter_soldier.sql`, `drizzle/meta/0054_snapshot.json`, `drizzle/meta/_journal.json`	添加 `enable_codex_session_id_completion` 布尔列（默认为true，非空），完整的PostgreSQL架构快照（JSON格式），及迁移日志条目
国际化消息 `messages/en/settings/config.json`, `messages/ja/settings/config.json`, `messages/ru/settings/config.json`, `messages/zh-CN/settings/config.json`, `messages/zh-TW/settings/config.json`	在5种语言的配置文件中添加 `enableCodexSessionIdCompletion` 和 `enableCodexSessionIdCompletionDesc` 的UI标签和描述文本
类型与接口定义 `src/types/special-settings.ts`, `src/types/system-config.ts`	新增 `CodexSessionIdCompletionSpecialSetting` 类型，扩展 `SpecialSetting` 联合类型；在 `SystemSettings` 和 `UpdateSystemSettingsInput` 接口中添加 `enableCodexSessionIdCompletion` 字段
验证与缓存配置 `src/lib/validation/schemas.ts`, `src/lib/config/system-settings-cache.ts`, `src/lib/utils/special-settings.ts`	在验证架构中添加可选布尔字段，更新系统设置缓存默认值，为 `buildSettingKey` 添加 `codex_session_id_completion` 序列化分支
数据访问层 `src/repository/system-config.ts`, `src/repository/message.ts`, `src/repository/_shared/transformers.ts`	在系统配置读写路径中增加新字段支持，为消息请求创建时添加 `special_settings` 处理，完善SystemSettings有效负载变换
应用逻辑与操作 `src/actions/system-config.ts`, `src/drizzle/schema.ts`	在 `saveSystemSettings` 操作中传递 `enableCodexSessionIdCompletion`；在Drizzle架构定义中添加相应的系统设置表字段
核心会话完成器模块 `src/app/v1/_lib/codex/session-completer.ts`	实现Codex会话ID完成逻辑，包括类型定义、Redis支持的指纹缓存、UUID v7生成、头部/请求体标识符同步和可观测结果追踪
会话守卫与代理集成 `src/app/v1/_lib/proxy/session-guard.ts`, `src/app/v1/_lib/proxy/message-service.ts`	在会话守卫中检查启用状态并调用会话完成器，记录完成结果为特殊设置；向消息请求有效负载添加 `special_settings` 字段
系统设置UI组件 `src/app/[locale]/settings/config/_components/system-settings-form.tsx`, `src/app/[locale]/settings/config/page.tsx`	在表单接口中添加 `enableCodexSessionIdCompletion` prop，在本地状态中管理该字段，添加带标签、描述和开关的UI元素
测试与配置 `tests/unit/codex/session-completer.test.ts`, `vitest.codex-session-id-completer.config.ts`, `package.json`	新增包含555行的综合单元测试套件验证会话完成逻辑、边界情况和Redis集成；配置专用Vitest运行器和npm脚本；简化现有测试中的消息加载
测试文件清理 `tests/unit/settings/providers/model-multi-select-custom-models-ui.test.tsx`, `tests/unit/usage-doc/opencode-usage-doc.test.tsx`	用共享测试助手替代本地文件系统消息加载；修正OpenAI npm条目的测试期望断言

估计代码审查工作量

🎯 3 (Moderate) | ⏱️ ~25 minutes

可能相关的PR

feat: thinking signature rectifier #576: 两个PR都添加新系统级特性标志，并在多个层级进行平行变更（系统设置表、验证、缓存、类型、UI和数据库访问代码）
feat: 审计并展示供应商级参数覆写（specialSettings） #557: 两个PR都修改 specialSettings/special_settings 特性（数据库列、消息请求有效负载、特殊设置类型和会话API），具有直接代码关联
feat: optionally intercept Anthropic warmup requests #525: 两个PR都修改代理会话守卫和系统设置处理，添加新的布尔标志并更新会话守卫逻辑

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题清晰准确地总结了本次修改的主要内容：修复Codex会话完成功能不应该注入metadata字段的问题。
Description check	✅ Passed	The pull request description clearly relates to the changeset, detailing a bug fix for Codex session ID completion that stops injecting metadata and limits writes to supported fields.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/codex-session-id-completion-auto-fill

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist · 2026-01-12T19:41:08Z

Summary of Changes

Hello @ding113, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a critical fix and enhancement for handling Codex API requests. Previously, requests were failing due to an unsupported metadata field. This PR removes the problematic field and implements a robust session identifier completion mechanism. For Codex requests, it now ensures that both the session_id header and prompt_cache_key in the request body are consistently populated. If one is present, it's used to fill the other; if both are missing, a stable UUID v7 is generated and persisted across similar requests using a fingerprinting cache. This significantly improves the reliability and session continuity of Codex interactions, and the feature can be toggled via a new system setting.

Highlights

Codex metadata Field Removal: The metadata field is no longer injected into Codex request bodies, resolving a 400: Unsupported parameter error from the upstream Codex API.
Enhanced Session ID Completion: Implemented logic to automatically complete missing session_id (header) or prompt_cache_key (body) for Codex requests. If both are absent, a stable UUID v7 is generated.
Fingerprint-based Session Stability: Utilizes a Redis-backed fingerprinting cache to ensure consistent UUID v7 session IDs are reused for similar Codex requests, improving session stickiness.
New System Setting: A new system setting, enableCodexSessionIdCompletion, is introduced (defaulting to true) to allow administrators to control this session completion behavior.
Comprehensive Testing: New unit tests specifically cover the Codex session completion logic, ensuring correctness and preventing regressions, with a dedicated coverage gate.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request effectively resolves the issue where metadata was being incorrectly injected into Codex API requests, causing upstream errors. The core of the change is the new codex-session-id-completer, which robustly ensures that both session_id (header) and prompt_cache_key (body) are present and consistent. The implementation includes a smart fallback mechanism that uses request fingerprinting and Redis to generate stable session IDs when they are missing, falling back to a UUID v7 if needed. The changes are well-integrated with a new system setting, UI toggle, and comprehensive unit tests that validate the new logic and confirm that metadata is no longer modified. The code is clean, well-structured, and the addition of a dedicated test coverage script is a great practice.

gemini-code-assist · 2026-01-12T19:42:43Z

src/types/special-settings.ts

+    | "header_session_id"
+    | "header_x_session_id"
+    | "body_prompt_cache_key"
+    | "body_metadata_session_id"


The source type for CodexSessionIdCompletionSpecialSetting includes body_metadata_session_id. The implementation in session-completer.ts correctly avoids reading from metadata, which aligns with this PR's goal to prevent issues with the Codex upstream API. To maintain consistency and avoid confusion, this unused source type should be removed.

github-actions

Code Review Summary

This PR adds a new system setting enableCodexSessionIdCompletion to control automatic session ID completion for Codex requests. The implementation is well-structured with proper database migration, type definitions, i18n support, and comprehensive test coverage.

PR Size: XL

Lines changed: 3444 (3426 additions, 18 deletions)
Files changed: 28

Note on size: The large line count is primarily due to the auto-generated Drizzle snapshot file (drizzle/meta/0054_snapshot.json ~2388 lines). The actual implementation changes are reasonable in scope.

Issues Found

Category	Critical	High	Medium	Low
Logic/Bugs	0	0	0	0
Security	0	0	0	0
Error Handling	0	0	0	0
Types	0	0	0	0
Comments/Docs	0	0	0	0
Tests	0	0	0	0
Simplification	0	0	0	0

Review Coverage

Logic and correctness - Clean
Security (OWASP Top 10) - Clean
Error handling - Clean (Redis failures gracefully fall back to UUID v7 generation with proper logging)
Type safety - Clean
Documentation accuracy - Clean
Test coverage - Comprehensive (dedicated vitest config with 80% threshold)
Code clarity - Good

Implementation Highlights

Session Completer Logic (src/app/v1/_lib/codex/session-completer.ts):
- Properly handles all edge cases: missing headers, missing body fields, invalid session IDs
- Redis fingerprint caching with NX race condition handling
- Graceful fallback to UUID v7 when Redis is unavailable
- Error logging without silent failures
Database Migration (drizzle/0054_tidy_winter_soldier.sql):
- Simple ALTER TABLE adding boolean column with sensible default (true)
- Non-breaking change with backward compatibility
Test Coverage (tests/unit/codex/session-completer.test.ts):
- 18 test cases covering:
  - Header-to-body completion
  - Body-to-header completion
  - UUID v7 generation
  - Redis fingerprint caching and reuse
  - Redis NX race conditions
  - Redis failure fallback
  - Invalid session ID handling
- Tests explicitly verify metadata is never added/modified (per PR description)
i18n Support:
- All 5 required languages updated (en, ja, ru, zh-CN, zh-TW)
Type Safety:
- New CodexSessionIdCompletionSpecialSetting type properly defined
- SystemSettings interface updated with new field
- Validation schema includes the new boolean field

Verification Notes

The PR correctly addresses the stated goal: Codex upstream rejects metadata field, so the session completer now only writes to session_id header and prompt_cache_key body field
Tests explicitly assert expect(body.metadata).toBeUndefined() in relevant cases
The feature is toggleable via system settings with a sensible default (enabled)

Automated review by Claude AI

greptile-apps

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

coderabbitai

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

src/app/v1/_lib/proxy/message-service.ts (1)
24-32: 删除注释中的 emoji（⭐）

按规范 **/*.{ts,tsx,js,jsx} 代码、注释和字符串中不能出现 emoji，需要移除第 24 行注释中的 "⭐" 字符。
修改建议
-    // ⭐ 修复模型重定向记录问题：
+    // 修复模型重定向记录问题：
     // 由于 ensureContext 在模型重定向之前被调用（guard-pipeline 阶段），
     // 此时 session.getOriginalModel() 可能返回 null。
     // 因此需要在这里提前保存当前模型作为 original_model，
     // 如果后续发生重定向，ModelRedirector.apply() 会再次调用 setOriginalModel()（幂等性保护）
src/lib/config/system-settings-cache.ts (1)
27-48: 避免返回共享的默认对象引用（responseFixerConfig）

在兜底返回里直接复用 DEFAULT_SETTINGS.responseFixerConfig 可能导致下游误改对象后“污染默认值/跨请求泄露”。建议返回时做一次浅拷贝（该配置目前是扁平结构）。
Proposed diff
     return {
       id: 0,
       siteTitle: "Claude Code Hub",
       allowGlobalUsageView: false,
       currencyDisplay: "USD",
       billingModelSource: "original",
       verboseProviderError: false,
       enableAutoCleanup: false,
       cleanupRetentionDays: 30,
       cleanupSchedule: "0 2 * * *",
       cleanupBatchSize: 10000,
       enableClientVersionCheck: false,
       enableHttp2: DEFAULT_SETTINGS.enableHttp2,
       interceptAnthropicWarmupRequests: DEFAULT_SETTINGS.interceptAnthropicWarmupRequests,
       enableThinkingSignatureRectifier: DEFAULT_SETTINGS.enableThinkingSignatureRectifier,
       enableCodexSessionIdCompletion: DEFAULT_SETTINGS.enableCodexSessionIdCompletion,
       enableResponseFixer: DEFAULT_SETTINGS.enableResponseFixer,
-      responseFixerConfig: DEFAULT_SETTINGS.responseFixerConfig,
+      responseFixerConfig: { ...DEFAULT_SETTINGS.responseFixerConfig },
       createdAt: new Date(),
       updatedAt: new Date(),
     } satisfies SystemSettings;
Also applies to: 93-114
src/types/special-settings.ts (1)

8-16: source 在 special-settings.ts 中包含 "body_metadata_session_id"，与实际实现不符

实际的 Codex 会话完成逻辑（session-completer.ts）中定义的 CodexSessionCompletionSource 类型不包含 "body_metadata_session_id"，只支持 header_session_id / header_x_session_id / body_prompt_cache_key / fingerprint_cache / generated_uuid_v7。而 special-settings.ts 中的审计类型定义（line 130）仍然包含此源。

虽然 session-extractor.ts 确实会读取 body.metadata.session_id 作为第四优先级的备用源，但该值永远不会被转发到 Codex 上游（测试中明确验证 expect(body.metadata).toBeUndefined()），所以 PR 目标（禁止 metadata 转发）已正确实现。问题在于类型定义过于宽泛，导致混淆：审计记录的 source 类型应与实际完成流程使用的源保持一致。

建议：移除 special-settings.ts 中 CodexSessionIdCompletionSpecialSetting.source 的 "body_metadata_session_id" 项（line 130），确保类型定义与 session-completer.ts 的 CodexSessionCompletionSource 保持一致。

🤖 Fix all issues with AI agents

In @src/app/v1/_lib/codex/session-completer.ts:
- Around line 216-297: sanitizeCodexRequest is not stripping
requestBody.metadata so upstream receives an unsupported "metadata" param;
update the unsupportedParams list (used inside sanitizeCodexRequest in
request-sanitizer.ts) to include "metadata" so the sanitizer removes any
requestBody.metadata before forwarding, and ensure any tests or callers that
rely on unsupportedParams behavior still pass.

In @tests/unit/codex/session-completer.test.ts:
- Around line 95-116: The test uses a literal UUID in promptCacheKey which
triggers Gitleaks; change the literal to be constructed (e.g., join/split
smaller string constants or concatenate substrings) so no full token appears as
a single string literal; update occurrences referenced by the test "completes
header session_id from body.prompt_cache_key", the promptCacheKey variable, and
any other tests using the same UUID (the other block around the
makeCodexRequestBody usage) to build the ID at runtime instead of embedding the
full UUID.

🧹 Nitpick comments (12)

drizzle/0054_tidy_winter_soldier.sql (1)

1-1: 迁移语义 OK，但需关注大表加列的锁/耗时风险

DEFAULT true NOT NULL 对功能默认开启很合理；如果 system_settings 在生产环境行数较大或数据库版本/参数不确定，建议在发布前确认该 DDL 是否会触发表重写/长锁（必要时采用“先加 nullable 列 + 回填 + 再设 NOT NULL/default”的两步/三步迁移策略）。

messages/zh-CN/settings/config.json (1)

43-44: 文案与“禁止 metadata 注入”的目标一致，建议统一术语格式

这里的描述只涉及 session_id（请求头）与 prompt_cache_key（请求体），没有引入 metadata，方向正确；可考虑在中英文里统一 “session id / Session ID” 的大小写与 “UUID v7” 表述风格，避免 UI 文案不一致。

tests/unit/usage-doc/opencode-usage-doc.test.tsx (1)

73-73: 测试期望更新合理，但注意 textContent 子串断言的脆弱性

从“应包含 OpenAI npm 包”角度看，这个断言更新是合理的；如果后续文档格式化/换行调整导致波动，建议改成提取并解析对应 JSON 片段后再断言字段存在（可选）。

messages/en/settings/config.json (1)

54-55: i18n 键补齐到位，描述与接口约束一致

新增的英文文案没有提到 metadata，并明确只围绕 header 的 session_id 与 body 的 prompt_cache_key，与本 PR 目标一致；可选：统一 “session id / Session ID” 的大小写风格以保持全站一致。

tests/unit/settings/providers/model-multi-select-custom-models-ui.test.tsx (1)

11-12: 改用测试消息加载器是正确方向；建议确认返回值不共享可变状态

这次改动能避免测试依赖文件系统 I/O，整体更稳定。建议确认 loadTestMessages("en") 每次返回的 messages 不会被（或不可能被）运行时修改导致跨用例污染；如存在风险，可在 helper 内做深拷贝/冻结。

Also applies to: 55-60

messages/ru/settings/config.json (1)

54-55: 新增 RU 文案键值 OK；建议统一术语/字段名呈现方式

已按 i18n 方式补齐文案。建议对“Session ID/UUID v7/对话”的俄语表述与其他语言保持一致，并确认 UI 中字段名是否需要保留 session_id/prompt_cache_key 原样（代码字段）还是做更友好的解释。

messages/zh-TW/settings/config.json (1)

54-55: zh-TW 新增配置文案 OK；留意描述长度在 UI 上的可读性

键名与语义清晰，符合 i18n 约束。可顺便确认该段较长描述在设置页是否会出现排版/换行可读性问题（必要时在 UI 组件侧处理）。

messages/ja/settings/config.json (1)

54-55: ja 新增配置文案 OK；建议核对“同一对话内稳定复用”的语义一致性

新增键值符合 i18n 结构，内容表达基本到位。建议与其他语言对照确认“同一対話内で安定して再利用”是否与实际实现/产品定义完全一致。
src/repository/message.ts (1)
20-41: specialSettings 写入建议保留 null/undefined 语义（若上游类型区分二者）

这里用 data.special_settings ?? undefined 会把显式 null 折叠成 undefined。如果该仓库对 null/undefined 有语义区分（例如“显式清空” vs “不传不改”），建议按类型语义直传。基于该仓库对 null/undefined 语义区分的既有实践（见 learnings），这里最好确认一致性。
建议改动（如类型允许）
-    specialSettings: data.special_settings ?? undefined, // 特殊设置（审计/展示）
+    specialSettings: data.special_settings, // 特殊设置（审计/展示）
vitest.codex-session-id-completer.config.ts (1)
11-11: 配置文件默认导出可接受，但建议同时提供具名导出以贴合规范

你们规范里偏好具名导出；但 Vitest config 通常需要 default export。可以保留 default，同时额外导出一个具名常量供复用/类型引用。
建议修改
-export default defineConfig({
+export const codexSessionIdCompleterVitestConfig = defineConfig({
   test: {
     globals: true,
     environment: "happy-dom",
@@
   },
   resolve: {
     alias: {
       "@": path.resolve(__dirname, "./src"),
       "server-only": path.resolve(__dirname, "./tests/server-only.mock.ts"),
     },
   },
 });
+
+export default codexSessionIdCompleterVitestConfig;
src/app/v1/_lib/proxy/session-guard.ts (1)
5-5: 新增 import 建议改用 @/ 路径别名，保持项目一致性。

当前 ../codex/session-completer 与“使用 @/ 引用 src 下文件”的规范不一致。
建议修改
-import { completeCodexSessionIdentifiers } from "../codex/session-completer";
+import { completeCodexSessionIdentifiers } from "@/app/v1/_lib/codex/session-completer";
src/app/v1/_lib/codex/session-completer.ts (1)

150-205: 避免最后一次无 NX 的 SET：存在覆盖并发写入的风险

在 SET ... NX 失败且二次 GET 仍为空时（Line 193-194），直接 SET（无 NX）可能覆盖另一个并发请求刚写入的值；建议改为再次 SET ... NX / 或直接放弃写入并返回 candidate（让下次请求再尝试），以消除覆盖风险。

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to Reviews > Disable Cache setting

📥 Commits

Reviewing files that changed from the base of the PR and between 464449e and 2b17fc4.

📒 Files selected for processing (28)

drizzle/0054_tidy_winter_soldier.sql
drizzle/meta/0054_snapshot.json
drizzle/meta/_journal.json
messages/en/settings/config.json
messages/ja/settings/config.json
messages/ru/settings/config.json
messages/zh-CN/settings/config.json
messages/zh-TW/settings/config.json
package.json
src/actions/system-config.ts
src/app/[locale]/settings/config/_components/system-settings-form.tsx
src/app/[locale]/settings/config/page.tsx
src/app/v1/_lib/codex/session-completer.ts
src/app/v1/_lib/proxy/message-service.ts
src/app/v1/_lib/proxy/session-guard.ts
src/drizzle/schema.ts
src/lib/config/system-settings-cache.ts
src/lib/utils/special-settings.ts
src/lib/validation/schemas.ts
src/repository/_shared/transformers.ts
src/repository/message.ts
src/repository/system-config.ts
src/types/special-settings.ts
src/types/system-config.ts
tests/unit/codex/session-completer.test.ts
tests/unit/settings/providers/model-multi-select-custom-models-ui.test.tsx
tests/unit/usage-doc/opencode-usage-doc.test.tsx
vitest.codex-session-id-completer.config.ts

🧰 Additional context used

📓 Path-based instructions (8)

**/*.{js,ts,tsx,jsx}