cron-watchdog-authoring

Use the literal prefix "every 30m" or "every 2h", or a cron expression like "0 9 * * *". A bare "30m" creates a one-shot job with repeat=once, so always check the returned schedule and repeat fields and fix with cronjob(action=update).

Use no_agent=true with a script that prints to stdout only when it performs real action; empty stdout means a silent tick. Write diagnostics to a log file and exit 0 on transient failures like being offline, reserving non-zero exits for genuinely broken states.

A job can sit with next_run_at in the past and last_run_at null after creation or update. Treat the scheduler as a self-healing layer, not an execution guarantee: when the trigger condition is met, run the script manually in the foreground.

Use lsof -ti :<port> to find and SIGTERM only the process holding that specific port. Never use pkill -f on the binary name, since it matches scratch servers on other ports and can kill unrelated instances.

Scripts may run under macOS system Python 3.9, which does not support X | None type annotations at definition time. Add "from __future__ import annotations" as the first line or avoid union annotation syntax entirely.

Draft scripts often assume a config parent verb that does not exist; many tools expose verbs at root level. Run every command the script will execute, or its --help, against the real binary during foreground verification before scheduling.