[codex] Structure reference repo sync failures

[juliusmarminge]

Summary

• replace the reference-repo sync message bag with schema-tagged selection, version-source, resolution, and git-subtree failures
• preserve exact filesystem/schema/process causes and public repo/action/ref/path context
• retain argument count, exit code, and output lengths without storing subprocess argv, stdout, or stderr

Validation

• vp test scripts/sync-reference-repos.test.ts (10 tests)
• vp check
• vp run typecheck

---

Note

Low Risk
Changes are confined to the reference-repo sync script and its tests; no production auth or data paths, though callers matching on the old error shape would need updating.

Overview
Replaces the single message-bag ReferenceRepoSyncError in sync-reference-repos.ts with four schema-tagged failure types and a ReferenceRepoSyncError union plus isReferenceRepoSyncError.

Selection failures expose repoId and expectedRepoIds. Version source failures distinguish read vs parse, carry sourcePath and a real cause, and keep human messages from leaking underlying error text. Version resolution failures report packageVersionPath with no fabricated cause. Git subtree failures record operation (spawn / communicate / exit), repo/ref/action context, optional cause for process errors, and on non-zero exit only stdout/stderr lengths—not raw stderr (so secrets in git output do not land in messages).

Tests gain configurable mock child processes and new cases that assert structured fields and absence of stderr/cause where intended.

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

Note

Structure reference repo sync failures into typed error classes

• Introduces four tagged error classes in sync-reference-repos.ts: ReferenceRepoSelectionError, ReferenceRepoVersionSourceError, ReferenceRepoVersionResolutionError, and ReferenceRepoGitSubtreeError, plus a ReferenceRepoSyncError union type and isReferenceRepoSyncError guard.
• Git failures are now categorized by phase (spawn/communicate/exit) and report output lengths rather than raw content, preventing stdout/stderr from leaking into error messages.
• Read/parse failures for version sources preserve the original cause internally but expose only a stable, structured message to callers.
• Adds test coverage in sync-reference-repos.test.ts asserting non-leaky error semantics across all failure paths.
• Behavioral Change: non-zero git exits no longer include raw stdout/stderr or args in the error message; callers receive length counts instead.

^{Macroscope summarized a24f12b.}

[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: 176d4470-1832-4855-9015-459c844d298e

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/reference-repo-sync-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling in internal sync scripts by replacing a generic error class with multiple structured error types. Changes are limited to error formatting and structure with comprehensive test coverage - no behavioral changes to the sync logic itself.

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

Dismissing prior approval to re-evaluate a24f12b