fix(gateway): catch lazy import rejections in runtime event subscriptions by cxbAsDev · Pull Request #100401 · openclaw/openclaw

cxbAsDev · 2026-07-05T17:55:34Z

What Problem This Solves

Gateway runtime subscriptions deliberately fire three lazy event handlers without awaiting them. On current main, a rejected module load, handler construction, synchronous handler call, or returned promise can escape that fire-and-forget boundary as an unhandled rejection.

Why This Change Was Made

The final implementation keeps event delivery asynchronous but routes agent, transcript, and lifecycle dispatch through one local helper that owns the rejection boundary. Failures are logged with the relevant run or session identifiers. The existing Gateway subsystem logger is passed from the only production caller.

The maintainer fixup also corrects the original warning semantics: the catch covers handler execution as well as lazy loading, so the log reports a dispatch failure rather than claiming every failure came from an import. Typed test parameters repair the original check-test-types failure.

User Impact

Transient Gateway event-handler failures no longer surface as unexplained process-level unhandled rejections. Operators get an actionable warning while unrelated Gateway subscriptions continue running.

Evidence

Regression test: src/gateway/server-runtime-subscriptions.test.ts covers a rejected dynamic import plus transcript and lifecycle handler execution failures.
The test fixture now uses Parameters<typeof startGatewayEventSubscriptions>[0], satisfying the concrete chat-abort and restart-recovery map types.
Exact-head structured AutoReview on 007793be877c51c4fc095ac2a342f029f5faaf1f: clean, no actionable findings.
git diff --check origin/main...HEAD: passed.
Exact-head hosted CI: https://github.com/openclaw/openclaw/actions/runs/28760630435

AI assistance: Codex performed maintainer review, implementation cleanup, focused proof selection, and landing preparation.

clawsweeper · 2026-07-05T18:04:59Z

Codex review: needs real behavior proof before merge. Reviewed July 5, 2026, 8:48 PM ET / 00:48 UTC.

Summary
Adds a Gateway runtime subscription helper that catches and logs lazy event-handler failures, passes the Gateway logger from startup, adds regression tests, and edits CHANGELOG.md.

PR surface: Source +36, Tests +120, Docs +1. Total +157 across 4 files.

Reproducibility: yes. Current main source shows three fire-and-forget lazy event dispatches without catch handlers, and the PR tests exercise the rejected module and handler failure paths.

Review metrics: 1 noteworthy metric.

Release-owned files changed: 1 changed. CHANGELOG.md is owned by release generation, so this otherwise narrow Gateway fix has one process-sensitive edit to remove.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

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

Rank-up moves:

Remove the CHANGELOG.md entry; the PR body already has release-note context.
[P1] Add redacted live/log proof of a Gateway lazy subscriber failure being contained, or get an explicit proof override.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR supplies regression tests, CI, and maintainer validation notes, but no redacted live Gateway fault-injection logs or terminal output; add real behavior proof and redact IPs, keys, phone numbers, and private endpoints before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] Real behavior proof is still mock/CI-only; no redacted live Gateway fault-injection transcript or logs show the process-level rejection containment after the fix.
[P1] The manual CHANGELOG.md entry conflicts with the release-owned changelog workflow and should be removed before merge.

Maintainer options:

Decide the mitigation before merge
Land the runtime and regression-test fix after removing the changelog line and adding redacted live/log proof or an explicit proof override.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P1] Human/contributor follow-up is needed because proof is mock/CI-only and the changelog edit must be removed; ClawSweeper should not queue repair while the proof gate is unsatisfied.

Security
Cleared: The diff only changes local Gateway rejection handling, tests, and a changelog line; it does not alter dependencies, workflows, secrets, permissions, packaging, or executable supply-chain inputs.

Review findings

[P3] Remove the release-owned changelog edit — CHANGELOG.md:22

Review details

Best possible solution:

Land the runtime and regression-test fix after removing the changelog line and adding redacted live/log proof or an explicit proof override.

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

Yes. Current main source shows three fire-and-forget lazy event dispatches without catch handlers, and the PR tests exercise the rejected module and handler failure paths.

