fix(server): name the cause of a failed git command

[walid-baharwal]

What Changed

GitCommandError gains an optional reason: a closed set of diagnostic tags for well-known
git failures, recognized from stderr inside the driver and appended to the message the way
EnvironmentInternalError does it. The tag names the cause; it selects no text.

Before and after, for the same failing command (real git, captured from the driver):

Git command failed in GitVcsDriver.createWorktree (/tmp/…/repo): git worktree add failed
Git command failed in GitVcsDriver.createWorktree (/tmp/…/repo): git worktree add failed (branch_checked_out_in_worktree)

Raw stderr still never leaves the driver.

Why

Fixes #4380. Every git precondition failure collapsed into one string, so a tag conflict, an
auth failure and a branch already checked out elsewhere were indistinguishable without
re-running the command by hand.

The issue offers two options. The first — carrying a bounded stderrExcerpt — is the one I
did not take: apps/server/src/vcs/GitVcsDriverCore.test.ts already asserts
notProperty(error, "stderr") and that a secret passed in argv never reaches
error.message, so dropping stderr is deliberate, and shipping an excerpt would mean
deleting a security test. This is the issue's second option, the parsed reason, which keeps
that guarantee intact: the tags are a closed literal union, the sentences are static, and
nothing matched from stderr is ever interpolated. The existing redaction test is extended
with notProperty(error, "reason").

Classification happens at the two shared funnels every git call routes through
(executeGit and the non-zero-exit branch of the raw executor), which covers
fetchRemote and createWorktree — the two operations named in the issue.

Two limits, stated rather than hidden:

• Only git's own diagnostic lines are classified, plus the refusals ssh prints. remote:
  is deliberately excluded: git prefixes every byte the server sends that way, remote hook
  output included, so trusting it would reintroduce the same false positive from the far end.
  Every source that can reach the classifier is covered by a test — local hook output, remote
  hook output, five ssh refusal shapes, and an OS-level permission error that must not read as
  ssh auth. The one accepted residue is that a local hook echoing an ssh refusal verbatim would
  still be classified; that text is narrow enough that the tag would arguably still be right. Hooks write to the same stream
  unprefixed, so a pre-push hook echoing "authentication failed" would otherwise be reported
  as a credential failure (reproduced, and now covered by a test that pushes through a failing
  hook). ssh states a key refusal unprefixed as well, so those specific lines stay eligible —
  otherwise git's generic "could not read from remote repository" would be read as an
  unreachable remote when the real cause is credentials.
• Classification is English-only. executeGit inherits the process locale, so under a
  non-English LANG git's wording does not match and the error simply keeps today's
  behavior — no reason, no regression. Forcing LC_ALL=C for every git command would fix
  that, but it changes the environment of every call in the driver and belongs in its own
  change. The new tests pin LC_ALL: "C" so they do not depend on the runner's locale.
• Five other GitCommandError constructions hold stderr in hand and stay unclassified.
  Adding them is one line each and deliberately left out to keep this to one concern.

UI Changes

None. Server-side error metadata; no rendered change. The improved text surfaces wherever
an existing git error message is already shown.

Verification

vp test run apps/server/src/vcs/GitVcsDriverCore.test.ts   # 68 passed
cd packages/contracts && tsgo --noEmit                     # clean
cd apps/server && tsgo --noEmit                            # clean
vp lint apps/server/src/vcs/GitVcsDriverCore.ts apps/server/src/vcs/GitVcsDriverCore.test.ts packages/contracts/src/git.ts
vp format --check <same three files>
git diff --check

The new tests drive real git through the real driver: a branch already checked out in
another worktree, a command outside a repository, a tag collision that must stay unclassified, a failing
pre-push hook whose output must not be classified, and a fallback detail that must not run
into the reason sentence. Each fails without the source change.

Checklist

• One concern
• Focused tests, failing before the fix
• Typecheck, lint and format run on the changed packages
• No new dependencies, no committed artifacts
• Additive optional contract field; web, mobile and desktop need no change (no reference
  to GitCommandError fields exists in any client)

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

Note

Medium Risk
Changes how git failures are surfaced (new optional field and message suffix) and classifies auth/SSH-related stderr, though patterns are conservative and stderr still never leaves the driver.

Overview
GitCommandError now carries an optional reason from a closed GitCommandFailureReason union in contracts, and the error message appends (reason) when classification succeeds—without ever exposing raw stderr.

The git VCS driver adds classifyGitFailure, which pattern-matches filtered diagnostic lines (plus specific SSH refusal lines) at the shared non-zero-exit paths in executeRaw and executeGit. Callers can distinguish worktree branch conflicts, missing repos, auth vs host-key failures, and similar cases while the redaction guarantee stays intact (no stderr, no matched text in messages). Classification deliberately ignores hook/remote: noise and leaves ambiguous failures (e.g. duplicate tags) untagged; matching is English-only unless git runs under LC_ALL=C.

Integration tests exercise real git scenarios and extend the secret-leak test to assert reason is not set when stderr would be unsafe to interpret.

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

Note

Add reason tag to GitCommandError for classified git failures

• Introduces GitCommandFailureReason schema in git.ts with literal tags like authentication_failed, not_a_repository, branch_checked_out_in_worktree, and host_key_unverified.
• Adds classifyGitFailure(stderr) in GitVcsDriverCore.ts that matches stderr lines against ordered regex patterns to produce a reason tag, returning null when no pattern matches.
• Both executeRaw and executeGitWithStableDiagnostics now call classifyGitFailure on non-zero exits and attach the reason to the thrown GitCommandError.
• GitCommandError.message now appends (reason) when a reason is present, so callers that parse error messages see a new suffix.
• Risk: any code that string-matches GitCommandError messages or asserts exact error text will break due to the appended (reason) suffix; the reason field is optional so existing .reason checks are unaffected.

^{Macroscope summarized 61b8981.}

[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 Plus

Run ID: 2f865d56-f9eb-46c4-9443-de0b394614e4

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

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes shared production Git error handling and automatically classifies SSH authentication and host-key failures, with new metadata and message output visible to existing callers. The authentication-sensitive runtime behavior warrants human validation despite the additive contract and comprehensive integration tests.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

One convention finding on the new GitCommandError.reason discriminator. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3a9c452. Configure here.}