feat: hot-reload trigger config without restart

[Nathan Schram (nathanschram)]

Summary

Implements hot-reload for trigger configuration (crons and webhooks) so that editing untether.toml applies changes immediately without restarting Untether or killing active runs. Closes #269.

• New TriggerManager class (triggers/manager.py) — mutable holder that both the cron scheduler and webhook server reference at runtime
• Cron scheduler reads manager.crons each tick — new crons fire immediately, removed crons stop matching, last_fired dict preserved to prevent double-firing
• Webhook server uses manager.webhook_for_path() per request — new webhooks accessible immediately, removed webhooks return 404, auth/secret changes take effect on next request
• Config watcher (handle_reload()) re-reads raw TOML [triggers] section and calls manager.update() on every config file change

What's now live-reloadable (no restart needed)

Setting	Mechanism
Cron schedules (add/remove/modify)	TriggerManager — scheduler reads each tick
Webhook routes (add/remove/modify)	TriggerManager — per-request lookup
Webhook auth/secrets	TriggerManager — per-request lookup
Webhook actions (agent_run, file_write, etc.)	TriggerManager — per-request lookup
Multipart/file upload settings	TriggerManager — per-request lookup
Cron fetch config	TriggerManager — read at fire time
Cron timezone (per-cron and default)	TriggerManager — read each tick
Projects config / chat routing	Already reloadable via TransportRuntime
Engine defaults	Already reloadable via TransportRuntime
Watchdog, preamble, footer, cost settings	Already per-run via load_settings_if_exists()
Command menu, topic scope	Already refreshed in handle_reload()

What still requires a restart

Setting	Why
Bot token / chat ID	Baked into Telegram client at startup
Webhook server host/port	aiohttp binds once; changing port needs new listener
Transport type	Architectural — entire transport stack
triggers.enabled toggle (off→on)	Webhook server and cron scheduler must be started
session_mode (stateless↔chat)	Requires state store initialisation
topics.enabled toggle	Requires topic state store initialisation
New engine binaries	Resolved via shutil.which() at startup
allowed_user_ids / chat_ids	Frozen in TelegramBridgeConfig (future work)
Voice transcription settings	Frozen in TelegramBridgeConfig (future work)
Files settings	Frozen in TelegramBridgeConfig (future work)

Future work: unfreezing TelegramBridgeConfig

The TelegramBridgeConfig dataclass is frozen=True, which blocks hot-reload for voice, files, chat_ids, and timing settings. These fields are already read per-message (correct pattern), so unfreezing the config or introducing a config wrapper would make them reloadable with minimal logic changes. Tracked separately from this PR.

Design decisions

• Backwards-compatible: build_webhook_app() accepts manager=None (default), so all existing tests pass without changes
• In-flight safety: TriggerManager.update() creates new list/dict objects, so iterations over the old cron list are unaffected (Python's for loop grabs the iterator at the start)
• Webhook server always starts when triggers are enabled — even with no initial webhooks — so new webhooks added via reload are immediately accessible
• Cron scheduler always starts when triggers are enabled — idles when cron list is empty, picks up new crons on next tick

Test plan

• 13 new tests in test_trigger_manager.py:
  • Manager init, update, clear, timezone, in-flight iteration safety
  • Webhook server: add/remove/update routes, secret changes, health count
  • Cron schedule swapping, timezone updates
• All 2038 existing tests pass (81.55% coverage)
• Lint and format clean (ruff check, ruff format --check)
• Integration test via @untether_dev_bot: edit TOML, add cron, verify fires without restart
• Integration test: add webhook route, verify accessible without restart

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1e6bdba8-4113-4281-aed2-0c96a95c9437

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/trigger-hot-reload

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Nathan Schram (nathanschram)]

v0.35.1rc4 Status — Merged + Extended

Squash-merged to dev as commit 74ea778 on 2026-04-14. Closes #269.

PR #292 (rc4 feature branch) extends the TriggerManager with additional helpers:

• cron_ids(), webhook_ids() — snapshot lists
• crons_for_chat(), webhooks_for_chat() — per-chat reverse lookup (used by feat: trigger visibility — indicators, discovery, and run history #271 /ping indicator)
• remove_cron() — atomic removal for feat: one-shot delayed triggers — /at command and run_once cron flag #288 run_once flag
• 10 new tests added to test_trigger_manager.py (total: 23)

All original PR #285 functionality preserved. See #269 comment for the full hot-reload scope including #286 (unfrozen bridge config).