Codex Desktop binary replacement and re-signing strategy

[shiny-code-bot]

Intent

Decide how the Every Code overlay can replace the Codex binary used inside the Codex Desktop app bundle in a way that survives updates of both Codex Desktop and the forked CLI.

Parent: #1

Finish Line

Produce an evidence-backed replacement strategy and viability decision covering:

• where Codex Desktop stores and launches the bundled Codex binary
• whether Desktop supports any override path, config, environment variable, app-server endpoint, or channel selector
• whether binary replacement inside the .app bundle is stable enough across Desktop updates
• what re-signing is required after replacing the binary
• whether Gatekeeper/notarization/quarantine/translocation create user-facing friction
• how to atomically install, verify, roll back, and re-apply after Desktop updates
• whether the right product shape is a patcher/installer, launch wrapper, stable symlink, app-server bridge, or a first-class Desktop integration request

Current Status

Known from the prior Every Code session and current planning discussion:

• The Codex binary used by Codex Desktop is inside the Codex Desktop app bundle.
• The binary can be replaced manually, but replacing it requires re-signing the app bundle.
• The likely product direction is a tool that replaces and re-signs the binary for users, if this can be made reliable and safe.
• There may be useful prior-session evidence in /Users/cbusillo/Developer/code rollout/session files. Mine that archive before repeating expensive discovery.

Questions

• Can re-signing be done locally with ad-hoc signing, or does it require a developer certificate for a usable UX?
• Does the app continue to run normally after local re-signing on current macOS?
• Does a Desktop update overwrite the bundle and require re-patching, and can we detect/re-apply safely?
• Does a CLI update need to replace only one binary, or are supporting resources/protocol schemas bundled too?
• Can we avoid patching the app bundle by using a shim path, symlink, environment override, app-server endpoint, or launch wrapper?
• What should the rollback story be if the patched Desktop fails to launch?

Guardrails

• Start read-only: inspect the installed app bundle and old rollout evidence before modifying anything.
• Do not patch or re-sign the live app until the strategy and rollback plan are written down.
• Treat app bundle mutation as a local user operation, not a repo code change.
• Keep this separate from provider-worker architecture in Provider-agnostic worker decision spike #2.

[cbusillo]

Archive evidence mined from /Users/cbusillo/Developer/code

Read-only archive pass found useful code-level evidence, but not a concrete prior re-signing recipe.

Relevant evidence:

• The pinned archive is at archive/every-code-pre-codex-substrate-transition / 4339c37439.
• codex-rs/cli/src/desktop_app/mac.rs in the archive looks for Codex Desktop at /Applications/Codex.app and ~/Applications/Codex.app.
• That file downloads Desktop from https://persistent.oaistatic.com/codex-app-prod/Codex.dmg on Apple Silicon and Codex-latest-x64.dmg on x64.
• It installs by copying Codex.app from a mounted DMG into an Applications directory, then opens the workspace with open -a <Codex.app> <workspace>.
• code-rs/cli/src/main.rs accepted --analytics-default-enabled on app-server explicitly for Codex Desktop compatibility, suggesting Desktop may launch codex app-server with fixed flags that a replacement binary must tolerate.
• Targeted searches of repo text and local .code/agents artifacts for codesign, resign, Codex.app, Contents/MacOS, and binary replacement did not uncover a durable written procedure for replacing and re-signing the bundle.

Implication:

The next pass should inspect the live installed app bundle directly and produce a small reversible patch procedure. Prior archive evidence supports the app bundle/install/open path and Desktop compatibility flags, but not the signing details.

[cbusillo]

Clarification: manual replacement works

Updated assumption from the planning discussion:

• Replacing the Codex binary inside the Codex Desktop app bundle has already been proven to work in the previous session.
• The open question is not whether replacement works manually.
• The open question is whether Every Code can provide a reliable scripted flow on a normal user's machine, especially when the user is not enrolled as an Apple developer and may not have a Developer ID certificate.

The spike should therefore focus on:

