fix(server): resolve Node for standalone helper scripts

[juliusmarminge]

Standalone builds expose the T3 executable as process.execPath. Running device helper scripts through it launches T3's embedded CLI instead of Node and leaves Device hub waiting for a process that cannot start. Antigravity's browser helper has the same assumption.

Resolve Node from PATH for standalone builds, using node.exe on Windows so batch wrappers are never launched without a shell and report Install Node.js and make sure node is on PATH, then retry before installing tools or starting helpers when it is missing. Reject symlink and hard-link aliases pointing back at T3. Preserve launcher names such as Vite+'s node alias. Use the selected runtime for hub starts and restarts, agent-device daemon starts and stops, generated agent launchers, and Antigravity's browser helper. Preserve fixed install guidance and the original cause chain through device and provider errors.

Audited every process.execPath and HostProcessExecutablePath use. Intentional T3/Claude-history relaunches, Electron workers using ELECTRON_RUN_AS_NODE, remote scripts already running under Node, and Node-only build scripts keep their existing behavior.

Validation:

• 106 focused tests across eight files; server typecheck and targeted lint pass. Lint reports one existing array-find warning in the device handlers.
• Built and ran the actual Node 26.8.2 single-executable server in isolated state. With Node available, hub readiness returned 200 and the app listed the Pixel, foldable, and tablet audit emulators alongside Mac Mini devices. Android SDK, Java, and the audit AVD directory were configured for this test.
• With Node unavailable, runtime resolution failed in under 2 ms with the install message, and Mac Mini devices remained available. Before this change, the packaged executable rejects the hub flags and readiness times out.
• Real CLI subprocess tests cover host-bound agent launchers and Antigravity browser suppression in standalone mode, plus missing-runtime and retry behavior.

Node unavailable:

Node available:

Found while auditing #11841.

Model: GPT-6. Harness: Codex.

Summary by CodeRabbit

• New Features

  • Device automation and Antigravity now detect and use an available Node.js installation instead of relying on the packaged runtime.
  • Added clearer guidance when Node.js is unavailable, including installation instructions.
  • Improved support for Windows executable discovery and symlinked or linked installations.

• Bug Fixes

  • Prevented device and Antigravity setup from attempting to use an invalid standalone application runtime.
  • Preserved underlying failure details for more reliable troubleshooting.
  • Improved error reporting for device readiness, agent startup, sign-in, and provider setup failures.

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.6 KiB	13.6 KiB	+11 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.1 KiB	7.0 KiB	−7 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.6 KiB	6.6 KiB	+18 B (+0.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.1 KiB	57.1 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	10	10	0 (0.0%)	21	✅
Claude	Total thread wire	13.6 KiB	13.6 KiB	+32 B (+0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.1 KiB	7.1 KiB	−6 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.6 KiB	+38 B (+0.6%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.9 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	9	10	+1 (+11.1%)	21	✅

Baseline: 6ee0324 · PR result: 49fb7a0 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.9 KiB
• Claude decoded thread snapshot: 114.6 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Effect Service Conventions found 7 blocking issues. See the inline review comments for required structured-error fixes.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes executable selection and startup behavior across device and Antigravity workflows, including new preflight gates and subprocess lifecycle handling. The logic is cohesive and tested, but its cross-component runtime impact warrants human review.

^{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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 6646ace1-5b80-4b44-837f-7aa842277144

📥 Commits

Reviewing files that changed from the base of the PR and between ae39cfb and 36b0cce.

📒 Files selected for processing (12)

• apps/server/src/device/DeviceHost.ts
• apps/server/src/device/DeviceService.test.ts
• apps/server/src/device/DeviceService.ts
• apps/server/src/device/LocalDeviceHost.ts
• apps/server/src/mcp/toolkits/device/handlers.ts
• apps/server/src/provider/AntigravityInstallation.ts
• apps/server/src/provider/Drivers/AntigravityDriver.ts
• apps/server/src/provider/antigravityAuthSupport.test.ts
• apps/server/src/provider/antigravityAuthSupport.ts
• packages/contracts/src/device.ts
• packages/shared/src/nodeRuntime.test.ts
• packages/shared/src/nodeRuntime.ts

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

---

📝 Walkthrough

Walkthrough

The pull request adds shared Node.js runtime resolution for standalone binaries. Device hosts, agent launchers, and Antigravity workflows use the resolved executable and preserve related error causes.

Changes

Node runtime integration

Layer / File(s)	Summary
Runtime resolver and coverage packages/shared/src/nodeRuntime.ts, packages/shared/src/nodeRuntime.test.ts, packages/shared/package.json	Adds standardized runtime error messages and rejects paths that resolve to the standalone application. Tests cover runtime selection, cache refresh, hard links, and symlinks.
Device runtime propagation apps/server/src/device/*, apps/server/src/mcp/toolkits/device/handlers.ts	Device hubs, daemons, launchers, and tool paths use the resolved Node executable. The path is reused across restarts and shutdown, exposed by the ready-host API, and preserved as an error cause.
Antigravity runtime validation apps/server/src/provider/AntigravityInstallation.ts, apps/server/src/provider/antigravityAuthSupport.ts, apps/server/src/provider/Drivers/AntigravityDriver.ts	Installation and profile preparation resolve Node before execution. Runtime failures use standardized messages, and provider refresh handling preserves setup failures from configuration and startup.
Validation and error contracts apps/server/src/device/*.test.ts, apps/server/src/provider/**/*.test.ts, packages/contracts/src/device.ts	Tests cover unavailable Node, PATH-based selection, standalone executable handling, skipped process execution, and preserved causes. Device unavailable errors now accept defect causes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~30 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant DeviceOrProvider
  participant resolveNodeExecutable
  participant NodeProcess
  participant ErrorSurface
  DeviceOrProvider->>resolveNodeExecutable: resolve Node executable
  resolveNodeExecutable-->>DeviceOrProvider: return executable path or runtime error
  DeviceOrProvider->>NodeProcess: run tool, hub, daemon, or browser helper
  NodeProcess-->>ErrorSurface: return result or failure cause

Loading

Merge Risk: ⚪ Minimal · up to 36b0c

The runtime-resolution changes have no identified merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The Antigravity changes and shared runtime resolver support #11767. The pull request also changes device-specific behavior and contracts in AgentDeviceShim, DeviceHost, LocalDeviceHost, `DeviceS…	Remove the unrelated device runtime, device error-contract, and device handler changes from this pull request, or link those changes to a separate issue with explicit coding requirements.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #11767 requires Antigravity browser-helper preflight to use Node from PATH instead of the standalone T3 executable. prepareAntigravityProfile now calls `resolveNodeExecutable("Antigravity sign…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Title check	✅ Passed	The title clearly and concisely describes the main change: resolving Node for standalone helper scripts.
Description check	✅ Passed	The description explains what changed, why it changed, affected components, validation results, and UI evidence. It does not use the template headings or include the checklist, but the required substa…

Full details: Out of Scope Changes check

Explanation

The Antigravity changes and shared runtime resolver support #11767. The pull request also changes device-specific behavior and contracts in AgentDeviceShim, DeviceHost, LocalDeviceHost, DeviceService, MCP device handlers, and packages/contracts/src/device.ts. These changes resolve Node for device automation, alter device error types and messages, and add device readiness behavior. Issue #11767 only addresses Antigravity browser-helper preflight and does not establish a device scope.

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/standalone-node-helpers

---

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

[macroscopeapp]

Effect Service Conventions found 1 blocking issue. See the inline review comment for the required bounded-error-attribute fix.

^{Posted via Macroscope — Effect Service Conventions}