fix: harden native codex queue fallback for the desktop composer

[luvs01]

Summary

Use native codex queue as an on-demand, limited fallback for a composer-only usage gate. Submit one message to an explicit existing thread without changing OpenCodex routing, ChatGPT authentication, account entitlements, app files, TLS or Statsig. This does not unlock the model picker, switch an existing gpt-reserve thread to another provider, or reset quota. App/CLI updates can still change compatibility.

Integration and on/off behavior

• Reuse the thread's native app-server and already-configured provider. OpenCodex retains ownership of Pool/Direct account selection, routing, credentials and upstream authorization when that thread already routes through it. No second router, quota cache, listener or automatic monitor is introduced.
• Preserve CODEX_HOME, OPENCODEX_HOME, working-directory context and both applications' configuration. Only thread and text are passed. On Windows, filesystem discovery and the native child use PowerShell's current location, including relative homes after Set-Location.
• No persistent switch is necessary: no invocation means no helper activity. A normal invocation queues one ordinary message even when quota is available; it is not silently skipped. Dry run never submits. Once the composer works, stop invoking the helper rather than running ocx restore or disabling the normal integration.
• Accepted messages remain in Codex's queue after the helper exits. Stopping the helper is not cancellation; inspect/remove unwanted items in the native queue. Avoid duplicate composer/CLI submissions.
• These are repository-checkout helpers, not an installed ocx queue command or dashboard control. The existing npm file allowlist excludes scripts/. No packaging/runtime feature is claimed or added.

Implementation and bot follow-up

• Require an explicit UUID/exact name or deliberate latest-file heuristic. Respect the effective store; preserve literal text; propagate CLI exit status without automatic resend.
• Prefer queue-capable app/standalone binaries before PATH. Bash now checks all PATH candidates rather than only the first obsolete CLI. Explicit executable pinning stays authoritative.
• Hide paths, thread identifiers/names and prompts from default dry-run diagnostics. Explicit --show-target / -ShowTarget requires dry run and local terminal output, with control-character escaping. Fixed helper errors avoid raw private filesystem exceptions. Native CLI output during a real submission is still passed through; terminal recording and process-argument visibility are not prevented.
• Add the guide to the explicit docs sidebar. Document ordinary-usage behavior, route ownership, remote-provider versus remote-app-server distinction, daemon compatibility, resume --last directory filtering, and queue acceptance versus execution/completion.
• The offline Node harness IS wired into CI: .github/workflows/codex-queue-helpers.yml runs Linux Bash, macOS system Bash, Windows PowerShell 5.1 and PowerShell 7. Required shells fail rather than silently skip. This is separate from live Desktop/provider/remote-control verification.
• Review findings have individual replies with commit/test evidence. Correct code/docs findings are resolved after correction; stale PR-description findings are explained against current metadata. The remaining pre-merge verification thread is intentionally open, not treated as a code fix or a passing check.

Source basis: OpenAI Codex 7dae8c53d97e61cd774e4d6bcca5243c29ca615c (queue_cmd.rs, session_queue_commands.rs, queue service.rs, ResumeCommand), current OpenCodex provider-target code, and package file allowlist. Source checks and fake-CLI tests are not live provider-routing evidence.

Verification

Current head: b8cfba17a0953d4fed9d5441c3adfe1ca7ba7872.

• PASS, latest-head hosted CI: Codex queue helpers run 35957767065 — all three jobs completed successfully: ubuntu-latest, macos-latest using /bin/bash, windows-latest requiring both powershell.exe and pwsh.exe. The API job metadata confirms this head SHA for every job.
• PASS, latest-head React Doctor: run 35957767006.
• Not complete at last observation: separate latest-head Cross-platform CI 35957766946 was queued. The helper workflow is not a substitute for required repository/documentation checks or independent security review.
• PASS locally: CODEX_QUEUE_TEST_SHELLS=bash node --test scripts/codex-queue.test.mjs — 33 tests, 0 failures, Linux / Node 22.16.0 / Bash 5.2.
• Coverage: deliberate targets; 2,200-session selection; dual UUIDs; literal Unicode/quotes/newlines; errors without retries; private dry runs; obsolete first PATH executable; configuration/env preservation for ordinary allowed true/false × built-in/custom provider. Temporary files and fake native CLIs only, not actual OpenCodex/backend traffic.
• PASS locally: Bash syntax, Node test syntax, Astro config JavaScript syntax, and git diff --check in the partial validation workspace. Committed changed-file blob SHAs match the local tested files. All pushes preserve prior commits; no force push.
• CI-driven correction: the initial c938967 Windows run failed. Follow-up 59bf48c fixed PowerShell 5.1 relative-home lookup and corrected the harness's Windows 8.3 path-alias and outer PowerShell exit-code handling. Run 35957533636 then passed on all three platforms; b8cfba1 adds the later-PATH regression and also passes. No failed assertions were skipped or weakened.
• Static workflow security inspection: ordinary pull_request/push triggers, hosted runners, contents: read, no secret use, pinned existing checkout action, persist-credentials: false, no dependency installation or real Codex/account/model calls. This is technical inspection, not independent maintainer approval.

