Summary

• Add a best-effort error listener to the detached gateway update respawn child before calling unref().
• Preserve the existing detached update handoff behavior and spawned result shape.
• Add regression coverage that the child error listener is registered before unref() and can consume an async spawn error.

Change Type

• Bug fix
• Feature
• Refactor
• Docs
• Security
• Chore

Scope

• Gateway
• Skills
• Auth
• Memory
• Integrations
• API
• UI/UX
• CI

Real behavior proof

Behavior addressed: Detached gateway update respawn no longer leaves the returned ChildProcess without an error listener, so asynchronous spawn failures do not become unhandled child-process errors.

Environment tested: Linux source checkout on branch fix/101458-process-respawn-error, Node running TypeScript sources through node --import tsx, plus the targeted Vitest shard through node scripts/run-vitest.mjs.

Steps run after the patch: Called the actual respawnGatewayProcessForUpdate() production function from src/infra/process-respawn.ts, forced a detached spawn with a missing process.execPath, waited for the child error event, and confirmed the parent process stayed alive. Also ran the targeted process respawn test file.

Evidence after fix: Production function proof:

node --import tsx --no-warnings -e '
import { respawnGatewayProcessForUpdate } from "./src/infra/process-respawn.js";
import { SUPERVISOR_HINT_ENV_VARS } from "./src/infra/supervisor-markers.js";

for (const key of SUPERVISOR_HINT_ENV_VARS) delete process.env[key];
delete process.env.OPENCLAW_NO_RESPAWN;
process.execArgv = [];
process.argv = ["/usr/local/bin/node", "/repo/dist/index.js", "gateway", "run"];
Object.defineProperty(process, "execPath", {
  configurable: true,
  value: "/tmp/openclaw-missing-node-for-respawn-proof",
});

const result = respawnGatewayProcessForUpdate();
const child = result.child;
let childError = "none";
child?.once("error", (err) => {
  childError = `${err.code ?? "NO_CODE"}:${err.message.includes("ENOENT")}`;
});
await new Promise((resolve) => setTimeout(resolve, 150));
console.log(JSON.stringify({
  mode: result.mode,
  pid: result.pid ?? null,
  hasChild: Boolean(child),
  childError,
  processStillRunning: true,
}, null, 2));
'

Output:

{
  "mode": "spawned",
  "pid": null,
  "hasChild": true,
  "childError": "ENOENT:true",
  "processStillRunning": true
}

Targeted test proof:

$ node scripts/run-vitest.mjs src/infra/process-respawn.test.ts
[test] starting test/vitest/vitest.infra.config.ts
[test] passed 1 Vitest shard in 18.07s

Observed result: The production respawn path returned a spawned child, the missing executable emitted ENOENT, and the parent process stayed alive long enough to print processStillRunning: true. The targeted test shard also passed, including the assertion that child.on("error", ...) is registered before child.unref() and that invoking the captured error listener does not throw.

Not tested: Full live OpenClaw package update respawn with a real gateway process was not run; the proof exercises the same production respawn function and Node child-process error path with a deliberately missing executable.

Root Cause

• spawnDetachedGatewayProcess() spawned and unref'd the detached update child without attaching an error listener.
• Node treats an emitted error event without a listener as an unhandled exception, so asynchronous spawn failures can terminate the parent process.

Regression Test Plan

• src/infra/process-respawn.test.ts now covers the detached update respawn path and asserts that the error listener is attached before unref().
• Existing process respawn tests continue to cover supervised, disabled, rewrite, and synchronous spawn failure paths.

Verification

• node --import tsx --no-warnings -e '...' production-function proof passed and printed processStillRunning: true.
• node scripts/run-vitest.mjs src/infra/process-respawn.test.ts passed.
• git diff --check passed.

Impact Assessment

• Scope: one helper in the gateway update respawn path plus its colocated tests.
• Downstream: respawnGatewayProcessForUpdate() keeps returning the spawned child and pid; detached process behavior is unchanged except async child errors are consumed best-effort.
• Edge cases: synchronous spawn() throws still return mode: "failed"; asynchronous ChildProcess errors after spawn are now handled.
• Hard-coded values: none introduced.
• Existing fixes: user-specified issue, so competing PR search was intentionally skipped unless requested.
• Import paths: no new imports were added.

User-visible / Behavior Changes

Gateway update respawn is more resilient when a detached child emits an asynchronous spawn error such as ENOENT or ENOMEM.

Security Impact

• New permissions: No
• Secrets handling changed: No
• New network calls: No

Closes #101458