• ad-hoc signing viability after binary replacement
• whether a locally re-signed app launches consistently on current macOS
• what user prompts/permissions are required
• whether Gatekeeper/quarantine/notarization blocks the flow for downloaded apps
• whether the app can be patched in-place or should be copied to a managed location first
• atomic backup/restore and update re-apply behavior
• how to detect Desktop updates and binary drift
• whether a patcher can be distributed independently without making users install Xcode or Apple developer tooling

Known prior evidence still worth mining later:

The previous session apparently had rollout evidence showing manual replacement works. I attempted broad archive searches, but the local session/rollout stores are large and noisy. Since the key fact is now supplied directly, the next productive work is to prototype the scripted signing flow against a copied app bundle rather than re-discovering the manual proof.

[shiny-code-bot]

Distribution posture to validate

Working assumption, pending real legal review: do not redistribute a modified or re-signed Codex.app bundle.

Clean path for the first proof:

• distribute the forked Codex CLI Lab binary from this Apache-2.0 source fork, with the required license/notice handling;
• distribute a patcher/installer that a user runs against their own installed official Codex.app;
• have the patcher replace Contents/Resources/codex, sign the replacement and outer bundle locally as needed, verify launch/app-server compatibility, and record enough metadata to re-apply after Desktop updates;
• make the patched installation visibly identify itself as Codex Lab only after compatibility with app naming, bundle IDs, Sparkle updates, deep links, and signing behavior is proven.

Open question for this spike:

Can a normal user machine reliably perform the local replacement and ad-hoc re-signing path without Apple Developer Program enrollment, and what warnings or quarantine/Gatekeeper behavior appear on a clean Mac?

This keeps us from building the strategy around redistributing someone else's Desktop app bundle while still testing the practical local-user path.

[shiny-code-bot]

Scope narrowing

Decision: remove "build our own full Desktop GUI" from the practical near-term path.

Current target shape:

• Ship Codex Lab CLI from the fork.
• Ship Codex Lab Desktop Patcher as a local user-machine patcher for the official installed Codex.app.
• Treat Codex Lab Desktop as the user's patched local state, not a redistributed app bundle.

Reasoning:

A full replacement GUI would be a separate product with substantial design, UI, packaging, update, and platform maintenance burden. It is not the best next step while the immediate technical question is whether we can reliably replace/re-sign the embedded Contents/Resources/codex binary across official Desktop updates.

Next proof remains:

1. work on a disposable copy of Codex.app;
2. replace the embedded CLI with a compatible Codex Lab CLI binary;
3. re-sign locally;
4. verify codesign/Gatekeeper behavior and Desktop app-server startup;
5. repeat on a clean Mac before designing the patcher UX.

[shiny-code-bot]

Local proof result: ad-hoc signed copied app is internally valid but Gatekeeper-blocked

Test date: 2026-06-07.

What was tested:

• Built forked codex from this repo in both debug and release profiles.
• Verified the fork binary is arm64 and supports Desktop-required codex app-server --analytics-default-enabled.
• Copied official /Applications/Codex.app to /Applications/Codex Lab.app.
• Replaced only Contents/Resources/codex in the copied app.
• Ad-hoc signed the replacement binary and the outer copied app bundle with codesign --sign -.
• Verified the official app was not modified.

Findings:

• codesign --verify --deep --strict passed after re-signing the copied app. The modified resource seal can be repaired with ad-hoc signing.
• spctl --assess --type execute rejected the ad-hoc signed app.
• Finder/LaunchServices showed the macOS damaged/Move to Trash style dialog repeatedly for the copied app.
• spctl --add local allow-listing is no longer supported on this macOS version, so the old local Gatekeeper exception path is not viable for a patcher.
• The app and embedded binary retained com.apple.provenance metadata even after xattr -cr; attempts to delete provenance directly did not clear the behavior.
• The same release codex binary ran when copied outside the app bundle, but was killed when executed from the patched app bundle path. This suggests macOS provenance/Gatekeeper policy on the modified bundle path is part of the blocker, not a broken CLI binary.
• A /tmp copied app could be launched directly via Contents/MacOS/Codex far enough to spawn native helpers and create Application Support/CodexLabProof, but spctl still rejected it and no Desktop app-server success was confirmed.

Cleanup performed:

