[codex] Structure dev-runner failures

[juliusmarminge]

Summary

• replace the dev-runner message bag with schema-tagged configuration, offset, port, process, and exit failures
• preserve exact configuration/platform causes without copying cause text into messages
• retain mode, fixed executable identity, argument count, shell mode, port requirements, and exit status without storing free-form run arguments

Validation

• vp test scripts/dev-runner.test.ts (26 tests)
• vp check
• vp run typecheck

---

Note

Medium Risk
Behavior change for anything matching the old DevRunnerError type; dev tooling only, but spawn/exit error handling paths are refactored.

Overview
Replaces the single generic DevRunnerError message bag with five Schema-tagged error types (DevRunnerConfigurationError, DevRunnerInvalidPortOffsetError, DevRunnerPortExhaustedError, DevRunnerProcessError, DevRunnerProcessExitError) plus a DevRunnerError union and isDevRunnerError helper.

resolveOffset now returns an Effect and fails with DevRunnerInvalidPortOffsetError instead of throwing. Port search failures use DevRunnerPortExhaustedError with structured range and port-requirement fields.

runDevRunnerWithInput maps config read failures, spawn/wait-for-exit platform errors, and non-zero exits to the matching typed errors—preserving underlying causes where appropriate, attaching mode/executable/argument count/shell context, and avoiding argv or cause text in user-facing messages (including sensitive runArgs).

Tests are extended for invalid offsets, port exhaustion, and full runDevRunnerWithInput error shapes via mocked NetService and ChildProcessSpawner.

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

Note

Replace generic dev-runner errors with structured error classes in runDevRunnerWithInput

• Introduces five typed error classes — DevRunnerConfigurationError, DevRunnerInvalidPortOffsetError, DevRunnerPortExhaustedError, DevRunnerProcessError, and DevRunnerProcessExitError — each carrying structured fields (config keys, port ranges, process context, exit code, etc.).
• resolveOffset is refactored from a throwing function into an Effect that fails with DevRunnerInvalidPortOffsetError; callers must handle the Effect.
• runDevRunnerWithInput now maps configuration read failures, spawn failures, wait-for-exit failures, and non-zero exits to their respective typed errors instead of collapsing them into a single generic error.
• Tests in dev-runner.test.ts are updated to assert on structured error fields rather than string matching.
• Behavioral Change: callers of resolveOffset must now treat it as an Effect; the previous throwing behavior is removed.

^{Macroscope summarized c1295f1.}

[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: 50b09f7d-92ea-4028-8976-81bbd3fa90b6

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/dev-runner-error-context

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling in dev-runner scripts by replacing a generic error class with specific typed error classes. Changes are confined to development tooling with comprehensive tests and no production behavior impact.

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

Dismissing prior approval to re-evaluate c1295f1