fix(codex): install and run autostart shims from standalone ocx

[lidge-jun]

Summary

Closes #6276. Carries the compiled-probe approach from #6280 (d31e7f0d6ef1721df378d4bf9d9d13abf2a3cfcd).

Standalone desktop ocx executables can install and run the Codex autostart shim. The Unix probe selects Bun interpreter mode with BUN_BE_BUN=1, then removes that flag before invoking the saved Codex launcher. Unix, Windows CMD, and PowerShell wrappers use the existing selfLaunchArgv mode selection to invoke a standalone executable as ocx ensure, omitting the virtual bundled CLI path; source/npm launches retain their entrypoint.

A compiled regression fixture exercises installation and the installed Unix wrapper, including executable paths with spaces/apostrophes, ensure argv and runtime provenance, flag isolation, Codex argument forwarding, and its exit status. Command-generation tests cover all three wrapper flavors. The new test is registered in both layout maps, and the runtime contract and public guide are synchronized.

Co-authored-by: drakeo338 paranoyouz@gmail.com

Verification

• Focused run: bun test tests/codex-integration/codex-shim-standalone.test.ts tests/codex-integration/codex-shim.test.ts tests/codex-integration/codex-shim-autorestore.test.ts tests/codex-integration/codex-shim-destroyed-probe.test.ts tests/codex-integration/codex-shim-ensure-failure.test.ts tests/codex-integration/codex-shim-readiness.test.ts tests/lib/self-launch-argv.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts — 126 pass, 23 platform skips, 0 fail.
• Red proof: the same five standalone regressions against pre-fix source snapshots all fail. The signed compiled fixture reproduces the original phase=group-id refusal; all three wrappers retain the erroneous virtual-entrypoint command.
• bun run typecheck, bun run privacy:scan, bun run structure:check, bun scripts/file-size-ratchet.ts, and git diff --check — pass.
• cd docs-site && bun install --frozen-lockfile && bun run build — pass (545 pages, 74,719 internal links checked).
• bun run test:changed — failed: 26,315 pass, 47 skip, 863 fail across 1,339 files. Numerous existing tests create/delete checkout-local fixtures, and the real-home guard refuses those paths inside a managed ~/.codex/worktrees checkout. Additional assertion/launcher-shutdown failures are not claimed passing. The focused changed-behavior regressions pass independently.
• Full local-suite exception: changed mode already expanded to 27,225 tests, and other worktrees were running local suites concurrently. A second broad run in the same protected checkout would repeat those failures and add contention. Broader coverage is provided by exact-head Cross-platform CI run 36663135066, pull_request, attempt 1, completed success for 7ea7a5dbddc7c2e40759c3d27439968791fb8890: all 17 requested jobs succeeded. Eight out-of-scope jobs are not claimed passing. Windows standalone tests inspect generated commands; the compiled installation/launch regression executes on Unix.
• Environment regression ablation: removing only launcher sanitization makes the compiled install regression fail its saved-launcher probe.
• Independent read-only code/security review: PASS, no actionable findings, no secret/auth changes or introduced shell-injection path; interpreter mode is confined to the supervisor.
• Rebased onto latest dev (fdf4177dfe2b6885aafef5a67213c08684f9c4f3) before the final CI run; git range-diff confirms the shim patch is unchanged.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

[coderabbitai]

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

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: b7c751a9-924c-412e-ac62-44bdf3e2fe18

📥 Commits

Reviewing files that changed from the base of the PR and between fdf4177 and 7ea7a5d.

📒 Files selected for processing (7)

• docs-site/src/content/docs/guides/codex-integration.md
• scripts/test-layout/layout.json
• src/codex/shim-probe.ts
• src/codex/shim-templates.ts
• structure/runtime.md
• tests/codex-integration/codex-shim-standalone.test.ts
• tests/fixtures/test-layout-expected.json

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

---

📝 Walkthrough

Walkthrough

The Codex shim now constructs standalone-compatible ensure commands across Unix, Windows CMD, and PowerShell. The Unix install probe sets BUN_BE_BUN=1 for its script and removes it from the saved launcher’s environment. Tests and documentation cover the behavior.

Changes

Standalone Codex shim

