feat: trigger visibility — indicators, discovery, and run history

[nathanschram]

Summary

The trigger system (crons + webhooks) is currently configured but largely invisible to users in the Telegram UI. Once set up in untether.toml, there's no easy way to discover what triggers exist, which chats they target, when they last fired, or whether a run was trigger-initiated.

This issue tracks improvements to surface trigger presence, activity, and management across the Untether UI.

Current state

Area	What exists today	Gap
Startup message	Global count: "triggers: enabled (N webhooks, M crons)"	Not per-chat; doesn't say which chats have triggers
Per-chat indicator	Nothing	No visual cue that a chat has active triggers
Trigger dispatch	⚡ Trigger: webhook:id / 🕐 Scheduled: cron:id notification	Silent (notify=False), no schedule/context info
Run footer	Shows model/effort/permission	Identical for trigger-initiated and manual runs
/config menu	Trigger mode page (all/mentions)	No view of configured cron/webhook triggers
/trigger command	Sets trigger mode (all/mentions)	Doesn't list or describe configured triggers
Run history	last_fired dict — in-memory, per-cron, lost on restart	No persistent history, no UI display
Cron schedule display	Raw 5-field expression stored	No human-friendly rendering
Stats	Per-engine run counts	No trigger vs manual breakdown

Proposed improvements

Tier 1 — Quick wins (v0.35.2)

1a. Per-chat trigger indicator in startup/greeting
When the bot starts (or on /ping), if the current chat has triggers configured, append a line:

⏰ triggers: 1 cron (daily-review, 8am Mon–Fri Melbourne)

Requires a reverse lookup: iterate trigger_settings.crons + .webhooks, match chat_id → current chat. Lightweight, no persistence needed.

1b. Trigger-initiated run footer
When a run was started by a trigger, add to the meta line:

🏷 sonnet · plan · ⏰ cron:daily-review

or

🏷 sonnet · plan · ⚡ webhook:github-push

Pass trigger source through RunOptions or ProgressTracker.meta so format_meta_line() can render it.

1c. Human-friendly cron description
Add a describe_cron(schedule, timezone) utility that converts 0 8 * * 1-5 + Australia/Melbourne → "8:00 AM Mon–Fri (Melbourne)". Used in startup indicator, /config page, and dispatch notifications. Keep it simple — cover common patterns, fall back to raw expression for complex ones.

Tier 2 — Discovery (v0.35.2–0.35.3)

2a. /config → Triggers sub-page
Add a triggers info page to the /config menu showing:

• Active crons: id, schedule (human-friendly), timezone, project, engine
• Active webhooks: id, path, auth type, project, engine
• Per-chat filtering: only show triggers targeting this chat (or all if in default chat)

Read-only view — editing stays in untether.toml. This gives users a way to see what's configured without SSH.

2b. Enhanced dispatch notification
Improve the cron/webhook notification messages:

⏰ Scheduled: cron:daily-review
📅 8:00 AM Mon–Fri (Melbourne) · project: myapp

Add schedule context and project info. Still silent (notify=False), but more informative when scrolling history.

Tier 3 — History & stats (v0.35.3+)

3a. Persistent trigger run history
Track last_fired_at (UTC timestamp) per trigger in a JSON state file (similar to chat_prefs pattern). Show in /config triggers page:

⏰ daily-review — 8:00 AM Mon–Fri (Melbourne)
   Last run: today 8:00 AM · next: tomorrow 8:00 AM

3b. Trigger activity in /stats
Add trigger-initiated run counts alongside engine counts:

Runs today: 5 (3 manual, 2 triggered)
  cron:daily-review — 1 run
  webhook:github-push — 1 run

Extend DayBucket in session_stats.py with an optional source field.

3c. Trigger run notifications
Optional: when a trigger fires and completes, send a brief completion notification (configurable). Useful for webhook-triggered runs that complete while the user isn't watching.

Key files

File	Relevance
src/untether/telegram/loop.py:143-157	Startup message construction
src/untether/markdown.py:312-394	Footer/meta line formatting
src/untether/triggers/dispatcher.py:30-86	Trigger dispatch notifications
src/untether/triggers/cron.py	Cron scheduler + matching
src/untether/triggers/settings.py	CronConfig/WebhookConfig models
src/untether/telegram/commands/config.py:924-988	/config trigger mode page
src/untether/telegram/commands/trigger.py	/trigger command (mode only)
src/untether/session_stats.py	Run stats tracking
src/untether/telegram/chat_prefs.py	Per-chat state storage

Design notes

• No new dependencies — human-friendly cron description is a simple pattern-matching function
• Read-only UI — trigger config stays in untether.toml; Telegram shows info, doesn't edit
• Backward compatible — all new UI elements are additive; no existing behaviour changes
• Per-chat awareness requires iterating trigger configs to find matching chat_id — cheap at startup, could be cached in TransportRuntime

[nathanschram]

Tier 1 implemented in v0.35.1rc4:

• /ping shows per-chat trigger indicator: ⏰ triggers: 1 cron (daily-review, 9:00 AM daily (Melbourne))
• Trigger-initiated runs show provenance in footer: ⏰ cron:<id>
• describe_cron() utility for human-friendly rendering
• RunContext.trigger_source flows through dispatcher → runner_bridge → footer

