Orca: coordinate coding agents without losing track of their work
Read Orca’s native-runtime checker before diagnosing terminal failures
Follow Node and Electron checks, selective rebuilding and fresh-process verification in ensure-native-runtime.mjs.
What you will learn
- Choose the intended runtime
- A normal check can rebuild dependencies
- Verification uses a fresh process
Before you start
- Basic command-line and configuration reading
- Ability to work in a disposable authorized environment
Create a learning tool that records host, worktree and acceptance evidence without automating merges or deleting unfinished work.
Key takeaways
- The ordinary ensure command can change dependencies.
- Node and Electron require separate checks.
- A fresh process matters after native-load failures.
Choose the intended runtime
readRuntimeArg accepts --runtime=node or --runtime=electron, with an inline or separate value. An unsupported selection exits with usage status 2. The package test script invokes the checker for Node before Vitest.
The checked module list includes node-pty and adds Windows-specific modules on Windows. A successful JavaScript import elsewhere is not proof that these native dependencies match the selected runtime and platform.
A normal check can rebuild dependencies
ensureNodeRuntime first checks loading and a patched node-pty rebuild condition. It returns immediately only when both are satisfactory. Otherwise it rebuilds selected modules and verifies again. The Electron branch invokes its native-dependency rebuild script when needed.
Do not describe the ordinary ensure command as read-only. It can modify installed native dependencies. The child --check-only branch collects failures and exits, but this article does not provide a complete audit of every helper it calls.
Verification uses a fresh process
runNodeCheck launches a new Node process because a failed native-addon load can contaminate the current process. runElectronCheck launches the installed Electron with ELECTRON_RUN_AS_NODE=1. A rebuild is followed by another check.
The source also compares Electron package and installed binary versions and checks its executable path. Use those diagnostics before treating a terminal failure as a model problem. We inspected control flow without executing rebuilds or upstream tests.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Identify whether the failure belongs to Node or Electron.
- 2
Inspect native-module diagnostics before rebuilding.
- 3
Verify again in the intended runtime after an approved rebuild.
Copy-ready example
runtime argument → Node or Electron
initial load + patch condition
if needed: rebuild native dependencies
fresh-process verification → success or exit 1Frequently asked questions
Is the checker only a diagnostic command?
Its normal path can rebuild dependencies; inspect and authorize that effect.
Does a Node check establish desktop compatibility?
No. Electron has a separate execution path and binary checks.
Sources
- Orca / config/scripts/ensure-native-runtime.mjsSource checked 2026-09-18
- Orca / package.jsonSource checked 2026-09-18