Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Document PluginHookSessionEndReason shutdown/restart contract + 2s drain budget for plugin maintainers; add migration notes (downstream gap example: Martian-Engineering/lossless-claw#668) [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#81310•Fetched 2026-05-14 03:33:31
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
2
Author
CaldereinCalderein
Participants
CaldereinCaldereinclawsweeper[bot]clawsweeper[bot]
Timeline (top)
commented ×1cross-referenced ×1

OpenClaw 5.10-beta.2 added "shutdown" and "restart" values to PluginHookSessionEndReason (via #57790) with a 2-second total drain budget for plugin work at gateway termination. The new reasons + budget are correct + intentional — the docstring "a slow plugin cannot block process exit" is the right contract.

However, downstream plugin maintainers may not realize they need to fast-path on these new reasons. We've identified one concrete example where a downstream plugin falls through to heavy work and may be truncated mid-write:

This is a downstream-plugin bug, not an openclaw bug — but it's symptomatic of a missing-migration-note: plugin maintainers don't necessarily know they need to update their handlers for the new contract.

Error Message

2. One-shot warn-log when drain budget truncates a plugin

Currently, drain-budget truncation is silent from the operator perspective. A warn-log when a plugin's session_end work exceeds the 2s budget would:

  • (Optional) One-shot warn-log when a plugin's session_end work exceeds the drain budget

Root Cause

OpenClaw 5.10-beta.2 added "shutdown" and "restart" values to PluginHookSessionEndReason (via #57790) with a 2-second total drain budget for plugin work at gateway termination. The new reasons + budget are correct + intentional — the docstring "a slow plugin cannot block process exit" is the right contract.

However, downstream plugin maintainers may not realize they need to fast-path on these new reasons. We've identified one concrete example where a downstream plugin falls through to heavy work and may be truncated mid-write:

This is a downstream-plugin bug, not an openclaw bug — but it's symptomatic of a missing-migration-note: plugin maintainers don't necessarily know they need to update their handlers for the new contract.

Fix Action

Fixed

PR fix notes

PR #81503: docs(plugins): document session end shutdown budget

Description (problem / solution / changelog)

Summary

  • document the shutdown and restart session_end reasons as shutdown-finalizer events
  • call out the 2-second total drain budget for plugin session_end work
  • advise plugin maintainers to fast-path or make persistence crash-consistent for shutdown/restart handling

Fixes #81310.

Verification

  • pnpm docs:list
  • git diff --check docs/plugins/hooks.md
  • sed -n '132,139p' docs/plugins/hooks.md

Real behavior proof

  • Behavior addressed: the plugin hooks docs now state that shutdown and restart session_end reasons run during gateway shutdown/restart finalization, with a 2-second total drain budget and bounded/crash-consistent plugin guidance.
  • Real environment tested: local OpenClaw docs checkout on macOS, reading the real docs/plugins/hooks.md file after the patch and running the repo docs inventory command.
  • Exact steps or command run after this patch: pnpm docs:list; git diff --check docs/plugins/hooks.md; sed -n '132,139p' docs/plugins/hooks.md
  • Evidence after fix:
$ pnpm docs:list
Listing all markdown files in docs folder:
AGENTS.md - [missing front matter]
...
Reminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above (React hooks, cache directives, database work, tests, etc.), read that doc before coding, and suggest new coverage when it is missing.

$ git diff --check docs/plugins/hooks.md
(no output; exit code 0)

$ sed -n '132,139p' docs/plugins/hooks.md
- **`before_dispatch`** - inspect or rewrite an outbound dispatch before channel handoff
- **`reply_dispatch`** - participate in the final reply-dispatch pipeline

**Sessions and compaction**

- `session_start` / `session_end` - track session lifecycle boundaries. The event's `reason` is one of `new`, `reset`, `idle`, `daily`, `compaction`, `deleted`, `shutdown`, `restart`, or `unknown`. The `shutdown` and `restart` values fire from the gateway shutdown finalizer when the process is stopped or restarted while sessions are still active, so downstream plugins (such as memory or transcript stores) can finalize ghost rows that would otherwise be left in an open state across restarts. The shutdown finalizer has a 2-second total drain budget for plugin `session_end` work, so plugins should fast-path those reasons with an early return or bounded finalize path. If a plugin needs heavier persistence, make that path crash-consistent and tolerant of partial writes because slow handlers may be truncated when the process exits.
- `before_compaction` / `after_compaction` - observe or annotate compaction cycles
- `before_reset` - observe session-reset events (`/reset`, programmatic resets)
  • Observed result after fix: the terminal output shows the Sessions and compaction section includes the 2-second total drain budget and tells plugins to fast-path shutdown/restart or use crash-consistent bounded persistence.
  • What was not tested: no live gateway shutdown/restart was run because this PR is documentation-only; runtime behavior is covered by the existing implementation/tests referenced in the linked issue and ClawSweeper review.

Changed files

  • docs/plugins/hooks.md (modified, +1/-1)
RAW_BUFFERClick to expand / collapse

Summary

OpenClaw 5.10-beta.2 added "shutdown" and "restart" values to PluginHookSessionEndReason (via #57790) with a 2-second total drain budget for plugin work at gateway termination. The new reasons + budget are correct + intentional — the docstring "a slow plugin cannot block process exit" is the right contract.

However, downstream plugin maintainers may not realize they need to fast-path on these new reasons. We've identified one concrete example where a downstream plugin falls through to heavy work and may be truncated mid-write:

This is a downstream-plugin bug, not an openclaw bug — but it's symptomatic of a missing-migration-note: plugin maintainers don't necessarily know they need to update their handlers for the new contract.

Request

Two complementary changes that would help downstream maintainers + operators:

1. Document the contract in plugin-API reference

Under PluginHookSessionEndReason, note that:

  • shutdown + restart reasons fire during a bounded 2-second total drain budget at gateway termination
  • Plugin maintainers should either: (a) fast-path on these reasons (early-return or bounded-finalize), OR (b) implement crash-consistent / partial-write-tolerant work paths
  • Slow plugin handlers risk truncation mid-execution

2. One-shot warn-log when drain budget truncates a plugin

Currently, drain-budget truncation is silent from the operator perspective. A warn-log when a plugin's session_end work exceeds the 2s budget would:

  • Surface latent bugs (like lossless-claw#668) in production
  • Give operators something concrete to file upstream / triage
  • Cost: one log line per truncated plugin per shutdown

3. (Optional, lower priority) CHANGELOG migration note

Short note for plugin maintainers in 5.10-beta.2's CHANGELOG entry (or future releases that touch PluginHookSessionEndReason) about the new reasons + contract expectations.

Cross-references

  • Original PR: #57790 "Gateway shutdown/restart does not fire session_end for active sessions" (CLOSED) — the feature-add this issue follows up on
  • Downstream gap (concrete example): https://github.com/Martian-Engineering/lossless-claw/issues/668 "Plugin session_end handler does not recognize new shutdown/restart reasons from OpenClaw 5.10-beta.2+"
  • Adjacent plugin verified clean (no gap, reason-agnostic by design): claude-mem — handler ignores reason + does pure in-memory cleanup → benefits cleanly from #57790 without code change. Good reference for how to write a session_end handler that's compatible with the new contract.

Environment

  • OpenClaw 5.9-beta.1 + lossless-claw 0.9.4 installed locally
  • Issue identified during 5.12-beta.4 changelog read against installed plugin source
  • Constellation chair-team multi-entity environment

Acceptance Criteria

  • Plugin-API reference documents the shutdown/restart reasons + 2s drain budget contract
  • (Optional) One-shot warn-log when a plugin's session_end work exceeds the drain budget
  • (Optional) CHANGELOG migration note added retroactively to 5.10-beta.2 (or going forward) for plugin maintainers

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#installation#tensor shape#autograd error#model save/load

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix Document PluginHookSessionEndReason shutdown/restart contract + 2s drain budget for plugin maintainers; add migration notes (downstream gap example: Martian-Engineering/lossless-claw#668) [1 pull requests, 1 comments, 2 participants]