Is this the best way to solve the issue?

Yes for the runtime code: catching at the subscription-owned fire-and-forget boundary is the narrow maintainable fix. The changelog edit is not part of the best solution and should be removed.

Full review comments:

[P3] Remove the release-owned changelog edit — CHANGELOG.md:22
Root AGENTS.md says CHANGELOG.md is release-only and normal PRs should put release-note context in the PR body or squash message. This PR already has release-note context in the body, so keeping this manual entry creates release-generation churn; this re-raises the prior ClawSweeper finding on the current head.
Confidence: 0.96

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.

Label justifications:

P2: This is a focused Gateway availability fix for unhandled promise rejections with limited blast radius and no release-blocker evidence.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.

Evidence reviewed

PR surface:

Source +36, Tests +120, Docs +1. Total +157 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	2	39	3	+36
Tests	1	120	0	+120
Docs	1	1	0	+1
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	4	160	3	+157

What I checked:

Repository policy read: Root and scoped Gateway AGENTS.md were read; the root changelog rule affected the finding, and the Gateway guide raised the proof bar for lazy-loading changes. (AGENTS.md:238, 95f12178a794)
Current main rejection boundary: Current main fires agent, transcript, and lifecycle lazy handlers with void ...then(...) and no rejection handler, so a rejected load or handler can escape the subscription boundary. (src/gateway/server-runtime-subscriptions.ts:237, 95f12178a794)
PR runtime catch: The PR head adds dispatchEventHandler, which catches load, construction, synchronous handler, and returned-promise failures and logs bounded event context. (src/gateway/server-runtime-subscriptions.ts:20, 007793be877c)
Production caller wiring: The only production caller now passes the existing Gateway subsystem logger into startGatewayEventSubscriptions. (src/gateway/server.impl.ts:1180, 007793be877c)
Regression coverage: The new test covers a rejected lazy agent module plus transcript and lifecycle handler failures through the subscription entry point. (src/gateway/server-runtime-subscriptions.test.ts:82, 007793be877c)
Release-owned changelog edit: The PR head still adds a manual CHANGELOG.md entry even though repository policy says normal PRs should leave changelog generation to release tooling. (CHANGELOG.md:22, 007793be877c)

Likely related people:

Vincent Koc: Blame on the current Gateway runtime subscription file and lazy handler call sites points to the commit that introduced the current source shape. (role: introduced current-main behavior; confidence: high; commits: aa665817490b; files: src/gateway/server-runtime-subscriptions.ts, src/gateway/server-chat.ts, src/gateway/server-session-events.ts)
steipete: He is assigned on this PR, authored the consolidation/changelog commits on the PR branch, and posted the land-ready maintainer pass. (role: recent PR reviewer and likely follow-up owner; confidence: high; commits: 00e5c550e757, 007793be877c, 95f12178a794; files: src/gateway/server-runtime-subscriptions.ts, src/gateway/server-runtime-subscriptions.test.ts, CHANGELOG.md)

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 (2 earlier review cycles)

reviewed 2026-07-05T18:08:08.595Z sha dd37138 :: needs real behavior proof before merge. :: [P2] Use typed gateway test maps
reviewed 2026-07-06T00:33:25.447Z sha b516390 :: needs real behavior proof before merge. :: [P3] Remove the release-owned changelog edit

steipete · 2026-07-06T00:40:07Z

Land-ready maintainer pass complete.

Final head: 007793be877c51c4fc095ac2a342f029f5faaf1f.
Fixup: one subscription-owned rejection boundary now covers lazy loading, handler construction, synchronous throws, and returned-promise rejection for agent, transcript, and lifecycle events; warnings retain bounded event context.
Regression proof: src/gateway/server-runtime-subscriptions.test.ts covers a real dynamic-import rejection and transcript/lifecycle handler failures.
Review: exact-head structured AutoReview is clean with no actionable findings.
Static proof: git diff --check origin/main...HEAD passed; hosted test types, production types, lint, build artifacts, and focused/full Node shards passed.
Hosted proof: final post-sync exact-head CI https://github.com/openclaw/openclaw/actions/runs/28760630435 passed on attempt 1. On the preceding identical code tree, CI https://github.com/openclaw/openclaw/actions/runs/28759867780 passed on attempt 2 after attempt 1 lost its Blacksmith runner connection without a product assertion.
Native gate: OPENCLAW_TESTBOX=1 scripts/pr prepare-run 100401 passed on the final exact head in hosted_exact_head mode.

