PR #72306: fix(gateway): unref pricing refresh timer and abort fetches on stop

• Repository: openclaw/openclaw
• Author: bittoby
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/72306

Description (problem / solution / changelog)

Summary

• Problem: After openclaw gateway starts, the 24-hour pricing-refresh setTimeout and any in-flight LiteLLM/OpenRouter fetches keep the Node event loop alive. SIGINT/Ctrl+C cannot exit the process; users must kill from another terminal.
• Why it matters: Regression vs 2026.4.21. Reported on Windows 11 npm-global install (#72208). Affects every gateway run, not only pricing-fetch failures.
• What changed: .unref() the 24h refresh timer so it never blocks process exit; thread an AbortController through both pricing fetches and abort it from the stop() callback returned by startGatewayModelPricingRefresh.
• What did NOT change (scope boundary): No change to fetch URLs, timeout values, queueMicrotask deferral, cache TTL, schema, or HTTP server startup. Dashboard reachability during the initial fetch window is out of scope (already targeted by 966e814c5e).

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #72208
• Related #67605, #65365
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: scheduleRefresh() creates a setTimeout(..., 24h) whose handle holds a ref on the libuv loop. The pricing fetches in refreshGatewayModelPricingCache only honored AbortSignal.timeout(...); nothing connected them to gateway shutdown. When the user pressed Ctrl+C, the SIGINT handler ran but the loop stayed alive on the timer (and on any unsettled fetch socket).
• Missing detection / guardrail: No test asserted that timers/handles created by gateway runtime services are unref'd or torn down on stop().
• Contributing context (if known): The 24h refresh path was added with the tiered-pricing work in #67605. The async-bootstrap deferral in 966e814c5e made the timer reachable on every gateway start, exposing the unref gap.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/model-pricing-cache.test.ts
• Scenario the test should lock in:
  1. The 24h refresh timer is created with hasRef() === false.
  2. Calling the stop() from startGatewayModelPricingRefresh aborts every in-flight fetch's AbortSignal.
• Why this is the smallest reliable guardrail: Both failure modes are observable at the cache module's public surface without spinning a real gateway, so a unit test pins them deterministically and runs in milliseconds.
• Existing test that already covers this (if any): None — defers bootstrap refresh work until after the starter returns covers the prior queueMicrotask fix but not timer ref state or abort propagation.
• If no new test is added, why not: N/A — two tests added.

User-visible / Behavior Changes

• Ctrl+C now exits openclaw gateway cleanly even when the most recent pricing refresh has scheduled its next 24h tick or is still waiting on upstream. No config or default changes.

Diagram (if applicable)

Before:
SIGINT -> stop() -> clearRefreshTimer()
       -> in-flight fetch still pending (AbortSignal.timeout only)
       -> 24h setTimeout still ref'd
       -> event loop stays alive -> process hangs

After:
SIGINT -> stop() -> clearRefreshTimer() + abortInFlightRefresh()
       -> AbortSignal.any([timeout, cancel]) -> fetches reject AbortError
       -> any new 24h timer scheduled by the catch path is unref'd
       -> event loop drains -> process exits

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux 6.8 (issue reporter: Windows 11)
• Runtime/container: Node 22, pnpm
• Model/provider: any (reporter used openrouter/openrouter/free)
• Integration/channel (if any): gateway HTTP server only
• Relevant config (redacted): default agents.defaults.model

Steps

1. pnpm openclaw gateway with network conditions that delay/timeout openrouter.ai/api/v1/models and the LiteLLM raw-content URL.
2. Wait for the pricing fetches to complete or time out.
3. Press Ctrl+C.

Expected

• Process exits within a second of SIGINT.

Actual (before fix)

• Process stays alive; only kill -9 recovers it.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

pnpm test src/gateway/model-pricing-cache.test.ts — 13 passed (2 new). New tests:

• unrefs the 24-hour refresh timer so SIGINT exits cleanly
• aborts in-flight pricing fetches when stop is called

Human Verification (required)

• Verified scenarios:
  • Ran pnpm test src/gateway/model-pricing-cache.test.ts — all 13 cases green.
  • Inspected the abort path: AbortSignal.any([timeoutSignal, cancelSignal]) — aborting cancel synchronously flips the combined signal, which both fetch handlers observe.
  • Confirmed the new 24h timer scheduled by scheduleRefresh() is also unref'd, so a refresh that completes after stop() cannot resurrect a ref'd handle.
• Edge cases checked:
  • Concurrent callers of refreshGatewayModelPricingCache share the in-flight promise; the abort controller belongs to the original caller and is cleared in the finally.
  • __resetGatewayModelPricingCacheForTest aborts and clears, keeping suite isolation intact.
• What you did not verify:
  • Live Windows-11 npm-global reproduction (issue's host platform).
  • Dashboard reachability during the initial 30s fetch window — that symptom is the queueMicrotask deferral's responsibility (966e814c5e) and is unchanged here.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: After stop() aborts an in-flight refresh, the IIFE's catch handlers still reach scheduleRefresh(), scheduling a fresh 24h timer.
  • Mitigation: That timer is also unref'd via unrefRefreshTimer(), so it cannot keep the process alive. Tradeoff is a single redundant timer entry until GC; intentionally left in to keep the diff minimal.
• Risk: Test wraps globalThis.setTimeout to capture the 24h handle; a parallel test that also wraps it could collide.
  • Mitigation: Wrap is restored in a finally, and the suite is isolated under the gateway vitest project.

Changed files

• src/gateway/model-pricing-cache.test.ts (modified, +77/-0)
• src/gateway/model-pricing-cache.ts (modified, +37/-5)