[CPbianma]

Summary

A Desktop reconnect can attach to an online shared Host whose official Codex process still refers to files removed by a Desktop update. The interface can appear ready while a later native tool fails to spawn its missing codex-code-mode-host.exe.

Track the files present when each actual official backend generation is created. Before Desktop admission retains that running generation, check those files and reject stale reuse with a fixed recovery instruction. Existing idle configuration replacement remains available, and active official work is preserved until the user chooses to stop/restart Host. Optional companions absent when a generation starts remain optional.

Carry only the fixed recovery text through the authenticated WebSocket close reason; make abnormal bridge closure return failure and expose that recovery text. Create the per-Desktop AppServerHost only after admission succeeds, so rejected reconnects do not leak client/delegation registrations.

This change does not modify login scheduling, extend the 30-second Host-chain deadline, or claim to resolve every cold-start timeout. It detects missing files, not binary version replacement at the same path.

Related issues

Fixes #812

Test plan

• npm run build:typescript and npm run typecheck passed.
• Focused Vitest suites: native-account-host.test.ts, local-shared-host.test.ts, remote-app-server.test.ts: 32 passed, 10 platform-specific tests skipped on Windows.
• The new tests were run against the old behavior first: stale retention resolved instead of rejecting; the abnormal transport test timed out; the real Desktop admission test exposed a leaked delegation registration. All pass with the final patch.
• ESLint on all changed TypeScript files, the repository dependency-boundary checker, Prettier, and git diff --check passed.
• Tests use real temporary runtime files and an authenticated loopback Desktop transport with synthetic native backends. They cover active-work preservation, idle A-to-B replacement, current-generation tracking, optional companions, nonzero failure/recovery text, and rejected-session cleanup.
• No live Desktop/Store update or OS reboot was performed with this source patch. macOS/Linux execution is left to CI. The original Windows incident was recovered with the existing release through an explicit Host restart, separately from this patch.

[coderabbitai]

Summary

Summary by CodeRabbit

• 功能改进
  • Desktop 重连时，如果仍在运行的后台所需文件已缺失，会显示恢复提示并保留现有后台与任务。
  • 按提示运行 codexhost stop 后重启，可恢复后台；空闲后台切换配置时会重新记录所需文件。
• 注意事项
  • 若文件在原路径被替换，系统不会检测其版本变化。

新增后台运行时文件记录与检查。Desktop 接入时，若保留的后台代次文件缺失，系统会拒绝该配置，并将专用错误传递给 Desktop bridge。空闲后台仍可按现有路径切换配置。

Changes: 后台代次检查与 Desktop 接入

Layer / File(s)	Summary
记录并检查后台运行时文件 packages/host-runtime/src/codex-runtime/backend-files.ts, packages/host-runtime/src/native-account-host.ts, packages/host-runtime/test/native-account-host.test.ts, docs/product/standalone-web.md	新增运行时文件记录和存在性检查。后台运行且配置未变化，或存在活动任务时，检查已记录的文件。测试覆盖文件缺失、Windows companion 文件和空闲后台替换；文档说明恢复方式及检查限制。
按次创建 Desktop Host packages/host-runtime/src/shared-host-desktop.ts	每次 run 在启动配置完成后创建 Host。disconnect 和 close 会先标记连接已关闭，再处理已创建的 Host。
传递运行时文件移除错误 packages/host-runtime/src/remote-app-server-session.ts, packages/host-runtime/src/local-shared-host.ts, packages/host-runtime/test/local-shared-host.test.ts	特定错误会通过 WebSocket 的 1011 关闭消息传递。Desktop bridge 将错误消息写入标准错误，并以状态码 1 结束；新增测试验证该路径及服务状态。

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant NativeAccountHost
  participant RemoteAppServerSession
  participant LocalSharedHost
  participant runLocalDesktopBridge
  NativeAccountHost->>RemoteAppServerSession: 配置时检查后台运行时文件
  RemoteAppServerSession->>LocalSharedHost: 错误时以 1011 和固定消息关闭 WebSocket
  LocalSharedHost->>runLocalDesktopBridge: 传递 CodexRuntimeFilesRemovedError
  runLocalDesktopBridge->>runLocalDesktopBridge: 输出错误消息并以状态码 1 结束

Loading

Possibly related PRs

• BytePioneer-AI/codex-host#772: 涉及共享 Host、official app-server 和原生 Codex 代次的读取与操作，与本 PR 的后台代次保留和恢复行为相关。

Suggested reviewers: bytepioneer-ai

Merge Risk: Minimal · up to ff03e

