feat: hot-reload support for triggers, watchdog, and progress settings

[nathanschram]

Summary

Explore which parts of Untether can be dynamically updated via config reload (watch_config) without requiring a full bot restart. Currently, editing untether.toml and restarting the service is the only way to apply changes to several subsystems that could reasonably support hot-reload.

Motivation

Adding a new cron trigger, adjusting watchdog timeouts, or tweaking progress settings currently requires systemctl --user restart untether-dev — which kills all active runs. For a Telegram-first workflow, being able to edit config and have it apply live is a significant UX improvement.

Current state

Already hot-reloadable (no work needed)

• Projects config — chat-to-project mappings update on config change
• Per-chat preferences — engine, plan mode, verbose, etc. (JSON state files, reloaded on-demand)
• Preamble — re-read from TOML on every run via _load_preamble_settings()
• Per-chat/topic engine overrides — model, reasoning (persistent JSON, on-demand reload)
• Command menu — handle_reload() already calls refresh_commands() + set_command_menu()

Needs work

Area	Current behaviour	What hot-reload would look like	Effort
Triggers (cron + webhooks)	Parsed once at startup in loop.py:1488-1525; run_cron_scheduler() loops forever with a fixed crons list	on_reload callback cancels old scheduler/webhook tasks, spins up new ones with fresh config; preserve last_fired state to avoid double-firing	Medium-hard
Watchdog settings	WatchdogSettings read at startup, baked into runner bridge	Read tool_timeout, mcp_tool_timeout from current settings per-run instead of caching	Easy
Progress settings	ProgressSettings (verbosity, max_actions, min_render_interval) read at startup	Fetch from runtime on each ProgressEdits construction or per-render cycle	Easy
Footer settings	FooterSettings read at startup	Fetch per-render from runtime	Easy
Cost/budget settings	CostSettings read at startup	Re-read thresholds per-run from runtime; active CostTracker picks up new limits	Easy-medium

Out of scope (entry-point limitation)

• Engine registration — Python entry points require package reinstall
• Command registration — same entry-point constraint
• These would need a fundamentally different plugin discovery mechanism

Implementation sketch

Triggers (the big one)

1. Wrap cron scheduler + webhook server tasks in a TriggerManager that holds CancelScope references
2. On on_reload, if trigger config changed: cancel old scopes, start new scheduler/server tasks
3. Carry forward last_fired dict to avoid re-firing within the same minute
4. For webhooks: graceful close of old HTTP listener before binding new one (or skip if routes unchanged)

Settings per-run

For watchdog, progress, footer, and cost settings:

1. Store the TransportRuntime reference (already available in runner bridge)
2. Read settings from runtime.settings at the point of use rather than caching at init
3. Minimal code change — mostly replacing self._timeout with self._runtime.settings.watchdog.tool_timeout

Acceptance criteria

• Editing [triggers] in untether.toml with watch_config = true applies new cron/webhook config without restart
• Editing [watchdog] timeouts applies to the next run without restart
• Editing [progress] settings applies to the next progress render without restart
• Editing [footer] settings applies to the next completed run without restart
• Editing [cost] budget thresholds applies to the next run without restart
• No double-firing of cron triggers during reload transition
• Existing active runs are not disrupted by config reload

Related

• config_watch.py — existing file watcher infrastructure
• handle_reload() in telegram/loop.py:1272 — existing reload callback (currently handles projects + command menu)
• watch_config: bool = False in settings.py:198 — opt-in flag

[nathanschram]

Implementation: PR #285

Hot-reload for triggers is implemented in #285 via a new TriggerManager class that the cron scheduler and webhook server reference at runtime. On config file change, handle_reload() re-parses the [triggers] TOML section and calls manager.update().

What's now live-reloadable (edit TOML → immediate effect)

