[codex] Preserve PR materialization failure chains

[juliusmarminge]

Summary

• add a structured pull-request materialization error with repository and branch correlation fields
• preserve both the repository-head failure and pull-request-ref fallback failure in one AggregateError cause chain
• cover the dual-failure path through GitManager behavior

Testing

• vp test apps/server/src/git/GitManager.test.ts (59 passed)
• vp check
• vp run typecheck

---

Note

Low Risk
Scoped to PR thread preparation error reporting and contracts; behavior on success is unchanged, with clearer failure diagnostics on dual-fetch errors.

Overview
When preparing a PR worktree thread, both the repository-head fetch and the pull-request-ref fallback can fail; callers now get a single GitPullRequestMaterializationError instead of only the fallback GitCommandError.

The new contract error carries cwd, PR number, head repo/branch, and local branch name, with an AggregateError cause that lists both underlying git failures (primary as cause.cause). GitManagerServiceError includes this type so UI/RPC can pattern-match it.

Related logging in upstream configuration and setup-script failures is switched to structured Effect.logWarning payloads rather than interpolated strings.

^{Reviewed by Cursor Bugbot for commit 4734fe1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Preserve both branch materialization failures in GitPullRequestMaterializationError

• Adds GitPullRequestMaterializationError to packages/contracts/src/git.ts, a structured error carrying cwd, pullRequestNumber, headRepository, headBranch, localBranch, and a cause field.
• When both the primary head branch fetch and the fallback fetchPullRequestBranch fail in materializePullRequestHeadBranch, the error now wraps both failures in an AggregateError (with primaryCause as its own cause) rather than surfacing only the fallback error.
• Replaces string-interpolated warning logs with structured Effect.logWarning calls in configurePullRequestHeadUpstream and preparePullRequestThread.
• Adds a test in apps/server/src/git/GitManager.test.ts asserting that both GitCommandError instances are preserved in the AggregateError cause chain.
• Behavioral Change: GitManagerServiceError now includes GitPullRequestMaterializationError; consumers that pattern-match this union need to handle the new variant.

^{Macroscope summarized 4734fe1.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7cda890b-a7a2-4ab8-8142-0cbd5c89e3e3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/preserve-pr-materialization-fallback-causes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR improves error handling by preserving both failure causes when PR branch materialization fails. The changes are limited to error paths with a new additive error type and corresponding test coverage - a straightforward, low-risk improvement.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 4734fe1