[codex] Structure VCS process boundary errors

[juliusmarminge]

Problem

VcsOutputDecodeError grouped stdin writes, process reads, output limits, and missing exit codes behind one tag and a free-form detail string. That erased useful byte and stream diagnostics, made the message depend on manually manufactured text, and allowed real I/O causes and structural no-cause failures to share the same loose shape.

Change

Replace the single error class with a Schema.Union of distinct tagged errors for stdin writes, output reads, output limits, and missing exit codes. The errors now expose safe structured fields such as stream, stdinBytes, maxBytes, and observedBytes; real stdin/read failures retain their exact underlying cause, while output-limit and missing-code conditions do not manufacture one. Messages derive only from those structured fields and never from a cause or captured output.

VcsProcess constructs the errors directly at the mapping boundary, and the exhaustive GitLab CLI mapper recognizes the new tags without changing its existing fallback behavior. The focused backend test verifies exact-cause identity, safe messages, and the absence of a synthetic cause for a missing exit code.

Validation

• vp test run apps/server/src/vcs/VcsProcess.test.ts apps/server/src/sourceControl/GitLabCli.test.ts (18 tests)
• vp check (passes; existing unrelated warnings remain)
• vp run typecheck

---

Note

Medium Risk
Touches shared @t3tools/contracts error shapes and the core VcsProcess boundary; callers matching on VcsError tags must handle four tags instead of one, though the union alias preserves grouping.

Overview
Replaces the single VcsOutputDecodeError (free-form detail) with four distinct tagged errors: VcsProcessStdinWriteError, VcsProcessOutputReadError, VcsProcessOutputLimitError, and VcsProcessMissingExitCodeError. Each exposes structured fields (stdinBytes, stream, maxBytes, observedBytes) and messages derived from those fields only; real I/O failures keep their underlying cause, while limit and missing-exit-code cases do not invent one.

VcsProcess maps ProcessRunner failures directly to these types instead of factory helpers on the old class. VcsError lists the four tags individually; VcsOutputDecodeError remains as a Schema.Union alias for backward grouping. GitLab CLI’s exhaustive fromVcsError matcher adds cases for each new tag, all falling through to GitLabCliCommandError like before.

Tests add a mocked ProcessRunner path to assert exact cause identity, safe messages, and no synthetic cause on missing exit code.

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

Note

Structure VCS process boundary errors into granular error types

• Replaces the single VcsOutputDecodeError class in vcs.ts with four dedicated error classes: VcsProcessStdinWriteError, VcsProcessOutputReadError, VcsProcessOutputLimitError, and VcsProcessMissingExitCodeError, each with structured fields and specific tags.
• Updates VcsProcess.ts to emit these granular types instead of the old VcsOutputDecodeError factory methods, preserving underlying causes for stdin/read failures.
• Updates GitLabCli.ts to map each new error tag to a GitLabCliCommandError with the original cause preserved.
• VcsOutputDecodeError is retained as a union type alias over the four new classes for backward compatibility with existing consumers.
• Behavioral Change: VcsError consumers will now see distinct tags per boundary error type rather than a single generic VcsOutputDecodeError tag.

^{Macroscope summarized a6747ab.}

[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: efdff4d0-64c3-4f0c-8564-acc021dd343a

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/structure-vcs-output-decode-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR is a mechanical refactoring that splits a generic error class into multiple specific typed error classes without changing runtime behavior. The original union type is preserved for backward compatibility, and the changes are well-tested.

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