• Removed /Applications/Codex Lab.app and /tmp/CodexLabProof.app proof copies.
• Unregistered stale LaunchServices references for those proof app paths.
• Left official /Applications/Codex.app untouched.
• Repo tracked files remained clean.

Implication:

The patcher strategy is still technically plausible for replacing/re-sealing the bundle, but a no-Developer-ID ad-hoc app path is not clean enough for normal Finder launch on this macOS version. The next proof should test a Developer ID signed/notarized local patch, or a different architecture that avoids modifying the Desktop app bundle's sealed resources.

[shiny-code-bot]

Investigation update: external CLI launcher path is viable

We found a cleaner path than modifying or re-signing Codex.app.

Evidence from the installed Desktop bundle:

• The Electron main bundle reads process.env.CODEX_CLI_PATH.
• If set to an executable path, Desktop spawns that binary as its local app-server sidecar.
• If set to a directory, Desktop resolves <dir>/codex.
• The bundled binary remains the fallback.

Non-mutating local proof on June 7, 2026:

CODEX_CLI_PATH=/Users/cbusillo/Developer/codex/codex-rs/target/release/codex \
  /Applications/Codex.app/Contents/MacOS/Codex

The official signed Desktop app then logged:

[StdioConnection] stdio_transport_spawned argsCount=2 executablePath=/Users/cbusillo/Developer/codex/codex-rs/target/release/codex pid=27527 spawnCommand=/Users/cbusillo/Developer/codex/codex-rs/target/release/codex
[AppServerConnection] Current reported app-server version: currentVersion=0.0.0 hostId=local
[AppServerConnection] initialize_handshake_result durationMs=31 initializeRequestId=__codex_initialize__ outcome=success transportKind=stdio

A second proof showed LaunchServices can carry the environment too:

CODEX_CLI_PATH=/Users/cbusillo/Developer/codex/codex-rs/target/release/codex open -n /Applications/Codex.app

ps eww on the launched Desktop process included:

CODEX_CLI_PATH=/Users/cbusillo/Developer/codex/codex-rs/target/release/codex

Direction change:

• Prefer a small Codex Lab.app launcher/wrapper that starts the official signed /Applications/Codex.app with CODEX_CLI_PATH pointing to the installed Codex Lab CLI.
• Avoid patching, copying, modifying, or re-signing OpenAI's app bundle.
• This should survive official Desktop updates as long as the Desktop bundle continues honoring CODEX_CLI_PATH.
• This should survive Codex Lab CLI updates if the launcher points at a stable install path or symlink.

Next validation target:

Create a minimal launcher proof outside tracked repo files, then verify:

1. double-click or open launch behavior,
2. Dock/menu behavior,
3. stale/crash-window cleanup behavior,
4. compatibility check when CODEX_CLI_PATH support disappears or the Lab CLI app-server protocol drifts.

[shiny-code-bot]

Product direction refinement: launcher-owned CLI path and updater

The Codex Lab Desktop path should not rely on the user's shell PATH.

Preferred shape:

/Applications/Codex.app
  Official OpenAI Desktop app, unmodified.

/Applications/Codex Lab.app
  Codex Lab launcher/controller owned by us.
  Includes or resolves a stable Codex Lab CLI binary.
  Sets CODEX_CLI_PATH explicitly.
  Launches official Codex.app through LaunchServices.

Recommended CLI resolution order:

1. Bundle-contained CLI: Codex Lab.app/Contents/Resources/codex-lab.
2. Stable external install path or symlink, if we decide to separate CLI updates from app updates.
3. Developer override env/config for local testing only.

Avoid using PATH as the primary mechanism because Finder/LaunchServices GUI launches should not depend on shell startup files or terminal-specific environment state.

Updater should be part of the plan. Two viable tracks:

• Single app-bundle updater: update Codex Lab.app, including the embedded CLI and launcher together.
• Split updater: launcher remains stable while the CLI is updated at a stable external path/symlink; launcher checks and reports the active CLI path/version before launching Desktop.

Identity note:

