Wake on Done

Core principle

A background process (&, nohup, a background shell) never wakes you when it exits. Wrap it with notify-run: when the command exits (success, failure or interrupt) it POSTs a notice to a relay bot's webhook, and the relay wakes the bot whose id is in owner. You keep working instead of polling.

Workflow

Long task = you start it, it runs in the background on the box or a user computer, takes minutes or more, and you need its result. Seconds-long commands, never-ending servers, and tasks waiting on a human don't count.

1. Write down what "done" means.
2. Start it on the machine where the work runs, detached, with YOUR OWN bot id. Always use exactly this shape (nohup + & + redirects); a plain & is killed when your remote shell command returns, taking notify-run with it, so no notice ever arrives. (On the Linux box, nohup is enough; on a Mac use the tmux form below.) nohup ~/.local/bin/notify-run --owner <your bot id> --task <short-name> [--log <path>] -- <command> <args...> </dev/null >/dev/null 2>&1 & On a Mac (machine Shell), nohup is NOT enough: the remote shell kills the whole job when it returns (verified 2026-10-11). Use tmux there (/opt/homebrew/bin/tmux; if missing, brew install tmux): tmux new-session -d -s <short-name> "~/.local/bin/notify-run --owner <your bot id> --task <short-name> --log <path> -- <command> <args...> </dev/null" Check the command's flags first (e.g. codex exec --help): an unknown flag makes it exit at once; you'll still be woken, with the error in output_tail.
3. Keep working; don't poll. When woken, check exit_code, output_tail, the log at log_path and the artifacts against "done". A failure is evidence too.