Layer / File(s)	Summary
Build standalone shim launch arguments src/codex/shim-templates.ts, tests/codex-integration/codex-shim-standalone.test.ts, structure/runtime.md, docs-site/src/content/docs/guides/codex-integration.md	The Unix, Windows CMD, and PowerShell templates use selfLaunchArgv to build standalone-compatible ensure invocations. Tests check generated commands and the virtual CLI path. The documentation describes installation, launch behavior, status inspection, and uninstall.
Control probe environment and test standalone installation src/codex/shim-probe.ts, tests/codex-integration/codex-shim-standalone.test.ts, structure/runtime.md, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json	The Unix probe sets BUN_BE_BUN=1 for its script and removes the variable from the saved launcher’s environment. Integration tests cover installation, probe environment handling, argument forwarding, and exit status. The test-layout mappings include the new test.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 7ea7a

The changes address standalone shim installation and launch behavior without an identified merge-blocking regression. Windows coverage checks generated commands rather than executing the wrappers.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 7ea7a

The changed launch behavior preserves existing validation controls and keeps the probe’s interpreter flag out of the saved launcher. A local recovery weakness remains: failure while saving installation state can leave a wrapper installed but unrecognized by normal removal commands. No privilege escalation or cross-user attack path was established; interrupted and concurrent installation behavior remains partially validated.

Retained concerns

• Low · reliability · inferred: The newly working standalone installation path inherits a non-atomic terminal commit: after wrapper validation succeeds, ownership state is written directly without rollback around that write. A write failure or interruption can leave the wrapper and saved launcher present but ownership metadata missing or malformed. Normal uninstall then reports no installation, and auto-restore cannot recover from valid prior state. The mechanism predates this PR; its reachability expands to successful standalone installations.

Security review details

Security Blast Radius

• inferred — The demonstrated exposure is the invoking user’s Codex launcher, saved backup, shim ownership state, and inherited process environment. The change enables standalone runtime execution within that flow; the inspected code does not establish a new privilege boundary or cross-user reachability.

Trust Boundaries and Controls

• observed — BUN_BE_BUN is confined to the supervisor’s interpreter selection rather than inherited by the saved launcher. Existing recursive-entry detection, bounded diagnostics, timeouts, descendant detection, and process-group termination remain in the inspected probe flow.

Resilience and Maintainability Implications

• inferred — Invalid ownership metadata is rejected rather than used for automatic recovery. This contains unsafe adoption, but a failed terminal state write can leave a credential-bearing wrapper outside normal uninstall and auto-restore management. The concern is recovery and ownership consistency, not a verified credential-exfiltration path.

Hardening Proposals

