fix: carry ChatGPT launcher, SOCKS5 TLS deadline and 429 triage docs (#7055, #7056, #6925)

[lidge-jun]

Summary

Carries three contributor fixes onto an upstream branch so the repository CI runs them. Each one is a separate commit with a Co-authored-by trailer for its author. This is the non-auth part of #7062. The two Kiro commits from #7062 stay there for security review.

• fix(chatgpt): preserve launcher when app inspection fails #7055 by @lcxhh521: ocx chatgpt status reports an unknown state when app discovery or process inspection fails, instead of "not installed" or "not running". launch and restore refuse to change the launcher or reopen the app when they cannot confirm that the app has exited.
• fix(proxy): bound SOCKS5 TLS handshake lifetime #7056 by @lcxhh521: HTTPS over SOCKS5 gets an absolute 30-second TLS handshake deadline after SOCKS CONNECT. Before this, a stalled handshake depended only on the caller cancelling. Listeners and the socket are cleaned up on success, failure, abort and early close, and certificate verification stays on.
• docs: triage "exceeded retry limit, last status: 429 Too Many Requests" #6925 by @Howard-Jerry: the Codex retry diagnostics page gets a triage section for exceeded retry limit, last status: 429 Too Many Requests. It separates the local hard lock, an upstream plan window and a provider or transport incident.

Carries #7055, #7056, #6925.

Co-authored-by: lcxhh lcxhh521@gmail.com
Co-authored-by: Howard-Jerry 197214646+Howard-Jerry@users.noreply.github.com

Verification

These commits are cherry-picked unchanged from #7062, whose exact head 12f8ef22e passed full PR CI (ci, test 1–4, gates, structure gate, docs build and the rest). Rebased onto dev b28f23d78:

• bun test on socks5-tls-lifecycle, socks5-upload-lifecycle, desktop-app-server-shim-launcher, test-layout, test-layout-tooling and the file-size ratchet tests: 90 pass, 0 fail
• bun run typecheck, bun run structure:check and bun run privacy:scan pass
• Full local suite not run because several worktrees are running concurrently; exact-head CI on this PR is the gate.

Checklist

• Targets dev
• Focused regression tests included (from the source PRs)
• Docs and structure updated with the behavior
• No UI change
• Co-authored-by trailers for every carried author

Summary by CodeRabbit

• Bug Fixes

  • ChatGPT Desktop now reports its state as unknown when process inspection is inconclusive, rather than incorrectly reporting that it is not running.
  • Launch and restore stop when the app’s state or exit cannot be confirmed, helping avoid unintended changes to the launcher or app state.
  • SOCKS5 HTTPS connections now fail if the TLS handshake stalls, and can be stopped sooner by cancellation. Certificate verification remains enabled.

• Documentation

  • Clarified ChatGPT Desktop recovery behavior, SOCKS5 TLS timeouts, and troubleshooting steps for common Codex retry-limit errors.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T15:57:57.336087Z	4b18459	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 79a7bad4-e674-463b-903b-4dfa5d00232d

📥 Commits

Reviewing files that changed from the base of the PR and between b28f23d and 4b18459.

📒 Files selected for processing (12)

• docs-site/src/content/docs/guides/chatgpt-desktop.md
• docs-site/src/content/docs/reference/codex-retry-diagnostics.md
• docs-site/src/content/docs/reference/configuration/server.md
• scripts/test-layout/layout.json
• src/cli/chatgpt-command.ts
• src/lib/socks5-fetch.ts
• structure/clients/chatgpt-desktop.md
• structure/transports/inventory.md
• tests/clients/desktop-app-server-shim-launcher.test.ts
• tests/fixtures/test-layout-expected.json
• tests/helpers/desktop-app-server-shim-command-child.ts
• tests/lib/socks5-tls-lifecycle.test.ts

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

📝 Walkthrough

The changes update ChatGPT desktop process-state handling, add a bounded TLS handshake lifecycle for HTTPS over SOCKS5, and expand Codex retry-limit diagnostics. Tests cover desktop inspection failures and SOCKS5 TLS timeout and failure cases.

Changes: ChatGPT desktop process state

Layer / File(s)	Summary
Process inspection and command handling src/cli/chatgpt-command.ts	Discovery and inspection failures now produce unknown state rather than confirmed absence. Status reports unknown state. Launch, restore, and quit stop when required state checks or exit confirmation fail.
State validation and documentation tests/helpers/desktop-app-server-shim-command-child.ts, tests/clients/desktop-app-server-shim-launcher.test.ts, structure/clients/chatgpt-desktop.md, docs-site/src/content/docs/guides/chatgpt-desktop.md	Test fixtures simulate discovery and process-inspection failures. Tests check that commands preserve the launcher and avoid opening the app when state is uncertain. Documentation describes these behaviors and the non-transactional launcher update and restart.

SOCKS5 TLS handshake lifecycle

Layer / File(s)	Summary
TLS deadline and failure handling src/lib/socks5-fetch.ts, tests/lib/socks5-tls-lifecycle.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, docs-site/src/content/docs/reference/configuration/server.md, structure/transports/inventory.md	secureSocket bounds TLS handshakes with a separate deadline and handles aborts, TLS errors, and premature closure through a guarded failure path. Tests cover those failure cases. The test layout and documentation include the lifecycle test and deadline behavior.

Codex retry diagnostics

Layer / File(s)	Summary
Retry-limit cause triage docs-site/src/content/docs/reference/codex-retry-diagnostics.md	The guide distinguishes a local credential lock, an upstream plan-window limit, and a provider or transport failure, with evidence and responses for each.

Priority: ➖ Normal

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

Change: Bug fix

Suggested reviewers: lcxhh521

Merge Risk: ⚪ Minimal · up to 4b184

The identified concerns do not block merging; the test protects the intended post-quit behavior, and the aborted SOCKS5 connection is cleaned up.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 5 files. (7 skipped: 7…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately identifies all three primary changes: ChatGPT launcher handling, the SOCKS5 TLS deadline, and 429 retry diagnostics documentation. It is specific and understandable, although the …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 5 files. (7 skipped: 7 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• 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

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

[lidge-jun]

Maintainer integration record (MAINTAINERS.md dev exception): squash-merged into dev by @lidge-jun without a second maintainer approval during the 2026-10-14 triage. Exact-head verification: all 34 checks on head 4b184597852a1ca19e1c2b92142497e32eb0a4c5 completed with success or a policy skip (typecheck, test 1–4, gates, structure gate, docs build and the rest; macOS and Windows skipped per the PR CI policy). The merge was pinned with --match-head-commit. I reviewed the carried diffs: SOCKS5 keeps rejectUnauthorized, and the ChatGPT launcher change only adds refusal paths. Attribution is in Co-authored-by trailers.