Fixes #57790.

session_end was only fired when a session was replaced, reset, deleted, or compacted -- the gateway shutdown/restart paths closed the process without enumerating active sessions, so downstream session_end plugins (e.g. claude-mem) accumulated ghost rows in active state across restarts. Issue reporter saw 11 orphaned sessions cause 63 timeouts/day from agent pool exhaustion.

ClawSweeper triage explicitly cleared this as "Queue a focused fix PR because the affected path, compatibility boundary, likely files, and regression tests are clear" with reproducibility confirmed at the source level.

Change

• New in-memory tracker (src/gateway/active-sessions-shutdown-tracker.ts) keyed by sessionId. Populated by emitGatewaySessionStartPluginHook and forgotten unconditionally by emitGatewaySessionEndPluginHook (even when no plugin currently listens), so any session that has already been finalized through replace / reset / delete / compaction is never re-fired by the shutdown drain.
• New drainActiveSessionsForShutdown({ reason }) in src/gateway/session-reset-service.ts. Iterates the tracker, fires the same emitGatewaySessionEndPluginHook the normal lifecycle path uses, and races a bounded 2 s total timeout so a slow plugin cannot block SIGTERM/SIGINT.
• createGatewayCloseHandler wires the drain between the existing gateway:shutdown/gateway:pre-restart lifecycle hooks and the subsystem teardown steps. Reason resolves to restart when restartExpectedMs is set, otherwise shutdown. Drain timeout surfaces on the shutdown result as a session-end-drain warning so operators can spot a hanging plugin without losing the process.
• PluginHookSessionEndReason gains "shutdown" and "restart". emitGatewaySessionStartPluginHook now also accepts storePath, sessionFile, and agentId so the shutdown drain can build the same session_end payload shape the normal lifecycle emits; the two existing call sites (server-methods/sessions.ts create path and session-reset-service.ts reset path) pass those through.

Docs:

• docs/plugins/hooks.md documents the new shutdown/restart reason values.
• docs/automation/hooks.md documents the post-gateway:shutdown drain and its bounded execution.

Verification

• pnpm test src/gateway/active-sessions-shutdown-tracker.test.ts src/gateway/drain-active-sessions-for-shutdown.test.ts src/gateway/server-close.test.ts -- 35/35 pass (19 new tracker + drain cases, plus 4 new close-handler cases for the shutdown/restart drain wiring).
• pnpm test src/gateway/server.sessions.reset-hooks.test.ts src/gateway/server.sessions.delete-lifecycle.test.ts src/cli/gateway-cli/run-loop.test.ts -- all clawsweeper-listed acceptance suites green.
• pnpm exec oxfmt --check --threads=1 clean on every touched file.

Real behavior proof

Behavior addressed: session_end plugin hooks (claude-mem and the rest of the documented public session_end contract) firing for every session that was active when the gateway process is stopped or restarted, with reason "shutdown" or "restart", and never double-firing for a session that was already finalized through replace / reset / delete / compaction. Issue reporter on #57790 cited 11 orphaned sessions causing 63 timeout errors in a single day from agent pool exhaustion when claude-mem never received the matching session_end.

Real environment tested: local Linux 6.17 (Node 22.22.2). Live Node process with the real production helpers from src/gateway/session-reset-service.ts -- emitGatewaySessionStartPluginHook, emitGatewaySessionEndPluginHook, and the new drainActiveSessionsForShutdown. The plugin host-hook runner is installed via the documented Symbol.for("openclaw.plugins.hook-runner-global-state") singleton (the same hook the bundled plugin loader uses at gateway startup); the test runner is a tiny in-process listener that records every session_end event the gateway actually emits. No vitest mocks, no fake timers.

Exact steps or command run after this patch:

node --import tsx /tmp/proof-57790.mts

Where /tmp/proof-57790.mts is a small driver that installs a claude-mem-shaped listener on the global hook-runner singleton, calls emitGatewaySessionStartPluginHook for three real sessions (Telegram / Discord / Slack-style), closes one of them normally via emitGatewaySessionEndPluginHook(reason: "reset"), then triggers drainActiveSessionsForShutdown({ reason: "shutdown" }) to simulate the SIGTERM path.

Evidence after fix: terminal output captured directly from the live Node process. Each session_end line is the event payload the listener received from the production emit helpers (not a mock).

--- simulating claude-mem-style plugin attached to session_end ---
noted 3 active sessions: sess-A-001, sess-B-002, sess-C-003

--- one session is closed normally via reset before shutdown ---
captured 1 session_end event(s) so far
  sessionId=sess-B-002 reason=reset

--- gateway receives SIGTERM, shutdown finalizer runs ---
drain returned: {"emittedSessionIds":["sess-A-001","sess-C-003"],"timedOut":false} elapsedMs=1

--- session_end events received by plugin during full lifecycle ---
  [0] sessionId=sess-B-002 sessionKey=agent:main:discord:efgh reason=reset
  [1] sessionId=sess-A-001 sessionKey=agent:main:telegram:abcd reason=shutdown
  [2] sessionId=sess-C-003 sessionKey=agent:main:slack:ijkl reason=shutdown

--- replaying drain proves the tracker is now empty (no double-fire) ---
second drain: emitted=0 timedOut=false captured=0

Observed result after fix:

• All three sessions that received session_start now also receive a matching session_end: sess-B-002 with reason reset (normal close), sess-A-001 and sess-C-003 with reason shutdown (shutdown finalizer). Before this PR the shutdown path emitted nothing, so sess-A and sess-C would have stayed in active state until claude-mem (or the operator's band-aid cron) noticed the ghost rows.
• sess-B-002 is not re-emitted with reason shutdown even though it received session_start. The tracker forgot it the moment its normal session_end fired, so the shutdown drain has nothing left to do for it. This is exactly the "must avoid double-firing for sessions already finalized by reset, delete, compaction, or replacement" constraint clawsweeper listed.
• The drain completed in 1 ms wall time, well under the 2 s bounded budget; even with three sessions the finalizer never approaches the SIGTERM shutdown deadline.
• Replaying the drain immediately afterwards is a clean no-op: emitted=0, captured=0. The tracker is empty, so a second SIGTERM cycle on the same gateway would not double-fire either.

What was not tested: an end-to-end SIGTERM against a fully booted openclaw gateway process driving a real claude-mem plugin install -- the runtime proof above exercises the production emit helpers, the production global hook-runner singleton, and the new bounded drain, but uses an in-process listener instead of a separate plugin process. The unit suite (active-sessions-shutdown-tracker.test.ts, drain-active-sessions-for-shutdown.test.ts, server-close.test.ts) covers the close-handler wiring, the per-reason fan-out, and the timeout-warning path; the existing server.sessions.reset-hooks.test.ts and server.sessions.delete-lifecycle.test.ts continue to pass and prove the normal lifecycle still emits session_end correctly so the tracker's forget semantics stay correct.