• proposed — Extend the installation transaction through durable ownership-state publication, with atomic state replacement and explicit recovery for interrupted commits. Separately validate or serialize concurrent direct installs; the current evidence does not demonstrate a complete multi-installer guarantee.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	PR #6284 addresses the active coding requirements in #6276. In src/codex/shim-probe.ts, probeUnixShimInstall sets BUN_BE_BUN=1 for the compiled supervisor and deletes it from launcherEnv befor…
Out of Scope Changes check	✅ Passed	The changed files remain within #6276. The fixture registration in scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json enables the new regression test. The updates in `str…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: installing and running Codex autostart shims from the standalone ocx executable.

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 3 files. (4 skipped: 4 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

---

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.

[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-09-30T03:07:30.407718Z	dcf934c	Draft marked ready

ℹ️ 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.

[lidge-jun]

Owner-authorized maintainer integration into dev.

• Head: dcf934ce5009fa1ff564e405d4a275285978af35; current dev base: 1b97c6ff0f057159fac1f9ea484457b1316b97eb is contained in this branch, so no rebase is needed.
• Exact-head Cross-platform CI: run 36662038724, pull_request, attempt 1, completed successfully. All 17 requested jobs succeeded, including the four Linux suite shards, Windows/npm and keyring smoke checks, and the aggregate ci gate. Eight jobs excluded by the workflow scope are not claimed passing.
• scripts/ci/assert-mergeable-review.sh --maintainer-integration 6284 lidge-jun/opencodex passed: OK: validation snapshot for #6284 into dev at head dcf934ce5009fa1ff564e405d4a275285978af35 by lidge-jun; CI and security review remain separate.
• Independent code/security review passed with no actionable findings; focused local regressions passed. The failed local broad run and its managed-worktree guard limitation remain documented in Verification.

This records maintainer integration, not an approving self-review. The squash will retain Co-authored-by: drakeo338 <paranoyouz@gmail.com> for the carried probe fix from #6280.

[lidge-jun]

리뷰 · 우선순위 67 / 80

이 PR은 리눅스 데스크톱 .deb로 깐 단독 실행 파일 ocx에서 Codex 오토스타트 심을 설치·실행하지 못하던 문제를 한 번에 고친다. 베이스는 dev다. 이슈 #6276에는 원인이 두 개였다. 첫째, 설치 검사가 컴파일된 ocx에 Bun처럼 -e 스크립트를 돌리려다 Unknown command: -e로 끝나고 phase=group-id로 거절됐다. 둘째, 심 래퍼가 standalone일 때도 ocx <가상 /$bunfs 경로> ensure를 써서, 설치가 되더라도 오토스타트가 또 깨질 수 있었다. 이번 변경은 프로브 쪽에 BUN_BE_BUN=1을 넣어 검사 감독만 인터프리터로 돌리고, 저장해 둔 Codex 런처를 띄울 때는 그 플래그를 지운다. 심 템플릿(Unix·CMD·PowerShell)은 selfLaunchArgv로 standalone이면 실행 파일에 ensure만 붙이고, 소스/npm은 예전처럼 엔트리포인트를 유지한다. 컴파일된 픽스처로 설치·실행·공백/아포스트로피 경로·플래그 격리·인자 전달·종료 코드를 막고, 세 래퍼의 명령 생성도 따로 잠근다. 가이드와 structure/runtime.md도 맞춰 두었다. #6280의 프로브 접근을 이어 받아 이슈 전체(1·2번)를 닫는 방향이다.

라인 - src/codex/shim-probe.ts · BUN_BE_BUN=1 + 런처 env에서 삭제 · 감독만 인터프리터로 쓰고, 저장된 Codex에는 플래그가 안 넘어가게 한 점이 맞다. 컴파일 픽스처가 프로브 env를 unset으로 확인한다.

라인 - src/codex/shim-templates.ts · selfLaunchArgv(..., isStandaloneExecutable: bunRuntimeSource === "standalone") · Unix/PowerShell은 인자 문자열을 이어 붙이고, CMD는 OCX_CLI를 비울 때 "%OCX_BUN%" ensure만 남긴다. 가상 /$bunfs·~BUN 경로가 standalone 래퍼에 안 들어가는 걸 테스트가 잠근다.

라인 - tests/codex-integration/codex-shim-standalone.test.ts · 컴파일 설치/실행은 Unix만 · Windows는 명령 생성만 본다. 본문도 그렇게 적었다. 데스크톱 .deb 경로의 핵심 회귀는 Unix 쪽에 있다.

라인 - 검증 · 포커스 126 pass · 본문 test:changed 광범위 실패는 managed worktree 가드 때문으로 적어 두었고, 현재 head 7ea7a5db…의 Cross-platform CI(36663135066)는 리뷰 시점 기준 아직 진행 중이다. 이전 head 초록은 이 head의 머지 증거가 아니다.

메인테이너의 판단이 필요한 지점

#6280(프로브만)과 #6282(심 ensure만, draft)는 이 PR이 둘 다 덮는다. 이 PR을 머지 경로로 두면 둘은 닫는 쪽이 맞다. 현재 head CI가 초록이 된 뒤에만 dev 머지로 보면 된다. types/config 중복으로 닫을 PR은 없다.

너의 추천

원인 두 개를 한 갈래로 묶었고, 컴파일 픽스처·명령 생성·문서가 맞춰져 있다. exact-head CI가 통과하면 dev에 머지해도 된다. 머지 시 #6280·#6282는 무효/중복으로 닫고 #6276도 같이 닫으면 된다. 미리보기 배포 이야기는 필요 없다.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

Refreshed owner-authorized maintainer integration into dev after rebasing.

• Current head: 7ea7a5dbddc7c2e40759c3d27439968791fb8890; latest dev base: fdf4177dfe2b6885aafef5a67213c08684f9c4f3 is contained in the branch. The rebase preserved the patch (git range-diff).
• Exact-head Cross-platform CI: run 36663135066, pull_request, attempt 1, completed success. All 17 requested jobs passed, including all four Linux suite shards and the aggregate ci check. Eight jobs excluded by workflow scope are not counted as passing evidence.
• scripts/ci/assert-mergeable-review.sh --maintainer-integration 6284 lidge-jun/opencodex passed: OK: validation snapshot for #6284 into dev at head 7ea7a5dbddc7c2e40759c3d27439968791fb8890 by lidge-jun; CI and security review remain separate.
• Independent code/security review passed with no actionable findings; focused regressions passed, and no unresolved review threads were present. The failed local broad run remains documented in Verification.

This is maintainer integration, not an approving self-review. The squash retains Co-authored-by: drakeo338 <paranoyouz@gmail.com> for #6280's carried probe approach.