Tiers 2-3 deferred to v0.35.2+. See PR #292.

[nathanschram]

v0.35.1rc4 Implementation Status — Tier 1 Complete

Tier 1 (quick wins) is fully implemented in PR #292 and integration-tested on @untether_dev_bot.

What shipped

1a. Per-chat trigger indicator in /ping

• /ping now appends ⏰ triggers: 1 cron (daily-review, 9:00 AM daily (Melbourne)) when the current chat has active triggers
• Multiple triggers show counts: ⏰ triggers: 2 crons, 1 webhook
• Triggers without chat_id fall back to the transport's default chat_id
• TriggerManager exposes crons_for_chat() and webhooks_for_chat() helpers for the reverse lookup
• CommandContext gains trigger_manager and default_chat_id fields (defaults None) so commands can access trigger info without coupling to transport internals

1b. Trigger-initiated run footer

• RunContext gains trigger_source: str | None = None field
• triggers/dispatcher.py sets it to cron:<id> or webhook:<id> on every dispatch
• runner_bridge.handle_message seeds progress_tracker.meta["trigger"] with icon + source
• ProgressTracker.note_event now merges engine meta over dispatcher-seeded meta (was: replace) so the trigger key survives the engine's StartedEvent
• format_meta_line() appends the trigger to the footer parts: 🏷 opus 4.6 · plan · ⏰ cron:daily-review

1c. Human-friendly cron description

• New triggers/describe.py with describe_cron(schedule, timezone) utility
• Covers common daily/weekly patterns; falls back to raw for complex (stepped, specific DOM/month)
• Examples: 0 8 * * 1-5 + Australia/Melbourne → 8:00 AM Mon–Fri (Melbourne)

Files changed

• src/untether/context.py — RunContext.trigger_source field
• src/untether/triggers/describe.py — new describe_cron() utility
• src/untether/triggers/dispatcher.py — set context.trigger_source
• src/untether/triggers/manager.py — crons_for_chat(), webhooks_for_chat(), cron_ids(), webhook_ids() helpers
• src/untether/runner_bridge.py — seed progress_tracker.meta["trigger"]
• src/untether/progress.py — merge (not replace) meta in note_event
• src/untether/markdown.py — format_meta_line() includes trigger
• src/untether/commands.py — CommandContext.trigger_manager, default_chat_id
• src/untether/telegram/commands/dispatch.py — pass trigger_manager + default_chat_id to CommandContext
• src/untether/telegram/commands/ping.py — _trigger_indicator() + updated handle()

Test coverage

• test_describe_cron.py — 31 tests (daily, weekday ranges/lists, single day, timezone, fallback, boundaries)
• test_trigger_meta_line.py — 6 tests (trigger in footer ordering, empty/non-string ignored)
• test_ping_command.py — 7 new tests (single cron, multi-cron count, webhook, other chat, default fallback)
• test_trigger_manager.py — 10 new tests (crons_for_chat, webhooks_for_chat, cron_ids, webhook_ids, remove_cron)
• test_trigger_dispatcher.py — 2 new tests (trigger_source forwarded for webhook and cron)

Remaining (Tiers 2-3, deferred to v0.35.2+)

• 2a /config → Triggers sub-page showing cron/webhook details
• 2b Enhanced dispatch notification with schedule context
• 3a Persistent trigger run history (last_fired_at)
• 3b Trigger activity in /stats
• 3c Trigger completion notifications

[nathanschram]

Integration Test Results — v0.35.1rc4

Tested: 2026-04-14 against @untether_dev_bot (local editable source)
Branch: feature/v0.35.1rc4

Trigger visibility (TV1–TV4) ✅

Test	Result	Details
TV1: /ping with triggers	✅ PASS	/ping in Claude chat (which has cron + webhook targeting it) → response includes ⏰ triggers: 1 cron (rc4-test-cron, * * * * *), 1 webhook line below the pong
TV2: /ping without triggers	✅ PASS	/ping in Codex chat (no triggers targeting it) → just "🏓 pong — up 6m 25s" with no trigger line
TV3: Trigger footer on cron run	✅ PASS	run_once cron fired → completion message footer shows 🏷 codex-mini-latest · ⏰ cron:rc4-test-cron
TV4: Trigger footer on webhook run	✅ PASS	Webhook test-wh2 fired via curl → completion message footer shows ⚡ webhook:test-wh2

Verified capabilities

• /ping trigger summary: describe_cron() utility renders the schedule correctly; webhook count shown without details
• Per-chat filtering: Only shows triggers that target the specific chat — no false positives in other engine chats
• Cron footer: ⏰ cron:<id> appears alongside model name in format_meta_line()
• Webhook footer: ⚡ webhook:<id> appears alongside model name in format_meta_line()
• RunContext.trigger_source: Dispatchers correctly set trigger source, which flows through to ProgressTracker.meta["trigger"] and renders in the footer

Verdict: All trigger visibility indicators work correctly. Users can discover triggers via /ping and identify trigger-initiated runs via the footer. Ready for staging.