• Finder/Dock can clearly show Codex Lab.app as the launcher the user opened.
• The actual GUI windows are still owned by the official Codex.app, so the active app/window label may remain Codex unless Desktop exposes a supported way to surface app-server identity.
• We should investigate whether the app-server handshake or version/status UI can display a Codex Lab channel label, but that is a usability improvement rather than a blocker.

Current best path:

Use the official signed Desktop app unchanged, and distribute only our own Codex Lab.app launcher plus our own Codex Lab CLI binary/updater.

[shiny-code-bot]

Local proof: Codex Lab.app launcher bundle works

A throwaway app bundle was created under /tmp/codex-lab-proof/Codex Lab.app with:

Contents/MacOS/Codex Lab Launcher
Contents/Resources/codex-lab

The embedded codex-lab binary was copied from the repo release build:

/Users/cbusillo/Developer/codex/codex-rs/target/release/codex

The launcher sets CODEX_CLI_PATH to the embedded binary and launches the official Desktop app with LaunchServices:

CODEX_CLI_PATH=/private/tmp/codex-lab-proof/Codex Lab.app/Contents/Resources/codex-lab
open -n /Applications/Codex.app

Observed result:

76257     1 /Applications/Codex.app/Contents/MacOS/Codex
76346 76257 /private/tmp/codex-lab-proof/Codex Lab.app/Contents/Resources/codex-lab app-server --analytics-default-enabled

The Desktop process environment included the expected CODEX_CLI_PATH, and the official Desktop process spawned the bundle-contained Lab CLI as its local app-server sidecar.

A shim proof also worked:

/tmp/codex-lab-proof/bin/codex-lab -> /tmp/codex-lab-proof/Codex Lab.app/Contents/Resources/codex-lab
codex-cli 0.0.0

Interpretation:

• A distributable Codex Lab.app can contain the Lab CLI binary and use it for Desktop mode.
• The same app bundle can expose codex-lab for terminal use via a symlink/shim.
• This supports one update owner for the app-installed mode: update Codex Lab.app, and both Desktop mode and terminal mode use the same updated binary.
• Official /Applications/Codex.app remains unmodified.

Cleanup:

• The proof-launched Desktop process and embedded app-server process were closed.
• No tracked repo files were changed.

[shiny-code-bot]

Implementation slice: launcher package scaffold started

Created branch codex-lab-desktop-launcher and added the first tracked packaging scaffold for the Codex Lab.app shape.

New local builder:

scripts/build_codex_lab_app.py
scripts/codex_lab_package/

Current capabilities:

• Builds a macOS Codex Lab.app bundle from a prebuilt Lab CLI binary.
• Embeds the CLI as Contents/Resources/codex-lab.
• Generates Contents/MacOS/Codex Lab Launcher.
• The app launcher resolves its own bundle location at runtime, sets CODEX_CLI_PATH to the embedded CLI, and launches /Applications/Codex.app through open -n.
• Generates Info.plist with Codex Lab display/bundle metadata.
• Optionally installs a codex-lab terminal wrapper into a requested shim directory; the wrapper executes the embedded CLI from the app bundle.
• Refuses to overwrite existing app/shim paths unless --force is passed.

Validated locally:

python3 -m unittest scripts.codex_lab_package.test_layout
uv run --frozen --project scripts --no-sync --with ruff ruff check scripts/build_codex_lab_app.py scripts/codex_lab_package
uv run --frozen --project scripts --no-sync --with ruff ruff format --check scripts/build_codex_lab_app.py scripts/codex_lab_package
python3 scripts/build_codex_lab_app.py --codex-bin codex-rs/target/release/codex --app-dir /tmp/codex-lab-package-scaffold/Codex\ Lab.app --shim-dir /tmp/codex-lab-package-scaffold/bin --force
sh -n /tmp/codex-lab-package-scaffold/Codex\ Lab.app/Contents/MacOS/Codex\ Lab\ Launcher
sh -n /tmp/codex-lab-package-scaffold/bin/codex-lab
/tmp/codex-lab-package-scaffold/Codex\ Lab.app/Contents/Resources/codex-lab --version
/tmp/codex-lab-package-scaffold/bin/codex-lab --version

Notes:

