Release Notes
中文
新增
- 新增仓库内
codex-session-diagnostics skill，可按 Codex session key 只读收集 ~/.codex-helper 日志/状态/配置和 ~/.codex 会话 JSONL，辅助定位 waiting、resume、stream、routing affinity 和 relay 连续性问题。
- 新增容器优先的中央 relay runtime：
codex-helper-server、cargo-chef Dockerfile、Synology-friendly Compose 示例、容器 server 配置和 Docker 部署文档。容器启动 proxy/admin API，不会 patch 宿主机的 ~/.codex/config.toml 或 auth.json。
- 新增本机保存的 relay target 工作流：
ch relay add/list/status/off/use 和短入口 ch relay <target>。local 是内置本机 target；命名 target 可指向 NAS、Tailscale 或 LAN 上的 helper runtime，并支持 --no-tui switch-only、--attach-only observe-only，以及只保存环境变量名的 admin_token_env。
- 新增 GHCR Docker 发布 workflow：
v* tag、GitHub Release 发布和手动 dispatch 可构建/发布 ghcr.io/<owner>/codex-helper-server，PR 只做 Docker build/smoke，不推送镜像；稳定 tag 会额外发布 latest，预发布 tag 不会覆盖 latest。
变更
- 本地桌面 CLI 和容器 server 的职责边界进一步拆开：本地
ch、serve、switch 仍负责本机 client patch 和 TUI 生命周期；容器/server runtime 只暴露 proxy/admin control-plane。远端 attached TUI 现在通过 resolved admin URL 和可选 admin token env 观察目标 proxy，不再假设 admin API 一定在本机 loopback。
- control-plane 的
station/config 语义收口到 station-first 口径；GUI/TUI/tray/请求详情不再把默认站点、上次观测站点或旧 route-attempt 投影显示成 active_station / legacy / config 文案，operator/summary 回归断言也补强为显式拒绝旧 session-card、link 和 capability key。
- TUI 第 5 页用户可见名称统一为
Usage / 用量 口径；Recent/History 都明确标注为 Codex 全局会话，Recent 页 footer 也补齐 s/f/h 跳转提示。Usage / Balance 预测现在会显示样本来源来自当前 runtime 还是本地 request ledger，Requests 页在从 Codex 历史会话跳入且当前 runtime 未观测到请求时会给出明确空态说明，避免启动后把历史数据误认成当前会话请求。
修复
- 修复 Codex
/responses / /responses/compact 流式请求在上游已返回 HTTP 200 但后续 SSE body 长时间无字节时会无限 waiting 的问题；现在默认 900 秒 idle watchdog 会用 Codex 可解析的 response.failed 结束流，并在日志中记录 codex_helper_error=upstream_stream_idle_timeout。可用 CODEX_HELPER_STREAM_IDLE_TIMEOUT_SECS=0 关闭，或设置秒数覆盖默认值。
- TUI 的 Recent/History/Requests/Sessions 现在先在
UiState 里同步选择和表格状态，再交给 render 消费；Usage 预测样本来源也改成显式模型，不再通过 Vec 长度推断是否带上本地 request ledger。
- 修复交互式 TUI/runtime 日志只在启动时检查大小的问题；
runtime.log 现在会在运行过程中按 CODEX_HELPER_RUNTIME_LOG_MAX_BYTES / CODEX_HELPER_RUNTIME_LOG_MAX_FILES 持续轮转，并且升级后会在下次启动时清理超过保留预算的历史 runtime.log.*，避免老用户遗留的巨型日志继续占用磁盘。
- 修复轮转日志清理在 Windows 上遇到占用或删除失败时会把文件大小误算为已释放的问题；删除失败的
runtime.log.* / control_trace.*.jsonl 会继续保留预算压力，清理会尝试后续候选，并在下次 repair 时重试，避免旧用户升级后仍残留超大轮转文件。
- 将 runtime、GUI、request/debug、control trace、retry trace 和 Codex relay evidence 统一到有界本地日志存储；
control_trace.jsonl 等 JSONL 日志现在会在首次写入时按 CODEX_HELPER_REQUEST_LOG_MAX_BYTES / CODEX_HELPER_REQUEST_LOG_MAX_FILES 轮转并清理历史轮转文件，gui.log 和 relay evidence 也新增独立大小上限，降低老用户日志目录继续膨胀的风险。
- request ledger、control trace 和 Codex relay evidence 的读取入口现在也会先执行同一套有界日志修复；老用户升级后即使先打开 GUI/管理 API/CLI 查看日志、尚未产生新的写入，遗留的超大 active JSONL 也会按保留策略轮转清理，避免读取最近记录时完整扫描巨型文件。
- TUI/管理 API 的 Sessions 列表不再把仅由持久化 route affinity 恢复出来的旧 session 当作当前运行期已观测会话展示；恢复的 affinity 仍保留用于后续 remote compaction 连续性，但只有 session 被当前运行期请求、统计或显式 override 触达后才会显示。
重构
- 收口 route graph 与 legacy routing compat 的 authoring 边界；CLI、GUI 和 admin API 现在通过
RoutingConfigV4 / ServiceViewV4 的语义方法更新 entry route、provider 引用和手动 target，而不是在调用点手动修改字段后同步兼容字段。
- 新增
RequestLedgerStore 作为 request ledger 读模型边界；CLI、TUI、GUI 和 admin API 现在通过统一 store 读取 tail、filter 和 summary，最近记录与过滤查询改为流式保留窗口，避免只为读取最近 N 条就加载完整 requests.jsonl。
- 拆分 Codex relay live-smoke case registry；case 描述、HTTP spec 和诊断请求体迁移到独立
codex_relay_live_smoke::cases 模块，主模块保留 proxy orchestration、transport 和 response classification。
English summary
Added
- Added the repository
codex-session-diagnostics skill for read-only collection of ~/.codex-helper logs/state/config and ~/.codex session JSONL files from a Codex session key, helping diagnose waiting, resume, stream, routing-affinity, and relay-continuity failures.
- Added a container-first central relay runtime:
codex-helper-server, a cargo-chef Dockerfile, Synology-friendly Compose samples, container server config, and Docker deployment docs. The container starts only the proxy/admin APIs and does not patch the host machine's ~/.codex/config.toml or auth.json.
- Added client-side relay targets:
ch relay add/list/status/off/use and the shorthand ch relay <target>. local is the built-in local target; named targets can point at NAS, Tailscale, or LAN helper runtimes with --no-tui switch-only, --attach-only observe-only, and admin_token_env storing only the token environment variable name.
- Added a GHCR Docker publishing workflow.
v* tags, published GitHub Releases, and manual dispatches can build/publish ghcr.io/<owner>/codex-helper-server; PRs perform Docker build/smoke only. Stable tags also publish latest, while prerelease tags do not overwrite latest.
Fixed
- Fixed Codex
/responses / /responses/compact streams waiting forever when an upstream returns HTTP 200 and then stops producing SSE body bytes. A 900-second idle watchdog now finishes the client stream with a Codex-parseable response.failed event and logs codex_helper_error=upstream_stream_idle_timeout; set CODEX_HELPER_STREAM_IDLE_TIMEOUT_SECS=0 to disable it or set a custom timeout in seconds.
- TUI Recent/History/Requests/Sessions now sync selection and table state inside
UiState before render consumes them; Usage forecast sample provenance is now explicit instead of inferred from Vec length.
- Fixed interactive TUI/runtime log rotation only checking file size at startup.
runtime.log now rotates while the process is running according to CODEX_HELPER_RUNTIME_LOG_MAX_BYTES / CODEX_HELPER_RUNTIME_LOG_MAX_FILES, and upgrades clean up historical runtime.log.* files that exceed the retention budget on the next startup so oversized legacy logs do not keep consuming disk space.
- Fixed bounded-log pruning accounting when Windows cannot delete a rotated file because it is still open. Failed deletes no longer count as recovered budget, later rotated candidates are still pruned, and the oversized file is retried on the next repair.
- Unified runtime, GUI, request/debug, control trace, retry trace, and Codex relay evidence writes behind a bounded local log store. JSONL logs such as
control_trace.jsonl now rotate and prune historical rotated files on first write according to CODEX_HELPER_REQUEST_LOG_MAX_BYTES / CODEX_HELPER_REQUEST_LOG_MAX_FILES, while gui.log and relay evidence gained their own size limits to reduce continued log directory growth for existing users.
- Request ledger, control trace, and Codex relay evidence readers now run the same bounded-log repair before scanning. Existing users who open the GUI, admin API, or CLI before a new write is produced will still have oversized active JSONL logs rotated and pruned instead of fully scanned for recent records.
- TUI/admin Sessions no longer display old sessions that were restored only from persisted route affinity. The restored affinity is still kept for later remote-compaction continuity, but a session is shown only after the current runtime observes requests, stats, or explicit overrides for it.
Changed
- Split the local desktop CLI responsibilities from the container server runtime. Local
ch, serve, and switch continue to own local client patching and TUI lifecycle, while the container/server runtime exposes only proxy/admin control-plane APIs. Remote attached TUI now observes a target proxy through a resolved admin URL and optional admin-token environment variable instead of assuming loopback admin access.
- Closed the control-plane
station/config semantic tail around station-first wording. GUI/TUI/tray/request-detail surfaces no longer present default stations, last observed stations, or legacy route-attempt projections as active_station / legacy / config labels, and operator/summary regressions now explicitly reject old session-card, link, and capability keys.
- Standardized the TUI page-5 user-facing label around
Usage / Usage / Balance. Recent and History now both identify their Codex-global session scope, the Recent footer advertises the s/f/h navigation keys, Usage / Balance spend forecasts show whether their sample comes from the current runtime or the local request ledger, and Requests explains when a focused Codex-history session has no requests observed by the current runtime.
- Consolidated the route graph and legacy routing compatibility authoring boundary. CLI, GUI, and admin API callers now update entry routes, provider references, and manual targets through semantic
RoutingConfigV4 / ServiceViewV4 methods instead of mutating fields and synchronizing compatibility state at each call site.
- Added
RequestLedgerStore as the request ledger read-model boundary. CLI, TUI, GUI, and admin API consumers now read tail, filter, and summary data through one store, and recent/filter queries use a streaming bounded window instead of loading the full requests.jsonl just to return the newest records.
- Split the Codex relay live-smoke case registry. Case descriptors, HTTP specs, and diagnostic request bodies now live in a dedicated
codex_relay_live_smoke::cases module while the main module keeps proxy orchestration, transport, and response classification.
Install codex-helper 0.18.0
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Latias94/codex-helper/releases/download/v0.18.0/codex-helper-installer.sh | sh
Install prebuilt binaries via powershell script
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Latias94/codex-helper/releases/download/v0.18.0/codex-helper-installer.ps1 | iex"
Download codex-helper 0.18.0
