fix(discord): scale slash sync timeout to actual write count (#16713)

[Tranquil-Flow]

What does this PR do?

_run_post_connect_initialization in gateway/platforms/discord.py wraps the entire _safe_sync_slash_commands call in asyncio.wait_for(..., 30). Discord's per-app command-management bucket allows roughly 5 writes / 20-second window, so a mass-prune-plus-upsert reconcile reliably blows the 30 s budget under back-pressure. The reported case had 77 orphans + 30 desired = 107 writes; two consecutive 30 s timeouts, then a clean 22 s sync only after the bucket fully recovered ~60 minutes later.

This PR splits the read-only diff from the writes and sizes the execute-phase timeout to the actual workload, so a heavy reconcile gets enough budget to finish under bucket pressure but pathological loads still get a hard cap.

Related Issue

Fixes #16713

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• gateway/platforms/discord.py — extracted two helpers from _safe_sync_slash_commands:
  • _plan_slash_command_sync() — read-only; diffs desired vs existing global commands, returns a list of typed actions (create / update / recreate) plus the orphan deletes and a write_count.
  • _execute_slash_command_sync(plan) — applies the plan, returns the existing summary dict.
  • _safe_sync_slash_commands is now a thin wrapper that calls plan + execute, preserving the single-shot signature for callers and existing tests.
• gateway/platforms/discord.py:_run_post_connect_initialization — now plans first under a 30 s budget, then computes a write-count-aware execute budget (30 + 5 × write_count, capped at 600 s) before running the plan. recreate actions count as two writes (delete + upsert) so the budget covers Discord's actual rate-limit math. Timeout log message updated to point at saturated rate-limit bucket as the cause instead of a flat "after 30 s".
• Three new module-level constants on the adapter (_SLASH_SYNC_BASE_BUDGET_SECONDS, _SLASH_SYNC_PER_WRITE_SECONDS, _SLASH_SYNC_MAX_BUDGET_SECONDS) and a static _estimate_slash_sync_budget(write_count) so the budget formula is testable and trivially tunable.
• tests/gateway/test_discord_connect.py — added five tests:
  • _estimate_slash_sync_budget scales with write count, is monotonic, caps at the maximum.
  • _plan_slash_command_sync counts a recreate as two writes plus an orphan delete (matches Discord's bucket math).
  • Plan + execute produces the same summary dict as the existing _safe_sync_slash_commands single-shot path (so callers/tests that read the summary stay correct).

How to Test

Reproduction (matches the issue body): trigger a session that produces ≥ ~30 orphan slash commands (e.g., a command-registry refactor that drops or renames commands), restart the gateway, and watch the post-connect initialization. Before this fix, wait_for(..., 30) raised asyncio.TimeoutError and subsequent reconnects within the rate-limit cooldown also timed out. After this fix, the budget scales with the planned write count and the reconcile completes under bucket pressure.

Automated:

pytest tests/gateway/test_discord_connect.py -q

Result on macOS 15.6.1 / Python 3.14.2: 16 passed (11 pre-existing + 5 new). All five new tests fail on main without the production change.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15.6.1 (Python 3.14.2)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A (new helpers carry inline docstrings explaining the bucket math)
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A (N/A — budget tuning lives on adapter class constants; not user-facing yaml)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A (N/A)
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A (N/A — pure asyncio + discord.py HTTP calls, no platform-specific syscalls)
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A (N/A — gateway adapter, not a tool)

Screenshots / Logs

$ pytest tests/gateway/test_discord_connect.py -q
................                                                         [100%]
16 passed, 3 warnings in 3.17s

[teknium1]

Thanks for the clean write-up and the bucket-math diagnosis — both were load-bearing for the fix.

Merged a simpler variant via #17029 / commit on main: same root cause (flat 30 s budget vs Discord's ~5-writes/20-s command-management bucket), but just widens the outer asyncio.wait_for to 600 s instead of introducing the plan/execute split and write-count-derived budget. The 600 s ceiling does the load-bearing work here; the adaptive formula in your PR extrapolates from the same bucket math, so in practice both fixes land in the same regime, and the flat ceiling keeps _safe_sync_slash_commands as a single unit.

Credit to @Tranquil-Flow and @davidbordenwi in the merge commit. Closing in favor of #17029.

[bgmbgm94]

Sharing a related data point from a Windows Discord gateway deployment.

We saw intermittent Discord send 429 pressure around long/chunked replies. A local mitigation that helped was pacing outbound Discord channel.send(...) calls with a small await asyncio.sleep(0.5) before chunk sends and before the plain-text fallback resend path.

This did not look related to a separate silent Process exited with code 0 investigation, but it did reduce burst pressure during Discord replies. If this area is revisited, a configurable Discord send throttle / adapter pacing helper might be worth considering alongside the write-count-aware slash-sync budgeting discussed here.