Still unverified: real matching Desktop queue dispatch through the intended OpenCodex provider and remote-control continuity. The original author-reported Windows desktop 26.917.9434.0 probe established queue acceptance, not a completed model turn.

The local workspace has no Bun, PowerShell or full checkout and could not retrieve dependencies. Therefore local bun run typecheck, bun run test, bun run privacy:scan, bun run prepush, and the Astro install/build have not been run. Hosted Windows/macOS wrapper results are verified CI results but do not replace these unexecuted local commands or live integration verification.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes inspected for secrets, auth and unsafe defaults; no auth/runtime/config/packaging changes.
• Latest-head dedicated queue-helper checks passed on Windows, macOS and Linux.
• Independent maintainer security review for the new read-only workflow.
• Remaining required repository/documentation checks completed.
• Matching live Desktop/OpenCodex provider dispatch and remote-control behavior verified.

---

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

📝 Walkthrough

Walkthrough

Adds Bash and PowerShell helpers to send messages to Codex threads with codex queue. Adds a guide describing these helpers and other CLI options for use when the desktop composer is blocked by a client-side usage gate.

Changes

Composer usage-gate fallback

Layer / File(s)	Summary
Cross-platform queue helpers scripts/codex-queue.ps1, scripts/codex-queue.sh	Both scripts accept a message and an optional thread ID. When no thread ID is supplied, they select the newest rollout file and extract its UUID. They locate a Codex executable, invoke codex queue, and return or propagate its exit status.
Documented fallback options docs-site/src/content/docs/guides/composer-usage-gate-fallback.md	The guide describes codex queue, codex exec, and codex resume, explains thread ID resolution and quota behavior, and covers remote control and the helper scripts.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Suggested reviewers: lidge-jun

Merge Risk: 🟡 Moderate · up to fbda9

The new fallback helpers can fail or send a message to the wrong conversation in the following cases:

• Codex uses a custom home directory.
• An older codex is on PATH.
• The user has many saved sessions.

The guide also slightly misdescribes which session resume --last picks. These are contained to the new scripts and docs, but they should be fixed before merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: strengthening the native Codex queue fallback for the desktop composer. It is concise, specific, and consistent with the documentation and helper-script ad…

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[luvs01]

Implemented the focused hardening in 45ff4f9; all four GitHub file blobs match the locally tested versions.

Assessment: native codex queue is a reasonable least-invasive fallback for an otherwise usable thread when preserving desktop authentication is important. It is not a complete composer/model-picker fix. In particular, a thread still configured for gpt-reserve is not rerouted by queueing, and server quotas/authorization remain unchanged.

The revision addresses the valid review findings: effective CODEX_HOME, supported standalone layouts, bundled-before-PATH capability selection, safe global latest-file selection without ls/head, Bash end-of-options, and resume --last working-directory scope. It additionally removes implicit target selection, adds preview/explicit binary pinning, preserves literal native arguments, and avoids automatic retry.

The most important documentation correction is acceptance versus dispatch: the inspected upstream run_session_queue_action_with_app_server sends thread/queue/add only, while dispatch_if_idle/wake_if_loaded do not load an absent thread. An accepted message can remain pending. The guide now says to inspect/open/resume the same conversation without submitting the prompt again. No automatic force-start or second-server workaround was introduced.

Executed here: 24/24 offline Bash wrapper tests with Node 22.16.0/Bash 5.2, bash -n, node --check, and diff whitespace validation. The tests use fake native CLIs, not an account/model. Windows PowerShell, macOS, actual Desktop/provider completion and remote-control continuity remain unverified. Full Bun checks/privacy/prepush and docs build were unavailable locally and remain explicitly unchecked in the PR description. At the latest observation, Cross-platform CI was in progress; this comment is not a merge approval or an assertion that all checks are green.