Known proof gap: no manual live Gateway fault injection was added beyond the deterministic module/handler regression tests. The failure boundary itself is exercised directly.

…ions

steipete · 2026-07-06T00:53:16Z

Merged via squash.

Prepared head SHA: 007793be877c51c4fc095ac2a342f029f5faaf1f
Landed commit: 5a31666a06e53bbae8840ea587209308ed7b12b6

…ions (openclaw#100401) * fix(gateway): catch lazy import rejections in runtime event subscriptions * fix(gateway): consolidate event dispatch failures * docs(changelog): note gateway event dispatch fix --------- Co-authored-by: Peter Steinberger <[email protected]>

openclaw-barnacle Bot added gateway Gateway runtime size: S labels Jul 5, 2026

steipete self-assigned this Jul 5, 2026

steipete force-pushed the fix/gateway-runtime-subscriptions-catch branch 2 times, most recently from cecb4e1 to 7ca2bba Compare July 6, 2026 00:02

clawsweeper Bot removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 6, 2026

openclaw-barnacle Bot added docs Improvements or additions to documentation app: ios App: ios scripts Repository scripts size: XL and removed size: S labels Jul 6, 2026

steipete force-pushed the fix/gateway-runtime-subscriptions-catch branch from 51fc6f5 to b516390 Compare July 6, 2026 00:14

openclaw-barnacle Bot added size: S and removed docs Improvements or additions to documentation app: ios App: ios scripts Repository scripts size: XL labels Jul 6, 2026

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 6, 2026

cxbAsDev and others added 3 commits July 5, 2026 20:40

fix(gateway): catch lazy import rejections in runtime event subscript…

24c1a06

…ions

fix(gateway): consolidate event dispatch failures

00e5c55

docs(changelog): note gateway event dispatch fix

007793b

clawsweeper Bot removed the rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. label Jul 6, 2026

openclaw-barnacle Bot added the docs Improvements or additions to documentation label Jul 6, 2026

openclaw-barnacle Bot added channel: discord Channel integration: discord channel: slack Channel integration: slack channel: telegram Channel integration: telegram scripts Repository scripts agents Agent runtime and tooling labels Jul 6, 2026

clawsweeper Bot removed the status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. label Jul 6, 2026

openclaw-barnacle Bot added size: XL and removed size: S labels Jul 6, 2026

steipete force-pushed the fix/gateway-runtime-subscriptions-catch branch from 4cbb940 to 007793b Compare July 6, 2026 00:41

steipete merged commit 5a31666 into openclaw:main Jul 6, 2026
119 of 122 checks passed

clawsweeper Bot mentioned this pull request Jul 6, 2026

fix(ios): keep While Using selected after approval #100512

Merged

ajwan8998 mentioned this pull request Jul 6, 2026

fix(acp): catch unhandled rejection from handleGatewayEvent in event callback #100558

Merged

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

📡 Upstream Digest — 2026-07-06 02:26 UTC curtismercier/openclaw-mods#1220

Open

cxbAsDev deleted the fix/gateway-runtime-subscriptions-catch branch July 15, 2026 03:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(gateway): catch lazy import rejections in runtime event subscriptions#100401

fix(gateway): catch lazy import rejections in runtime event subscriptions#100401
steipete merged 3 commits into
openclaw:mainfrom
cxbAsDev:fix/gateway-runtime-subscriptions-catch

cxbAsDev commented Jul 5, 2026 •

edited by steipete

Loading

Uh oh!

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

steipete commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

cxbAsDev commented Jul 5, 2026 • edited by steipete 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 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

steipete commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cxbAsDev commented Jul 5, 2026 •

edited by steipete

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

steipete commented Jul 6, 2026 •

edited

Loading