The change rejects stale official backend reuse with a clear recovery message and preserves active work. No merge-blocking risk was identified.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		标题准确概括了主要变更：阻止 Desktop 重用已删除 Codex runtime 文件的 Host。标题简洁且与变更内容直接相关。
Description check		描述明确说明了运行时文件跟踪、过期复用拒绝、恢复提示、活动任务保留、WebSocket 错误传递和 Host 创建延迟，内容与变更集相关。
Linked Issues check		PR 满足直接关联的 #812 编码要求。captureCodexRuntimeFiles 记录官方后台代次创建时存在的运行时文件；assertCodexRuntimeFilesPresent 在 Desktop admission 时拒绝缺失文件。活动工作仍保留，空闲配置变化仍使用现有替换路径。remote-app-server-session.ts 仅传递固定恢复文本，`local…
Out of Scope Changes check		未发现与 #812 无关的变更。运行时文件检查、WebSocket 错误传递、Desktop bridge 失败处理、延迟 AppServerHost 创建，以及对应测试和文档，均直接支持 #812 的修复范围。PR 也明确未修改登录调度、30 秒超时或同路径二进制替换检测。

Full details: Linked Issues check

Explanation

PR 满足直接关联的 #812 编码要求。captureCodexRuntimeFiles 记录官方后台代次创建时存在的运行时文件；assertCodexRuntimeFilesPresent 在 Desktop admission 时拒绝缺失文件。活动工作仍保留，空闲配置变化仍使用现有替换路径。remote-app-server-session.ts 仅传递固定恢复文本，local-shared-host.ts 将该异常转换为失败状态并输出恢复文本。shared-host-desktop.ts 在 admission 成功后才创建 AppServerHost，因此拒绝的会话不会注册 delegation。新增和更新的 Vitest 测试覆盖缺失文件、活动工作、可选 companion、失败文本和拒绝会话清理。

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[coderabbitai]

Additional comments: 1

packages/host-runtime/src/codex-runtime/backend-files.ts: 1

23-24: Trivial · Performance & Scalability · Quick win

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

建议将 Desktop 接入时的文件检查改为异步 I/O。

configureStartup 在连接接入路径调用此函数。existsSync 会阻塞共享 Host 的事件循环；磁盘检查延迟期间，其他连接和任务的回调也无法执行。建议使用 node:fs/promises，并让调用方等待检查结果。改动时需在异步检查后确认后台代次未变化。同步文件 API 的阻塞行为见官方文档。(nodejs.org)

依据检索学习：“避免在服务端请求处理路径使用同步 fs 函数”。

Source: Learnings

Review info

Run configuration

• Source mode: Auto
• Repository: BytePioneer-AI/codex-host
• Branch: main
• File: .coderabbit.yaml
• Commit: 5684c9e
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: c6636d97-5f3b-4338-9fde-f218bcb85853

Commits

Reviewing files that changed from the base of the PR and between 5684c9e and ff03e5d.

Files selected for processing: 8

• docs/product/standalone-web.md
• packages/host-runtime/src/codex-runtime/backend-files.ts
• packages/host-runtime/src/local-shared-host.ts
• packages/host-runtime/src/native-account-host.ts
• packages/host-runtime/src/remote-app-server-session.ts
• packages/host-runtime/src/shared-host-desktop.ts
• packages/host-runtime/test/local-shared-host.test.ts
• packages/host-runtime/test/native-account-host.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Review details

Context from checks skipped due to timeout: 4

• GitHub Check: CodeRabbit
• GitHub Check: Check ubuntu-22.04
• GitHub Check: Check windows-latest
• GitHub Check: Check macos-26

Additional context used

Code guidelines: 2

CLAUDE.md — auto-discovered
AGENTS.md — auto-discovered

Path-based instructions: 1

Source excerpt: Host Runtime loads installed plugins through public contracts, not direct imports of concrete Adapter packages.

CodeRabbit inference engine (CLAUDE.md)

Files:

• packages/host-runtime/src/remote-app-server-session.ts
• packages/host-runtime/src/shared-host-desktop.ts
• packages/host-runtime/src/native-account-host.ts
• packages/host-runtime/src/local-shared-host.ts
• packages/host-runtime/test/local-shared-host.test.ts
• packages/host-runtime/test/native-account-host.test.ts
• packages/host-runtime/src/codex-runtime/backend-files.ts

LanguageTool

docs/product/standalone-web.md

[uncategorized] ~52-~52: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：固定"地"恢复
Context: ...后台，会先检查这些文件；文件已被 Desktop 更新或清理移除时，连接返回固定的恢复提示和失败状态，现有 Host 与任务继续保留。确认可以中断后台任务后，运行...

(wb4)

---

[uncategorized] ~52-~52: 您的意思是“"不"齐”？
Context: ...提供的新配置，新的一代重新记录实际使用的文件；可选工具宿主在创建时不存在则不要求补齐。检查覆盖文件缺失，不检测同一路径内的文件版本替换。

(BU)