fix(infra): handle detached respawn child errors by momothemage · Pull Request #101489 · openclaw/openclaw

momothemage · 2026-07-07T08:17:04Z

What Problem This Solves

Fixes #101458. Detached gateway update respawns can emit an asynchronous ChildProcess error after spawn() returns; without a listener, Node treats that as unhandled and crashes the current process.

Why This Change Was Made

The detached respawn path now attaches a best-effort error listener before unref(), matching the existing restart-helper pattern. The update handoff still returns the child/pid when spawn succeeds, and synchronous spawn failures still flow through the existing failed result.

User Impact

Users hitting a missing or invalid executable during detached update respawn no longer get an extra uncaught child-process error on the parent process.

Evidence

npx -y [email protected] real ChildProcess probe with a missing detached executable:

## without-listener
node=v24.18.0
exit=1 signal=none
stdout=""
stderr-summary=["      throw er; // Unhandled 'error' event","Error: spawn /tmp/openclaw-missing-detached-gateway-1957 ENOENT","  code: 'ENOENT',"]
## with-listener
node=v24.18.0
exit=0 signal=none
stdout="handled child error: ENOENT\nparent still alive"
stderr-summary=[]

node scripts/run-vitest.mjs src/infra/process-respawn.test.ts
git diff --check
OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 CI=1 PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false pnpm check:changed -- src/infra/process-respawn.ts src/infra/process-respawn.test.ts

clawsweeper · 2026-07-07T08:33:38Z

Codex review: passed. Reviewed July 7, 2026, 6:28 AM ET / 10:28 UTC.

Summary
The branch adds a no-op ChildProcess error listener before unref in the detached gateway update respawn helper and adds focused regression coverage for listener ordering and no-throw behavior.

PR surface: Source +3, Tests +30. Total +33 across 2 files.

Reproducibility: yes. source-level reproduction is high confidence: current main lacks the child error listener, and a direct Node v24.18.0 probe shows the missing-executable child error crashes without a listener and survives with one. I did not run a full OpenClaw package update respawn E2E.

Review metrics: none identified.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #101458
Summary: This PR is a candidate fix for the open detached gateway respawn ChildProcess error issue; the related closed PRs are parallel attempts at the same listener-before-unref repair.

Members:

canonical: Unhandled error on detached spawned gateway process crashes the Node process #101458 - The PR body uses closing syntax for this open issue, and the issue describes the same missing ChildProcess error listener in spawnDetachedGatewayProcess().
superseded: fix(infra): add error listener to detached spawned gateway process to prevent crashes #101482 - Closed unmerged parallel PR proposing the same production listener and colocated regression coverage.
superseded: fix(infra): attach error listener to detached spawn to prevent unhandled rejection crash #101487 - Closed unmerged parallel PR for the same missing detached spawn error listener.
superseded: fix(infra): add error listener to spawnDetachedGatewayProcess to prevent crash on async spawn failure #101490 - Closed unmerged parallel PR for the same async detached spawn failure crash path.
superseded: fix(infra): register no-op error handler on detached gateway spawn child #101491 - Closed unmerged parallel PR using the same restart-helper listener-before-unref precedent.
2 more in the report.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Refresh or validate the exact merge head because live GitHub reports the branch as BEHIND.
[P2] Resolve the failing dispatch check if it remains required by branch protection.

Risk before merge

[P1] The live PR is mergeable but BEHIND current base, so landing should use an exact merge-head refresh or validation.
[P1] The proof covers the Node child_process failure mode and focused regression tests, not a full live OpenClaw package update respawn.

Maintainer options:

Decide the mitigation before merge
Land this focused listener-before-unref fix as the canonical fix for Unhandled error on detached spawned gateway process crashes the Node process #101458 after exact-head validation.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

No automated repair is needed; the patch is clean and the automerge or maintainer gate should handle exact-head validation before landing.

Security
Cleared: The diff only adds a ChildProcess error listener plus test mocks/assertions, with no new dependencies, permissions, secrets handling, workflow changes, or supply-chain surface.

Review details

Best possible solution:

Land this focused listener-before-unref fix as the canonical fix for #101458 after exact-head validation.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level reproduction is high confidence: current main lacks the child error listener, and a direct Node v24.18.0 probe shows the missing-executable child error crashes without a listener and survives with one. I did not run a full OpenClaw package update respawn E2E.

Is this the best way to solve the issue?

Yes. Attaching a best-effort child error listener immediately after spawn and before unref is the narrowest maintainable fix, matches the sibling restart-helper pattern, and preserves the existing unhealthy-child fallback path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against cba20f9aec7b.

Label changes

Label changes:

add status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (terminal): The PR body includes terminal after-fix proof showing the missing-executable case crashes without a listener and stays alive with the listener installed, plus targeted test and changed-check commands.
remove status: 👀 ready for maintainer look: Current PR status label is status: 🚀 automerge armed.

Label justifications:

P2: This PR fixes a normal-priority gateway update availability bug with a narrow source change and limited blast radius.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (terminal): The PR body includes terminal after-fix proof showing the missing-executable case crashes without a listener and stays alive with the listener installed, plus targeted test and changed-check commands.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal after-fix proof showing the missing-executable case crashes without a listener and stays alive with the listener installed, plus targeted test and changed-check commands.

Evidence reviewed

PR surface:

Source +3, Tests +30. Total +33 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	3	0	+3
Tests	1	34	4	+30
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	2	37	4	+33

What I checked:

Repository policy read: Root AGENTS.md was read fully, no scoped AGENTS.md owns src/infra, and the review applied the root high-confidence process/security PR-review guidance. (AGENTS.md:1, 42e2390b3144)
Current main lacks the listener: On current origin/main, spawnDetachedGatewayProcess spawns the detached child, immediately calls child.unref(), and returns it without an error listener. (src/infra/process-respawn.ts:51, cba20f9aec7b)
PR head installs the handler before unref: The PR head adds a comment explaining asynchronous detached spawn failures and calls child.on("error", () => {}) before child.unref(). (src/infra/process-respawn.ts:56, 0d8c38ef50a0)
Regression coverage: The new test exercises respawnGatewayProcessForUpdate, verifies the child error listener is installed, invokes it without throwing, and asserts listener registration precedes unref. (src/infra/process-respawn.test.ts:398, 0d8c38ef50a0)
Caller fallback path: The gateway run loop already treats unhealthy update respawn children as best-effort, kills them if present, marks sentinel failure, and falls back to in-process restart. (src/cli/gateway-cli/run-loop.ts:210, cba20f9aec7b)
Sibling detached-spawn precedent: The update restart-script helper already uses the same detached spawn pattern with child.on("error", () => {}) before child.unref(). (src/cli/update-cli/restart-helper.ts:417, cba20f9aec7b)

Likely related people:

