feat: one-shot delayed triggers — /at command and run_once cron flag

[nathanschram]

Context

Untether's trigger system currently only supports recurring crons. There's no way to schedule a one-shot delayed run — e.g. "run this prompt in 30 minutes, once." This is a common need when dogfooding from mobile (e.g. "remind me to check the build in 20 minutes").

Claude Code has a ScheduleWakeup tool that lets the agent schedule itself to wake up after a delay (60-3600s), but this only works in Claude Code's local /loop mode — it doesn't work through Untether.

Proposal

Two complementary features:

1. /at command — on-demand delayed runs (~4-6 hours)

Interactive Telegram command for scheduling a one-shot delayed agent run:

/at 30m Check the build status
/at 2h Review the PR comments
/at 90s Run the test suite

Implementation:

• Parse delay from command arguments (supports Ns, Nm, Nh suffixes)
• Create an anyio task with anyio.sleep(delay) then run_job()
• Store pending timers in memory (lost on restart — acceptable for one-shot delays)
• Optional: persist to a state file for restart survival
• Show confirmation: "⏳ Scheduled: will run in 30 minutes"
• On fire: send notification then start the run, same as cron dispatch
• Clean up after firing

Delay range: 60s to 24h (matching ScheduleWakeup's 60s minimum, extending the max for practical use)

2. run_once cron flag — config-driven one-shot (~2-3 hours)

Add run_once: bool = False to CronConfig for crons that should fire once then disable:

[[triggers.crons]]
id = "deploy-check"
schedule = "0 15 * * *"
prompt = "Check today's deployment status"
run_once = true

Implementation:

• Add run_once field to CronConfig in triggers/settings.py
• After firing, TriggerManager removes the cron from the active list
• Log the removal: triggers.cron.run_once_completed
• The cron stays in the TOML (not auto-deleted) but is skipped in-memory after firing
• On config reload (hot-reload or restart), the cron resets and can fire again

Use case: "Fire this at 3pm today, then never again until I re-enable it" — useful for scheduled one-off tasks.

Effort

Item	Estimate
/at command (parsing, timer, dispatch, cleanup)	~4-6 hours
run_once cron flag (settings, manager, scheduler)	~2-3 hours
Tests for both	~2-3 hours
Total	~8-12 hours

Related

• feat: hot-reload support for triggers, watchdog, and progress settings #269 — hot-reload trigger configuration (PR feat: hot-reload trigger config without restart #285)
• feat: full /loop support — agent self-pacing via ScheduleWakeup interception #289 — full /loop support (agent self-pacing, v0.36.0)
• Claude Code's ScheduleWakeup tool — one-shot delayed wakeup for /loop mode

[nathanschram]

Forward ref corrected: full /loop support is #289.

[nathanschram]

Implemented in v0.35.1rc4:

• /at <Ns|Nm|Nh> <prompt> schedules delayed run (60s-24h)
• run_once: bool = False on CronConfig — fires once then auto-disables
• /cancel drops pending timers; per-chat cap of 20
• Fixed CancelScope race where cancelled timers still fired

34 tests in test_at_command.py. See PR #292.

[nathanschram]

v0.35.1rc4 Implementation Status — Complete (both features)

Both the /at command and run_once cron flag are fully implemented in PR #292 and integration-tested on @untether_dev_bot.

/at command

New files:

• src/untether/telegram/at_scheduler.py — module-level scheduler state (_TASK_GROUP, _RUN_JOB, _TRANSPORT, _PENDING); install() called from run_main_loop; schedule_delayed_run(), cancel_pending_for_chat(), active_count(), pending_for_chat()
• src/untether/telegram/commands/at.py — AtCommand backend; parses ^\d+[smhSMH]\s+.+$; validates 60s–24h bounds; registered as entry-point at

Integration points:

• telegram/loop.py — at_scheduler.install(tg, run_job, transport, chat_id) after task group opens
• telegram/commands/cancel.py — calls at_scheduler.cancel_pending_for_chat() before "nothing running" fallback
• telegram/loop.py:_drain_and_exit() — logs pending_at=at_scheduler.active_count() in drain; pending scopes get cancelled when task group exits

Edge cases handled:

• Invalid format → usage hint reply
• Below minimum (59s) / above max (25h) → range error
• Per-chat cap of 20 pending delays → error
• /cancel drops all pending /at timers for the chat
• Restart → explicitly lost (no persistence, documented)

Bugfix found during integration testing:

• anyio.CancelScope.__exit__ swallows the Cancelled exception when the scope itself caused the cancellation. The fire/dispatch code outside the scope continued regardless, causing cancelled timers to still fire and dispatch runs. Fixed with cancelled_caught check after scope exit (commit 11963d3).

run_once cron flag

• CronConfig.run_once: bool = False added to triggers/settings.py
• After dispatcher.dispatch_cron(cron) in the scheduler tick, if cron.run_once is True, manager.remove_cron(cron.id) atomically replaces the cron list
• The cron stays in TOML; on config reload or restart, it re-enters the active list
• TriggerManager.remove_cron() uses the same atomic list replacement pattern as update() — safe in the single-event-loop model

Test coverage (34 tests)

• test_at_command.py:
  • Parse: 19 tests (valid durations, invalid durations, case-insensitive units)
  • _format_delay: 7 parametrised tests
  • Command handle: usage on empty, scheduler not installed, invalid format, successful schedule
  • Scheduler: reject below min, reject above max, per-chat cap, cancel drops pending, uninstall clears
• test_trigger_settings.py: run_once default False, run_once True accepted
• test_trigger_cron.py: run_once removes after fire, run_once_false keeps cron, reload re-adds removed cron
• test_trigger_manager.py: remove_cron returns True/False, atomic during iteration, reload rehydrates

[nathanschram]

Integration Test Results — v0.35.1rc4

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

/at command (AT1–AT3) ✅

Test	Result	Details
AT1: Schedule + fire	✅ PASS	/at 60s say hello → "⏳ Scheduled: will run in 1m" appeared immediately; after 61s "⏰ Running scheduled prompt (60s after /at)" appeared, engine ran and completed with response
AT2: Schedule + cancel	✅ PASS	Scheduled a 5m delay then /cancel → "❌ cancelled 2 pending /at runs" (2 because AT1 was also pending)
AT3: Multiple + cancel	✅ PASS	Scheduled 3x /at (60s, 2m, 3m) then /cancel → "❌ cancelled 3 pending /at runs" — all cancelled cleanly
AT4: Per-chat cap	⏭️ SKIP	Unit tests cover the cap=20 logic; skipped to avoid scheduling 21 delays in live testing

/at edge cases (Q10–Q12) ✅

Test	Result	Details
Q10: /at no args	✅ PASS	Shows usage text with duration format and examples
Q11: /at 30x hello	✅ PASS	"❌ couldn't parse /at" + usage text
Q12: /at 10s hello	✅ PASS	Rejected (below 60s minimum) with parse error + usage

run_once cron flag (RO1–RO2) ✅

Test	Result	Details
RO1: Fire once	✅ PASS	* * * * * cron with run_once = true fired exactly once on startup; logs show triggers.cron.firing → triggers.cron.run_once_completed with remaining_crons=0; no second fire on next minute
RO2: Reload re-enables	✅ PASS	After RO1, touched TOML to trigger hot-reload → triggers.manager.updated with crons_added=['rc4-test-cron']; cron fired again on next minute, then auto-disabled again

CancelScope race fix (commit 11963d3) ✅

Verified by AT2 — cancelled /at timers do not fire after /cancel. The cancelled_caught check after scope exit prevents the race condition.

Drain integration ✅

GR3 test: scheduled /at 5m test then restarted service → logs show shutdown.draining active_runs=0 pending_at=1 → at.cancelled chat_id=8351408485 — pending /at delays are properly drained on shutdown.

Verdict: All /at and run_once functionality works correctly in live Telegram. Ready for staging.

[nathanschram]

Fully implemented in v0.35.1rc4 (commit 678c3c4, fix 11963d3):

/at command:

• /at 30m <prompt> schedules one-shot delayed runs (60s–24h range)
• /cancel drops pending delays before firing
• Per-chat cap of 20 pending delays
• telegram/at_scheduler.py holds task-group + run_job refs
• CancelScope race fix in 11963d3 prevents timers firing after /cancel
• 34 unit tests in test_at_command.py

run_once cron flag:

• [[triggers.crons]] entries can set run_once = true to fire once then auto-disable
• Cron stays in TOML and re-activates on config reload or restart
• Covered in test_trigger_settings.py

Closing as completed.