Summary

Fixes #20893

When config.patch or config.apply writes a config file, two independent restart paths race:

1. Config file watcher (chokidar, ~300ms debounce) detects the change and either hot-reloads channels or requests a full restart
2. WS handler schedules a SIGUSR1 restart (~2s delay via scheduleGatewaySigusr1Restart)

For channel-only changes (e.g. channels.telegram), the watcher hot-reloads the channel (stop + start), then the scheduled SIGUSR1 fires anyway, causing a full gateway restart that starts channels again — resulting in duplicate polling loops and permanent 409 Conflict errors from Telegram's getUpdates API.

Root Cause

[reload] config change detected; evaluating reload (...channels.telegram...)
[gateway/channels] restarting telegram channel    ← hot-reload starts new instances
[gateway] signal SIGUSR1 received                 ← scheduled restart starts them AGAIN

The config watcher and the explicit scheduleGatewaySigusr1Restart from the WS handler operate independently with no coordination, so both fire for the same config write.

Fix

Two complementary guards:

1. Cycle token snapshot — scheduleGatewaySigusr1Restart now snapshots restartCycleToken at schedule time. When the timer fires, it checks if a restart was already consumed (e.g. by the config watcher) and skips the emit if so.

2. Hot-reload cancellation — After the config watcher successfully applies a hot-reload, it calls cancelScheduledGatewaySigusr1Restart() to cancel the pending scheduled restart entirely.

Changes

• src/infra/restart.ts: Track scheduled restart timer; add cancelScheduledGatewaySigusr1Restart(); snapshot cycle token to skip stale restarts
• src/gateway/config-reload.ts: Cancel scheduled restart after successful hot-reload
• src/infra/infra-runtime.test.ts: 3 regression tests (cancel works, no-op cancel, config-watcher-fires-first race)

Test Results

All 386 gateway tests pass. All 18 restart tests pass (including 3 new regression tests).

Greptile Summary

Fixes race condition where config file changes trigger both hot-reload (via chokidar watcher) and scheduled SIGUSR1 restart (via WS handler), causing duplicate channel starts and 409 Conflict errors from Telegram.

The fix implements two complementary guards:

• Cycle token snapshot: scheduleGatewaySigusr1Restart now captures restartCycleToken at schedule time and skips the restart if consumedRestartToken has advanced (indicating another restart already fired)
• Explicit cancellation: Config watcher calls cancelScheduledGatewaySigusr1Restart() after successful hot-reload to preemptively cancel the pending timer

Changes are well-tested with 3 new regression tests covering cancellation, no-op cancellation, and the config-watcher-fires-first race. The logic correctly handles edge cases including previous restart cycles and multiple schedule attempts.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The fix implements a robust two-pronged solution to a well-documented race condition. The cycle token snapshot logic correctly handles all edge cases (previous restarts, multiple schedules, race scenarios). The explicit cancellation provides defense-in-depth. All 3 new regression tests pass alongside 383 existing gateway tests. The changes are minimal, focused, and preserve backward compatibility.
• No files require special attention

_{Last reviewed commit: 95e492e}