feat: increase default approvals.gateway_timeout from 300s to 1800s

[kiwipaulrob]

Summary

The default approval timeout for gateway/messaging platforms (approvals.gateway_timeout) is 300 seconds (5 minutes), which is too short for email round-trips. This PR changes the default to 1800 seconds (30 minutes), matching agent.gateway_timeout, and adds the option to the documented DEFAULT_CONFIG.

Background

approvals.gateway_timeout controls how long the agent thread waits for a user to respond with /approve or /deny on messaging and email platforms. Its current effective default is 300 seconds, falling back from two places:

1. tools/approval.py line 1289: _get_approval_config().get("gateway_timeout", 300)
2. tools/approval.py line 1296: except (ValueError, TypeError): timeout = 300 (defensive fallback)

Why 300s is wrong for email

The 300s value works fine for instant messaging (Telegram, Discord, Slack) where users typically respond in seconds. But email is fundamentally different — it is an asynchronous, intermittent communication channel. Users check email on their own schedule, not on the agent's timer. A typical email round-trip (Hermes sends email → user reads it at their next check → user composes /approve reply → Hermes polls IMAP → receives it) routinely takes 5–30 minutes.

The normal-reply trap (Issue #27352)

Sending a normal chat message while Hermes is waiting for approval does NOT resolve the pending event or extend the timeout. Only explicit /approve or /deny commands release the pending approval. Raising the default to 1800s provides breathing room.

Changes

1. hermes_cli/config.py — Add gateway_timeout to DEFAULT_CONFIG

Adds "gateway_timeout": 1800 with a comment referencing Issue #27352.

2. tools/approval.py — Raise the fallback default from 300 to 1800

Two fallback defaults: 300 → 1800, update comment from "5 min" to "30 min".

3. gateway/run.py — Update dormant constant to match

_APPROVAL_TIMEOUT_SECONDS = 300 → 1800

4. website/docs/user-guide/configuration.md — Document the option

Adds gateway_timeout documentation with email-specific guidance.

Related Issues

• [Bug] Gateway approval wait is not resolved by normal user replies during pending approval #27352 — Normal reply doesn't clear pending approval (OPEN)
• gateway agent timeout (HERMES_AGENT_TIMEOUT) kills legitimate long-running tasks #4815 — Gateway agent timeout kills long-running tasks (CLOSED)
• Hardcoded platform timeouts break local model workflows — need unified timeout configuration #21525 — Hardcoded platform timeouts break email workflows (OPEN)
• Discord approval button timeout ignores approvals.gateway_timeout config #30371 — Discord approval button ignores gateway_timeout (OPEN)
• feat: make dangerous command approval timeout configurable #3765 / PR feat(approvals): make dangerous command approval timeout configurable #3886 — Configurable approval timeout pattern (CLOSED)

[teknium1]

Thanks for identifying the email approval-wait problem. The current implementation needs a re-scope before it can be salvaged.

Problems

• Current main deliberately uses one canonical setting: tools/approval.py:2501 calls _get_approval_timeout(), which reads approvals.timeout with a 60-second fallback at tools/approval.py:1879-1884.
• Commit c5e841ab0e301f9ab0bf00ebd430159441f828d7 removed the gateway-specific lookup. Its regression test explicitly requires gateway waits to use approvals.timeout “without a second timeout knob” (tests/gateway/test_approve_deny_commands.py:518-527). Restoring approvals.gateway_timeout would reverse that current contract.
• The changed gateway/run.py constant is not in the active wait path; tools/approval.py:2444-2540 owns the gateway approval wait.

Suggested changes

• Please re-scope around the canonical approvals.timeout setting if a longer default is still desired, and account for all approval surfaces affected by that shared setting.
• Add regression coverage for the selected canonical default and update both approval documentation sections.

This is an automated hermes-sweeper review.

[kiwipaulrob]

Thanks for the review. The history in commit c5e841ab is clear — I'll re-scope this to just increase the default approvals.timeout from 60s to 300s rather than re-introducing a separate approvals.gateway_timeout knob. This way all approval surfaces (CLI, gateway, email) get the longer wait uniformly. I will update the PR with the simpler approach and add regression coverage for the new default.

[kiwipaulrob]

Re-scoped as promised:

• Dropped the separate approvals.gateway_timeout config key entirely
• Just increased the canonical approvals.timeout default from 60s → 300s
• Clean single-commit branch from current upstream/main (no unrelated diffs)

This gives all approval surfaces (CLI, gateway, email) the longer wait uniformly with a single +1/-1 change.

[teknium1]

Thank you @kiwipaulrob — you proposed this exact change (approvals.timeout default 60 → 300) back in June, well before it landed. The 60-second window was genuinely too tight for messaging platforms where approval prompts arrive as push notifications.

This was resolved on main today in #68597 with the same 300s default, along with aligned fallback sites (tools/approval.py, cli.py, hermes_cli/callbacks.py), docs updates (en+zh), and related fixes for stale approval taps rendering false "Approved" confirmations. Our duplicate sweep failed to surface your PR before we built the fix — apologies for that; you were first by over a month.

Closing as resolved-on-main. Appreciated!