• Cron schedules — add, remove, or modify crons; scheduler reads the list each tick
• Webhook routes — add, remove, or modify webhooks; per-request lookup
• Webhook auth/secrets — take effect on next request
• All v0.35.1 trigger features: non-agent actions (file_write, http_forward, notify_only), multipart settings, cron fetch config, timezone — all reload via TriggerManager
• Plus already-reloadable: projects, engine defaults, watchdog, preamble, footer, cost, command menu, topic scope

What still requires a restart

Architectural (no feasible fix):

• Bot token / chat ID — baked into Telegram client
• Webhook server host/port — aiohttp binds once
• Transport type — entire stack
• New engine binaries — resolved via shutil.which() at startup

Frozen TelegramBridgeConfig (future work):

• triggers.enabled off→on toggle — server/scheduler must be started
• session_mode / topics.enabled — require state store init
• allowed_user_ids / chat_ids — frozen dataclass
• Voice transcription settings — frozen dataclass (per-message read pattern already correct)
• Files settings — frozen dataclass (per-message read pattern already correct)
• Forward coalesce / media debounce timing — copied to state at startup

The frozen TelegramBridgeConfig items share a common fix: unfreezing the dataclass or introducing a config wrapper. These fields already read values per-message, so the logic pattern is correct — only the immutable container blocks updates. This is a separate piece of work.

Test coverage

13 new tests, all 2038 existing tests pass, 81.55% coverage. Integration testing pending.

[nathanschram]

Follow-up issue created: #286 — unfreeze TelegramBridgeConfig for hot-reload of voice, files, chat_ids, and timing settings (targeted for v0.36.0).

[nathanschram]

Merged to dev as squash commit 74ea778 (PR #285). rc4 extends TriggerManager with remove_cron(), crons_for_chat(), webhooks_for_chat(), cron_ids(), webhook_ids() helpers. Shipped in v0.35.1rc4 via PR #292.

[nathanschram]

v0.35.1rc4 Implementation Status — Complete

PR #285 squash-merged to dev as commit 74ea778. rc4 (PR #292) extends the TriggerManager with additional helpers consumed by #271 (trigger visibility) and #288 (run_once cron flag).

rc4 additions to TriggerManager

def cron_ids(self) -> list[str]
def webhook_ids(self) -> list[str]
def crons_for_chat(self, chat_id: int, default_chat_id: int | None = None) -> list[CronConfig]
def webhooks_for_chat(self, chat_id: int, default_chat_id: int | None = None) -> list[WebhookConfig]
def remove_cron(self, cron_id: str) -> bool  # atomic list replacement, used by run_once

All follow the same atomic-swap pattern as update() — safe in the single-event-loop model.

Integration with other rc4 features

• crons_for_chat() / webhooks_for_chat() → feat: trigger visibility — indicators, discovery, and run history #271 /ping per-chat trigger indicator
• remove_cron() → feat: one-shot delayed triggers — /at command and run_once cron flag #288 run_once auto-disable after fire
• cfg.trigger_manager field on TelegramBridgeConfig → feat: trigger visibility — indicators, discovery, and run history #271 command access via CommandContext

Test coverage

• 10 new tests in test_trigger_manager.py: TestTriggerManagerHelpers class covering cron_ids, webhook_ids, crons_for_chat (with/without default fallback, exclusion), webhooks_for_chat, remove_cron (found/missing/atomic iteration/reload rehydration)
• Total: 23 tests in test_trigger_manager.py (was 13)

Full hot-reload scope (original #269 + rc4 #286)

With #286 also landing in rc4, the combined hot-reload surface is now:

• ✅ Trigger crons/webhooks (via TriggerManager)
• ✅ Voice transcription settings (via update_from())
• ✅ File transfer settings
• ✅ allowed_user_ids (live reads in route_update())
• ✅ Message timing (forward_coalesce_s, media_group_debounce_s)
• ✅ show_resume_line

Restart-only: bot_token, chat_id, session_mode, topics, message_overflow, server host/port, triggers.enabled toggle.