steipete: git blame on current origin/main attributes the central spawnDetachedGatewayProcess helper and run-loop update respawn path to Peter Steinberger, and shortlog shows the heaviest history across the relevant respawn/run-loop files. (role: current respawn path owner; confidence: high; commits: 82b0f7cdc88d; files: src/infra/process-respawn.ts, src/infra/process-respawn.test.ts, src/cli/gateway-cli/run-loop.ts)
ZOOWH: Recent managed update handoff work changed process-respawn, process-respawn tests, the gateway run loop, and update handoff timing around the same update-restart surface. (role: recent adjacent contributor; confidence: medium; commits: b8b946e43db8, 46493bc867dc; files: src/infra/process-respawn.ts, src/infra/process-respawn.test.ts, src/cli/gateway-cli/run-loop.ts)
giodl73-repo: The sibling update restart-helper fix added the same best-effort detached child error listener before unref in another restart handoff path. (role: sibling pattern contributor; confidence: medium; commits: 566d8cdf3995; files: src/cli/update-cli/restart-helper.ts, src/cli/update-cli/restart-helper.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (3 earlier review cycles)

reviewed 2026-07-07T08:38:11.347Z sha 2d9b586 :: needs real behavior proof before merge. :: none
reviewed 2026-07-07T09:07:18.762Z sha 69fc48f :: needs maintainer review before merge. :: none
reviewed 2026-07-07T09:16:51.492Z sha 69fc48f :: needs maintainer review before merge. :: none

momothemage · 2026-07-07T08:43:57Z

@clawsweeper re-review

clawsweeper · 2026-07-07T08:44:01Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

momothemage · 2026-07-07T09:34:28Z

@clawsweeper automerge

clawsweeper · 2026-07-07T09:34:31Z

ClawSweeper 🐠 automerge status

ClawSweeper took another look; no safe branch change was available on this pass.

Executor outcome: no planned fix actions.
Worker summary: Canonical this PR is already closed and its fix is present on current main. Current main registers a detached child error listener before unref and includes focused regression coverage, so no merge, close, or repair PR action is needed.

Worker actions:

keep_closed on this PR: skipped - Already closed; canonical fix is present on current main.
keep_closed on #101458: skipped - Already closed; covered by the canonical fix path.
keep_closed on #101482: skipped - Already closed; superseded by the canonical adopted PR path.
keep_closed on #101487: skipped - Already closed; no closure or repair action is valid.
keep_closed on #101490: skipped - Already closed; no closure or repair action is valid.
keep_closed on #101491: skipped - Already closed; no closure or repair action is valid.

This pass stayed observational only. No branch push, replacement, merge, or re-review was started.

fish notes: reasoning high; reviewed against 918c4da.

Automerge progress:

2026-07-07 10:32:54 UTC validation plan (passed) in 22s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 pnpm check:changed; pnpm lint; pnpm check:test-types

2026-07-07 10:33:03 UTC Codex write preflight (passed) in 32s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 danger-full-access

2026-07-07 10:36:07 UTC Codex edit 1 a8206481603c (complete) in 3m 35s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 exit 0

2026-07-07 10:38:27 UTC validation and review 1 918c4daab0fe (complete) in 5m 55s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 already-current

2026-07-07 10:40:02 UTC repair completed 918c4daab0fe (branch updated) in 7m 31s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 initial automerge rebase is delegated to Codex repair

2026-07-07 10:40:01 UTC review queued 918c4daab0fe (after repair)

2026-07-07 10:50:05 UTC automerge wait 918c4daab0fe (waiting) in 17m 34s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 waiting for exact-head ClawSweeper review pass

2026-07-07 10:50:06 UTC repair finished 918c4daab0fe (pushed) in 17m 35s Run: https://github.com/openclaw/clawsweeper/actions/runs/28859535116 repair_contributor_branch

2026-07-07 10:52:22 UTC repair started (running) in 0s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 automerge-openclaw-openclaw-101489

2026-07-07 10:52:44 UTC validation plan (passed) in 22s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 pnpm check:changed; pnpm lint; pnpm check:test-types

2026-07-07 10:52:55 UTC Codex write preflight (passed) in 33s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 danger-full-access

2026-07-07 10:56:04 UTC Codex edit 1 695fa4e112f1 (complete) in 3m 42s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 exit 0

2026-07-07 11:13:13 UTC validation and review 1 7c1fa04895ee (base moved) in 20m 51s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 rebased

2026-07-07 11:13:27 UTC repair finished 7c1fa04895ee (opened) in 21m 5s Run: https://github.com/openclaw/clawsweeper/actions/runs/28860413312 open_fix_pr

2026-07-07 11:54:14 UTC repair started (running) in 0s Run: https://github.com/openclaw/clawsweeper/actions/runs/28863930775 automerge-openclaw-openclaw-101489

2026-07-07 11:54:17 UTC repair completed 918c4daab0fe (no branch change) in 4s Run: https://github.com/openclaw/clawsweeper/actions/runs/28863930775 no planned fix actions

vincentkoc · 2026-07-07T10:51:19Z

Land-ready maintainer verification:

Exact PR head: 918c4da
Focused proof: node scripts/run-vitest.mjs src/infra/process-respawn.test.ts — 26 passed
Remote changed gate: Blacksmith Testbox tbx_01kwy2wbcmjfx77se24xffd8ft — pnpm check:changed passed on the same production patch with a stricter EventEmitter-backed regression
Fresh exact-head autoreview: clean, no accepted/actionable findings
Hosted exact-head CI: https://github.com/openclaw/openclaw/actions/runs/28860048802 — 47 jobs passed
Behavior checked: successful detached handoff, synchronous spawn failure, asynchronous child error, and caller health-check fallback

Known gap: no destructive end-to-end self-update restart was run. The direct Node contract proof, focused lifecycle test, caller fallback review, remote changed gate, and exact-head CI cover this narrow failure mode.

vincentkoc · 2026-07-07T10:52:01Z

Merged via squash.

Prepared head SHA: 918c4daab0fe1096827cea3db520a2e8687697c3
Landed commit: 695fa4e112f1e60371ec6aeadf7cca6ef86609e6

* fix(infra): handle detached respawn child errors * docs(infra): explain detached respawn error listener * fix(infra): handle detached respawn child errors * fix(infra): handle detached respawn child errors --------- Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>

openclaw-barnacle Bot added size: XS maintainer Maintainer-authored PR labels Jul 7, 2026

clawsweeper Bot mentioned this pull request Jul 7, 2026

fix(infra): add error listener to detached spawned gateway process to prevent crashes #101482

Closed

clawsweeper Bot mentioned this pull request Jul 7, 2026

fix(infra): attach error listener to detached spawn to prevent unhandled rejection crash #101487

Closed

2 tasks

This was referenced Jul 7, 2026

fix(infra): add error listener to spawnDetachedGatewayProcess to prevent crash on async spawn failure #101490

Closed

fix(infra): register no-op error handler on detached gateway spawn child #101491

Closed

vincentkoc mentioned this pull request Jul 7, 2026

fix(infra): handle detached respawn child errors #101502

Closed

14 tasks

clawsweeper Bot mentioned this pull request Jul 7, 2026

fix: handle detached gateway spawn errors #101515

Closed

clawsweeper Bot added the clawsweeper:automerge Maintainer opted this PR into bounded ClawSweeper-reviewed automerge label Jul 7, 2026

clawsweeper Bot force-pushed the feature/issue-101458-detached-spawn-error branch from 69fc48f to 0d8c38e Compare July 7, 2026 10:11

clawsweeper Bot added status: 🚀 automerge armed This PR is in ClawSweeper's automerge lane. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jul 7, 2026

momothemage and others added 4 commits July 7, 2026 10:33

fix(infra): handle detached respawn child errors

a9ec059

docs(infra): explain detached respawn error listener

0f8860c

fix(infra): handle detached respawn child errors

a820648

fix(infra): handle detached respawn child errors

918c4da

clawsweeper Bot force-pushed the feature/issue-101458-detached-spawn-error branch from 0d8c38e to 918c4da Compare July 7, 2026 10:40

vincentkoc self-assigned this Jul 7, 2026

vincentkoc merged commit 695fa4e into main Jul 7, 2026
101 of 102 checks passed

vincentkoc deleted the feature/issue-101458-detached-spawn-error branch July 7, 2026 10:51

This was referenced Jul 7, 2026

fix(infra): handle detached respawn child errors #101593

Open

fix(infra): attach error listener to detached spawn in windows-task-restart #101528

Closed

github-actions Bot mentioned this pull request Jul 7, 2026

📡 Upstream Digest — 2026-07-07 14:10 UTC curtismercier/openclaw-mods#1230

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(infra): handle detached respawn child errors#101489

fix(infra): handle detached respawn child errors#101489
vincentkoc merged 4 commits into
mainfrom
feature/issue-101458-detached-spawn-error

momothemage commented Jul 7, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

momothemage commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

momothemage commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jul 7, 2026

Uh oh!

Uh oh!

vincentkoc commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

momothemage commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

momothemage commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

momothemage commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vincentkoc commented Jul 7, 2026

Uh oh!

Uh oh!

vincentkoc commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

momothemage commented Jul 7, 2026 •

edited

Loading

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading