Fixes #97796.

What Problem This Solves

createNonExitingRuntime().exit() throws a generic Error, making it impossible for upstream try-catch handlers to distinguish a simulated process exit from a real runtime crash. Any code that needs to handle "exit requested but we're in a non-exiting runtime" differently from an actual error has no clean way to do so.

Why This Change Was Made

Added an internal ExitError class (extending Error) that is thrown by createNonExitingRuntime().exit() instead of a generic Error. Callers can now use instanceof ExitError to distinguish simulated exits from real errors.

ExitError is intentionally kept internal — it is exported from src/runtime.ts for direct test imports, but is not re-exported from the public plugin SDK subpaths (plugin-sdk/runtime.ts, plugin-sdk/runtime-env.ts). This avoids expanding the public plugin SDK API surface without maintainer approval.

User Impact

No user-facing impact. This is an internal runtime improvement for code that uses createNonExitingRuntime.

Evidence

Behavior addressed: createNonExitingRuntime().exit() throws generic Error — no way to distinguish simulated exit from runtime crash.

Real environment tested: Node 24.13.1, local OpenClaw checkout.

Exact steps or command run after this patch:

node --import tsx -e "
import { createNonExitingRuntime, ExitError } from './src/runtime.js';
const rt = createNonExitingRuntime();
try { rt.exit(1); } catch (e) {
  console.log(JSON.stringify({
    isExitError: e instanceof ExitError,
    isError: e instanceof Error,
    name: e.name,
    code: e.code,
    message: e.message
  }));
}
"

Evidence after fix:

{"isExitError":true,"isError":true,"name":"ExitError","code":1,"message":"exit 1"}

Before fix: e instanceof Error is true but there's no way to know it's an exit vs a crash.
After fix: e instanceof ExitError cleanly distinguishes the two.

node scripts/run-vitest.mjs src/runtime.test.ts --run

 Test Files  1 passed (1)
      Tests  8 passed (8)

• exit function throws ExitError — verifies typed error is thrown
• ExitError includes exit code — verifies code is preserved in message and instanceof
• ExitError is distinguishable from generic Error — NEW: proves instanceof ExitError works independently of instanceof Error

node scripts/run-oxlint.mjs src/runtime.ts src/runtime.test.ts

(passed, exit 0)

Observed result after fix: createNonExitingRuntime().exit() throws ExitError with the exit code and a descriptive message. Callers can use instanceof ExitError to distinguish simulated exits from real errors.

What was not tested: Upstream callers that currently catch the generic Error and would benefit from switching to instanceof ExitError. Those are follow-up work and not part of this change.

Regression Test Plan

• node scripts/run-vitest.mjs src/runtime.test.ts --run — Test Files 1 passed (1), Tests 8 passed (8)
• node scripts/run-oxlint.mjs src/runtime.ts src/runtime.test.ts — exit 0

Root Cause

In createNonExitingRuntime(), the exit function throws new Error(\exit ${code}`)— a genericErrorinstance. Any upstream code that catches errors from the runtime cannot distinguish "the runtime simulated process.exit" from "something actually crashed." The fix adds a typedExitErrorsubclass so callers can useinstanceof` checks for clean control flow.

AI Assistance

• AI-assisted: Yes
• Model used: Claude Opus 4.8 (1M context)
• Co-Authored-By: Already in commit message