QVAC-18515 fix[api]: catch bare-runtime spawn failure instead of crashing the host

[simon-iribarren]

🎯 What problem does this PR solve?

The install failure originally reported in #1492 (No binaries found for target '<platform>-<arch>' under pnpm) is already fixed on the current toolchain — it was a pnpm bug fixed in pnpm 11.0.0 (see "Original issue: already fixed" below). What remains unaddressed is the failure mode: when the Bare runtime binary genuinely can't be spawned, the SDK crashes the host process instead of throwing a catchable error.

bare-runtime resolves its platform binary synchronously with require('bare-runtime-<platform>-<arch>'). When that package — or one of its nested deps — can't be loaded, the spawn call throws synchronously inside the IPC listen callback. Nothing catches it, so it escapes as an uncaught exception and kills the host process. The thrown message is also misleading: a missing nested dependency surfaces as the terse "No binaries found".

📝 How does it solve it?

• Wrap the synchronous spawn("bare", …) in client/rpc/node-rpc-client.ts in a try/catch. On failure it tears down the half-initialized RPC state, closes the IPC server, and rejects the init promise instead of letting the throw crash the process.
• Map the raw No binaries found throw to a structured, exported BareRuntimeBinaryNotFoundError that names the platform/arch and tells the user how to recover (install bare-runtime-<platform>-<arch> directly, or install with npm/bun).
• Document the same remedy in the CLI README.

This is platform-independent: any synchronous spawn failure now becomes a catchable error rather than a host crash.

✅ Original issue: already fixed

The #1492 install failure does not reproduce on the current toolchain — it was a pnpm resolution bug fixed in pnpm 11.0.0, not a bare-runtime/@qvac issue.

The bare-runtime platform package (e.g. bare-runtime-darwin-arm64) depends on require-asset, and older pnpm doesn't link require-asset into the virtual store (node_modules/.pnpm/node_modules/require-asset), so require('bare-runtime-<platform>-<arch>') fails and surfaces as the misleading "No binaries found". Reproduced on macOS (arm64) installing the originally-reported bare-runtime@1.28.4 and resolving the binary the way the SDK does:

pnpm	result
8.15.9 / 9.15.4 / 10.17.1	❌ No binaries found for target '<platform>-<arch>'
11.0.0+	✅ resolves the bare binary

The bare-runtime version isn't the factor (even 1.28.4 resolves fine on pnpm 11). An earlier revision of this PR declared the bare-runtime-<platform>-<arch> packages as optionalDependencies of @qvac/sdk / @qvac/cli; since current pnpm already resolves the binary, those added no guarantee and were dropped to keep the change minimal.

🧪 How was it tested?

• bun install + tsc --noEmit, eslint --max-warnings=0, and prettier --check on the changed files — all pass.
• Reproduced the load failure locally (a missing nested dependency of the platform package surfaces as the misleading No binaries found) and confirmed the new path rejects with BareRuntimeBinaryNotFoundError instead of crashing the process.
• pnpm version sweep on darwin-arm64 installing bare-runtime@1.28.4: fails on pnpm 8/9/10, resolves on pnpm 11 (see table above) — confirming the install issue is a pnpm bug already fixed upstream, hence the dropped optionalDependencies.
• Note: end-to-end win32 + pnpm validation requires a Windows host and was not run here; the crash-handling fix is platform-independent.

🔌 API Changes

New exported error class BareRuntimeBinaryNotFoundError (non-breaking addition). Thrown during worker init when the platform's Bare runtime binary cannot be loaded.

import { BareRuntimeBinaryNotFoundError, completion } from "@qvac/sdk";

try {
  await completion({ /* ... */ });
} catch (err) {
  if (err instanceof BareRuntimeBinaryNotFoundError) {
    // platform binary missing — install `bare-runtime-<platform>-<arch>`
    // directly (pnpm), or install @qvac/sdk with npm or bun
  }
}

Closes #1492

[lauripiisang]

could you write a test that checks this new behavior through RPC init via lying about the platform, e.g. something like

const ogPlatform = process.platform;

Object.defineProperty(process, 'platform', { value: 'commodore64' });
// do your test
finally {
  Object.defineProperty(process, 'platform', { value: ogPlatform });
}

[arun-mani-j]

could you write a test that checks this new behavior through RPC init via lying about the platform, e.g. something like

const ogPlatform = process.platform;

Object.defineProperty(process, 'platform', { value: 'commodore64' });
// do your test
finally {
  Object.defineProperty(process, 'platform', { value: ogPlatform });
}

spawn detects (https://github.com/holepunchto/bare-runtime/blob/main/index.js#L14) the platform and arch through the native OS handles (https://github.com/holepunchto/bare-os/blob/main/index.js#L12), so we need to fake the OS handle itself to cause this error no? 🤔

Ah wait, NVM. It also allows us to pass the opts, so we need a test where we spawn but with different opts that letting Bare decide it.

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ❌ PENDING

**Requirements:**
- 1 Team Member approval ❌ (0/1)
- 1 Team Lead OR Management approval ❌ (0/1)



---
*This comment is automatically updated when reviews change.*

[arun-mani-j]

The recommended solution comes up nicely when I passed wrong platform and arch.

Since this only comes for pnpm users, I'm wondering if we should ask the users facing the issue to update their pnpm than us adding all these 🤔