I have left the existing review threads available for reviewer re-evaluation rather than treating the new source changes as proof of unexecuted platform/runtime coverage.

[devin-ai-integration]

Devin Review found 3 new potential issues.

[devin-ai-integration]

🔍 Confirm cross-platform checks before merging

The PR description leaves Windows, macOS, and pre-push validation outstanding. Repository rules require these checks for cross-platform tooling; confirm exact-head results before merging.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[luvs01]

Exact-head wrapper evidence is now available for b8cfba1: Codex queue helpers run 35957767065 completed successfully for ubuntu-latest, macos-latest (/bin/bash), and windows-latest (required powershell.exe and pwsh.exe). This supersedes the first Windows failure; the follow-up fixed relative-home discovery and corrected 8.3-path/outer-launcher assertions without skipping tests. Local Linux has 33/33 passes.

I am deliberately keeping this thread unresolved as a remaining verification gate: the separate latest-head Cross-platform CI run 35957766946 was still queued at the last observation, local full Bun/prepush and docs builds were unavailable, and live Desktop/OpenCodex/remote-control verification is not established by fake-CLI tests. No merge or approval has been performed. The PR checklist also leaves independent maintainer review of the new read-only workflow outstanding.

[luvs01]

Exact-head platform evidence is now available for b8cfba1: Codex queue helpers run 35957767065 succeeded on Ubuntu, macOS and Windows, including the required Windows PowerShell 5.1 and PowerShell 7 harnesses. This is the current PATH-fix head, not just parent 59bf48c. Independently re-ran the exact published Linux harness: 33/33 passed after verifying the fetched file blob hashes.

The initial Windows failures at c938967 were real test results and were not skipped: 59bf48c corrected PowerShell 5.1 relative-home resolution, filesystem alias comparisons, and the outer PowerShell launcher's exit propagation. b8cfba1 additionally fixes later PATH-candidate discovery.

The separate general Cross-platform CI run 35957766946 was still queued/in progress at this check; local bun run prepush and the full local Bun/Astro checks have not been executed in this limited workspace. Independent workflow security review and live Desktop/OpenCodex dispatch/remote-control verification also remain outstanding. I am leaving this verification thread open rather than equating green offline wrapper tests with all merge/readiness requirements. No merge or approval is being performed.

[luvs01]

Follow-up integration/lifecycle review completed for b8cfba1.

Assessment: preserve the native queue + existing OpenCodex routing boundary. This is a deliberately narrow on-demand fallback, not a fully packaged/dashboard-integrated feature or a model-picker repair. A persistent toggle would add state without controlling any background behavior, because no helper runs until explicitly invoked. Normal usage availability does not suppress a deliberate invocation: it queues one ordinary message. Stopping future invocations does not cancel already accepted queue items.

Changes in this follow-up: c938967 documents integration/on-off/normal-usage behavior, redacts default diagnostics, preserves PowerShell working-directory context, adds guide discovery, and wires a dedicated offline platform workflow. 59bf48c fixes the Windows PowerShell relative-home failure exposed by that CI and corrects the harness's 8.3-path/outer-launcher exit-code assertions. b8cfba1 fixes the newly reported later-PATH CLI discovery defect and adds its regression.

Observed verification: local Linux 33/33 offline tests; exact-head Codex queue helpers workflow 35957767065 completed successfully on Linux, macOS system Bash and Windows PowerShell 5.1/7. React Doctor 35957767006 succeeded. These use fake native CLIs and temporary configuration files, not real account/model traffic.

Bot handling: reviewed the 15 known inline threads, including follow-up findings. Five previously resolved Devin threads remain addressed; nine additional code/documentation/metadata threads have individual evidence-bearing replies and are resolved. The remaining pre-merge verification thread PRRT_kwDOTmCbas6lcVt7 has an explicit status reply and stays open. CodeRabbit independently confirmed the four original findings after the replies. No blanket bot approval or silent dismissal was used.

Outstanding: separate latest-head Cross-platform CI 35957766946 was queued at the last observation; local complete Bun/prepush/docs checks were unavailable; live Desktop→OpenCodex→provider completion and remote-control continuity remain unverified; the new read-only workflow still needs independent maintainer security review. No merge/approval, user-PC configuration change, daemon restart, quota manipulation or real model request was performed.