• just fmt was run from codex-rs per repo instructions. It completed successfully.
• Local uv/ruff commands emit an existing warning because this uv version does not parse the repo's relative exclude-newer = "7 days" setting in scripts/pyproject.toml. The scoped checks still pass.
• No updater or signing/notarization behavior is implemented in this first slice.

[shiny-code-bot]

Implementation slice: CI/CD scaffold added locally

On branch codex-lab-desktop-launcher, the local implementation now includes CI/CD wiring for the Codex Lab app packaging scaffold.

Added/updated:

.github/workflows/ci.yml
.github/workflows/codex-lab-app.yml
scripts/codex_lab_package/smoke.py

CI gate additions:

• ci.yml now runs the Codex Lab package builder unit tests.
• ci.yml also builds a fake Codex Lab.app using /bin/sh as the embedded binary and smoke-checks the generated layout.

Artifact workflow:

• New codex-lab-app workflow.
• Runs manually via workflow_dispatch and on PRs touching the app packaging/workflow paths.
• Builds codex-cli in release mode on macos-15-xlarge.
• Packages Codex Lab.app with the built CLI embedded as Contents/Resources/codex-lab.
• Smoke-checks the generated app and terminal wrapper.
• Archives the app and terminal wrapper as zip artifacts.
• Generates SHA256SUMS and uploads the artifact bundle.

Local validation passed:

python3 -m unittest discover -s scripts/codex_lab_package -p 'test_*.py'
python3 scripts/build_codex_lab_app.py --codex-bin /bin/sh --app-dir /tmp/codex-lab-ci-smoke/Codex\ Lab.app --shim-dir /tmp/codex-lab-ci-smoke/bin --force
python3 scripts/codex_lab_package/smoke.py /tmp/codex-lab-ci-smoke/Codex\ Lab.app --shim-path /tmp/codex-lab-ci-smoke/bin/codex-lab
uv run --frozen --project scripts --no-sync --with ruff ruff check scripts/build_codex_lab_app.py scripts/codex_lab_package
uv run --frozen --project scripts --no-sync --with ruff ruff format --check scripts/build_codex_lab_app.py scripts/codex_lab_package
actionlint .github/workflows/ci.yml .github/workflows/codex-lab-app.yml
just fmt

Notes:

• The artifact workflow is unsigned/not notarized for now.
• Pushing workflow changes may require the repository's workflow approval path if GitHub rejects the push.
• The existing uv warning for relative exclude-newer = "7 days" still appears locally, but scoped checks pass and no lockfile drift remains.

[shiny-code-bot]

Closing after plan reconciliation on June 10, 2026.

This spike answered the core Desktop replacement question and changed direction based on evidence:

• Direct bundle mutation plus ad-hoc re-signing was proven internally possible, but was not a clean normal-user distribution path because Gatekeeper/provenance behavior blocked the copied modified app.
• Live Desktop inspection found a better supported integration point: CODEX_CLI_PATH.
• The selected architecture is to leave official /Applications/Codex.app unmodified and ship a separate Codex Lab.app launcher/controller that sets CODEX_CLI_PATH to the Codex Lab CLI before launching Desktop.

Implementation that followed this decision has landed:

• Add Codex Lab app packaging scaffold #5 added the Codex Lab.app packaging scaffold.
• Add Codex Lab distribution manifest #6 added the distribution manifest.
• Add Codex Lab release publication workflow #8 and Publish Codex Lab releases as public prereleases #9 added public prerelease publication.
• Add Codex Lab release installer #10 added the release installer.
• Add Codex Lab installer download timeout #11 and Canonicalize Codex Lab installer paths #12 hardened timeout/path behavior.
• Add Codex Lab latest installer mode #13, Add Codex Lab installer status command #14, Add Codex Lab installer update command #17, and Handle Codex Lab installer CLI errors #18 added latest/status/update/error-handling installer flows.

Current follow-up belongs elsewhere:

• Codex Lab identity and channel naming #4 owns visible Codex Lab identity/channel metadata.
• Codex fork overlay capability map #1 owns the parent roadmap and CI posture follow-up.
• Provider-agnostic worker decision spike #2 owns provider-agnostic worker architecture.

The old patch-and-re-sign Desktop strategy is retired; the launcher path is the current plan.