fix(server): surface SIGILL/AVX detail when Antigravity runtime fails to start

[pujitha24]

What Changed

In AntigravityInstallation.ts, the validate effect's error mapping now inspects the failure's cause chain for the signal that killed the child process (effect/platform's node child-process spawner raises "Process interrupted due to receipt of signal: ''" when a process exits via signal, preserved through PlatformError and AcpTransportError's cause fields). When that signal is SIGILL, the detail message now names the illegal-instruction crash and points at missing AVX/AVX2 CPU support as the likely cause; every other failure keeps the original generic message unchanged. This does not add a CPU-flag pre-flight check (the issue's other proposed option) — it only makes the existing failure legible.

Why

On CPUs that lack AVX/AVX2, the Antigravity runtime binary crashes on startup with SIGILL during post-install validation. The server reports one fixed generic message ("The downloaded Antigravity runtime could not start in this environment.") for every validation failure, so users mistake the illegal-instruction crash for archive corruption or a permissions/WSL issue and repeatedly re-download the 682 MB archive with no way to self-diagnose.

Report: #11414

UI Changes

None — this changes a server-side diagnostic message only.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (not applicable — no UI changes)
• I included a video for animation/interaction changes (not applicable — no animation/interaction changes)

---

Validation: npx vp test run src/provider/AntigravityInstallation.validationFailure.test.ts src/provider/AntigravityInstallation.test.ts (run from apps/server) — the new test file's 7 tests (signal extraction, chained-cause traversal, no-signal fallback, non-Error input, cyclical-cause bound, and both branches of the detail message) all pass, and all 29 previously-passing tests in AntigravityInstallation.test.ts still pass. One pre-existing, unrelated test in that file fails on this machine due to macOS resolving /tmp to /private/tmp; confirmed pre-existing by stashing this change and reproducing the identical failure before restoring it. Also ran npx vp run typecheck (apps/server) — exit 0, no new diagnostics — and npx vp lint --report-unused-disable-directives on the touched files — clean.

Signed-off-by: Pujitha Paladugu 10557236+pujitha24@users.noreply.github.com
Assisted-by: claude-sonnet-5 (via Claude Code)

Fixes #11414

Summary by CodeRabbit

• Bug Fixes

  • Installation validation errors now provide more specific guidance when startup fails because the runtime does not support required CPU instructions.
  • Existing installation errors are preserved during validation instead of being replaced by a generic startup message.

• Tests

  • Added coverage for signal detection across chained and cyclical errors.
  • Added validation for CPU-instruction-specific and generic failure messages.

[macroscopeapp]

Approvability

Verdict: Approved at 9ee0b7f

Macroscope's review found this PR approvable — The change is a narrow server-side diagnostic improvement: existing validation behavior is unchanged, while SIGILL failures receive a more actionable AVX/AVX2 message and other failures retain the old detail. The accompanying tests are isolated to the new cause-chain parsing logic.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a1338c5b-dff2-4f87-b434-1492c2f2e081

📥 Commits

Reviewing files that changed from the base of the PR and between 803f94e and 9ee0b7f.

📒 Files selected for processing (2)

• apps/server/src/provider/AntigravityInstallation.ts
• apps/server/src/provider/AntigravityInstallation.validationFailure.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds chained-cause signal detection for Antigravity validation failures. It reports a SIGILL-specific AVX message, preserves existing installation errors, and adds tests for signal extraction, cyclic causes, and fallback messages.

Changes

Antigravity validation

Layer / File(s)	Summary
Signal detection and failure descriptions apps/server/src/provider/AntigravityInstallation.ts	Adds findTerminatingSignal and describeValidationFailure. Signal lookup traverses up to eight chained causes.
Validation error mapping and tests apps/server/src/provider/AntigravityInstallation.ts, apps/server/src/provider/AntigravityInstallation.validationFailure.test.ts	The validation mapping preserves existing AntigravityInstallationError values and uses signal-specific details for other failures. Tests cover SIGILL, generic failures, missing signals, wrapped causes, and cyclic causes.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: juliusmarminge

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: exposing SIGILL and likely AVX-related details when the Antigravity runtime fails to start.
Description check	✅ Passed	The description includes complete What Changed and Why sections, explains the limited server-side scope, documents that no UI changes apply, references the linked issue, and records validation results…
Linked Issues check	✅ Passed	For [#11414], the validation error path now walks chained child-process causes and detects SIGILL. It reports an illegal-instruction crash and identifies missing AVX/AVX2 instructions as a likely ca…
Out of Scope Changes check	✅ Passed	The changes stay within [#11414]. They update Antigravity runtime validation and add focused automated tests for signal detection and failure messages. No unrelated provider, download, CPU pre-flight,…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[juliusmarminge]

Thanks for this. #13387 carries it forward with you as co-author. Since #12625 keeps a stderr tail, it maps signal deaths in effect-acp and uses one classifier for install, sign-in, session start and model refresh, which covers SIGABRT/IPv6 (#9800) too.

[juliusmarminge]

Superseded by #13387.