Codex App worktree setup fails with invalid reference: main for repositories without commits

Codex App worktree setup fails with invalid reference: main for repositories without commits

What version of the Codex App are you using?

26.901.20858 on macOS (desktop application bundle version).

What platform is your computer?

macOS 15.7.9 (24G830), Apple Git 2.50.1.

What issue are you seeing?

Codex recognizes a directory containing .git as a Git project even when the repository has no commits and no branch refs. Starting a task in Worktree mode then attempts to create a worktree from a fallback main reference and fails during workspace preparation:

[info] Starting worktree creation
fatal: invalid reference: main
[stderr] git worktree add failed: fatal: invalid reference: main

The failure happens before the requested task branch is created. Retrying or editing the environment does not help because the repository has no commit that can serve as the detached worktree's starting point.

What steps can reproduce the bug?

Create an unborn repository whose configured initial branch is not main:

mkdir empty-repository
cd empty-repository
git init -b master

Verify that it has no commit and no branch refs:

git branch --show-current                  # master
git for-each-ref refs/heads               # no output
git rev-parse --verify 'HEAD^{commit}'     # exits 128

Then:

1. Add the directory as a Codex project.
2. Start a task in Worktree mode.
3. Ask Codex to create a task branch, for example test.
4. Workspace preparation fails with fatal: invalid reference: main.

The underlying Git failure is independently reproducible:

git worktree add --detach ../worktree main
# fatal: invalid reference: main

What is the expected behavior?

Codex should distinguish between:

• a directory that merely contains Git metadata; and
• a worktree-ready repository with a base that resolves to a commit.

If the repository has no commits, Worktree mode should be disabled or fail before allocation with an actionable message such as:

Cannot create a worktree because this repository has no commits.
Create an initial commit, then retry.

Codex should not synthesize or fall back to main when the repository has no branch refs.

Root-cause analysis

A managed Codex worktree starts in detached HEAD, so it requires an existing commit. An unborn repository has a symbolic branch name such as master, but refs/heads/master does not exist until the first commit. Therefore neither HEAD^{commit} nor main^{commit} can resolve.

The current open-source worktree implementation resolves the requested base using git rev-parse --verify <base>^{commit} before calling git worktree add, but it currently returns the generic Git failure without an empty-repository-specific diagnostic:

https://github.com/openai/codex/blob/main/codex-rs/worktree/src/lib.rs#L61-L85

The desktop project/branch selection layer also appears to treat the presence of .git as sufficient and supplies main when no real branch ref is available.

Proposed solution

1. During project/worktree eligibility checks, separately expose whether HEAD^{commit} resolves. A repository with an unborn HEAD remains usable in Local mode but is not yet eligible for Worktree mode.
2. Do not fall back to main when git for-each-ref refs/heads returns no branches. Preserve “no valid starting branch” as an explicit state.
3. In WorktreeManager::create, add contextual validation before allocating the destination:
   • no explicit base and unborn HEAD: report that an initial commit is required;
   • explicit base that does not resolve: name the invalid base and ask the user to select an existing branch or commit.
4. Keep automatic commit creation and orphan worktrees out of scope. Creating a commit mutates the user's repository, while an orphan worktree violates the current detached-commit contract and has unclear behavior for untracked files.

Suggested tests

• An initialized repository without commits and base: None returns the actionable “no commits” error and creates no worktree directory.
• The same repository with base: Some("main") reports that main does not resolve and creates no worktree directory.
• A committed repository with a missing explicit base reports the invalid base without allocation residue.
• Existing HEAD, branch, tag, and commit-SHA creation cases remain unchanged.

Official Worktrees documentation states that the starting point is the HEAD commit of the selected branch, which is consistent with rejecting unborn repositories until they receive an initial commit:

https://developers.openai.com/codex/app/worktrees

Start in codex-rs/worktree/src/lib.rs, especially WorktreeManager::create and the base-resolution path, then trace the desktop project/branch eligibility checks that fall back to main. Verify the suggested unborn-repository and invalid-base cases, including that no worktree directory is created, while existing HEAD, branch, tag, and commit-SHA cases remain unchanged.