fix(codex): respect CODEX_HOME for profile installs

[huntharo]

Summary

This fixes Codex profile installs for Compound Engineering by making the Codex converter and cleanup paths honor the active Codex home consistently.

Before this change, codex plugin marketplace add respected CODEX_HOME, but the companion CE Bun install defaulted to ~/.codex. A profile install such as CODEX_HOME="$HOME/.codex/profiles/work" ... could therefore register the marketplace in the profile while writing CE custom agents into the default Codex home. The result was a half-installed profile: native plugin skills could be installed through Codex, but CE skills that delegate to custom agents would still fail because the agents were in the wrong root.

What Changed

• Added resolveCodexHome, which resolves Codex output roots as: explicit --codex-home, then $CODEX_HOME, then ~/.codex.
• Updated install, convert, and cleanup to use that resolver.
• Updated auto-detection so install --to all recognizes a Codex install located at $CODEX_HOME.
• Made the CLI Codex target treat its resolved home as the actual Codex root, even when the path is a profile directory like ~/.codex/profiles/work instead of a literal .codex directory.
• Preserved the lower-level writer behavior for callers that pass a project root directly to writeCodexBundle.
• Documented the profile-aware Codex setup flow with a work profile example and a local-worktree development variant.
• Clarified that the Codex /plugins TUI install is still required today: marketplace registration only makes CE available, and the TUI install activates native skills; the Bun step installs the custom agents that those skills delegate to.

Root Cause

The Codex native command and the CE Bun installer were using different ideas of “Codex home.” Codex itself follows CODEX_HOME, but the CE installer hard-coded path.join(os.homedir(), ".codex") unless --codex-home was passed. That mismatch only shows up for non-default profiles, which is why the normal ~/.codex install path appeared fine.

There was a second edge case: passing --codex-home ~/.codex/profiles/work should write directly into that profile root. The Codex writer historically treated any output path not named .codex as a project root and nested another .codex directory under it. The CLI now explicitly tells the Codex writer that resolved Codex homes are already Codex roots.

User Impact

Users can now install CE into a named Codex profile with consistent commands:

CODEX_HOME="$HOME/.codex/profiles/work" codex plugin marketplace add EveryInc/compound-engineering-plugin
CODEX_HOME="$HOME/.codex/profiles/work" bunx @every-env/compound-plugin install compound-engineering --to codex
CODEX_HOME="$HOME/.codex/profiles/work" codex

Inside Codex, users still run /plugins and install compound-engineering. That step is expected with current Codex because there is no CLI plugin-install subcommand for plugins from added marketplaces.

Validation

• bun test
• bun run release:validate

[huntharo]

I can confirm this works. I have installed CE as a plugin in a secondary Codex profile on my machine and am using brainstorm/plan/work right now to build a new project.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc288338bc

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

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".