Add logging to crontab entries

<Purpose> Cron Manager provides complete lifecycle management for scheduled tasks through system crontab or node-cron. It handles creating, listing, modifying, and deleting cron jobs with natural language schedule parsing, cron expression generation, validation, and failure alerting. This is the single interface for all time-based automation in SuperClaw. </​Purpose>

<Use_When>

• User says "schedule", "every", "daily", "hourly", "cron", "recurring"
• User describes a time: "at 8am", "every Monday", "twice a day", "every 5 minutes"
• User wants to list, modify, or remove existing scheduled jobs
• User asks "what is scheduled?" or "show my cron jobs"
• Setting up recurring heartbeat, pipeline, or notification schedules
• User says "stop scheduling" or "remove the daily job" </​Use_When>

<Do_Not_Use_When>

• One-time immediate execution (just run the command directly)
• Complex multi-step pipeline scheduling (use ultrawork mode for multi-step orchestration)
• System-level crontab editing (use Bash with crontab directly if user specifically requests OS-level cron)
• The user wants a delay/​timer, not a recurring schedule ("wait 5 minutes" is not cron) </​Do_Not_Use_When>

<Why_This_Exists> Scheduling is fundamental to automation but cron expressions are notoriously hard to write correctly. Users think in natural language ("every weekday at 8am") but cron requires cryptic syntax ("0 8 * * 1-5"). Cron Manager bridges this gap by parsing natural language into validated cron expressions and managing them through system crontab. Without it, every scheduling task requires manual cron syntax lookup. </​Why_This_Exists>

<Execution_Policy>

• Always parse natural language schedules into cron expressions before registering
• Validate every cron expression before submitting to system crontab
• Show the user the interpreted schedule in human-readable form for confirmation
• List existing jobs before adding to avoid duplicates
• Use timezone-aware scheduling when the user specifies a timezone
• Default timezone is the system local timezone unless specified otherwise
• Note: cron jobs are managed via system crontab (use crontab -l to list, crontab -e to edit) </​Execution_Policy>

<Steps> 1. **Parse schedule intent**: Convert the user's natural language into a cron schedule. Common mappings:

1. Generate cron expression: Build the 5-field cron expression:

   ┌───────────── minute (0-59)
   │ ┌───────────── hour (0-23)
   │ │ ┌───────────── day of month (1-31)
   │ │ │ ┌───────────── month (1-12)
   │ │ │ │ ┌───────────── day of week (0-6, Sun=0)
   │ │ │ │ │
   * * * * *
   

   Special characters:

   • * -- any value
   • , -- value list separator (1,3,5)
   • - -- range (1-5)
   • / -- step values (*/​5 = every 5th)

2. Validate expression: Verify the expression is syntactically correct:

   • All 5 fields present
   • Values within valid ranges
   • No contradictory fields (e.g., day 31 with month 2)
   • Step values divide evenly into the range

3. Check for duplicates: List existing cron jobs via crontab -l and check if a job with a very similar schedule already exists. Warn the user if so.

4. Register via system crontab: Add the validated job to system crontab:

   # Edit crontab
   crontab -l > /​tmp/​crontab.txt
   echo "0 8 * * 1-5 /​path/​to/​command # job-name" >> /​tmp/​crontab.txt
   crontab /​tmp/​crontab.txt
   

5. Verify registration: Call crontab -l after adding to confirm the job appears in the crontab. If it does not appear, report the error.

6. Report to user: Show the user:

   • Job name
   • Cron expression
   • Human-readable schedule interpretation
   • Next 3 scheduled run times </​Steps>

<Tool_Usage>

• Bash -- Manage system crontab via crontab -l, crontab -e, crontab <file>. Calculate next run times, validate expressions.
• Read -- Read pipeline definitions that reference cron schedules.
• Grep -- Search for cron references across configuration files. </​Tool_Usage>

<Examples> <Good> User says "schedule a heartbeat every 30 minutes": 1. Parse: "every 30 minutes" -> `*/​30 * * * *` 2. Validate: expression is correct 3. Check duplicates: no existing heartbeat cron via `crontab -l` 4. Register: Add `*/​30 * * * * /​path/​to/​heartbeat.sh # heartbeat-30m` to crontab 5. Verify: job appears in `crontab -l` 6. Report: "Heartbeat scheduled every 30 minutes. Next runs: 10:00, 10:30, 11:00"

Why good: Clean natural language parsing, full validation cycle, clear confirmation. </​Good>

<Good> User says "show me all my scheduled jobs": 1. Call `crontab -l` 2. Parse output and format as table: | Name | Schedule | Expression | |------|----------|------------| | heartbeat-30m | Every 30 min | */​30 * * * * | | morning-brief | Weekdays 8am | 0 8 * * 1-5 | | deploy-monitor | Every 5 min | */​5 * * * * | 3. Show next scheduled run for each

Why good: Clear, tabular output with all relevant information. </​Good>

<Bad> User says "run this at 8am" and the agent registers `0 8 * * *` without asking if they mean daily or just once.

Why bad: "at 8am" is ambiguous -- could mean once or daily. Should clarify with user before registering a recurring job. </​Bad>

<Bad> Agent registers a cron job but does not verify it appears in `crontab -l` afterward.

Why bad: Silent failure. The job might not have been added due to a syntax error. Always verify. </​Bad> </​Examples>

<Escalation_And_Stop_Conditions>

• If a cron expression cannot be parsed from natural language, ask the user for clarification rather than guessing
• If a duplicate job exists, ask user whether to replace or rename
• If crontab modification fails, report the specific error message to the user
• If the user's schedule is ambiguous (e.g., "at 8" -- 8am or 8pm?), ask for clarification
• After 3 failed registration attempts, check crontab permissions and escalate
• Stop if the user cancels or decides not to schedule </​Escalation_And_Stop_Conditions>

<Final_Checklist>

• Schedule intent parsed correctly from natural language
• Cron expression generated and validated
• No duplicate jobs with the same schedule
• Job added to system crontab
• Registration verified via crontab -l
• User shown human-readable schedule and next run times
• Timezone handled correctly (default to local if unspecified) </​Final_Checklist>

<Advanced> ## Cron Expression Reference

Field Ranges

Complex Expression Examples

System Crontab Management

System crontab provides standard scheduling with:

• Comments for names: Use # job-name comments to identify jobs
• Standard cron syntax: 5-field expressions (minute hour day month weekday)
• System-level scheduling: Jobs run even when user is not logged in
• Timezone support: Set TZ environment variable in crontab for specific timezones

Timezone Handling

When the user specifies a timezone:

1. Validate it is a valid IANA timezone (e.g., "America/​New_York", "Asia/​Seoul", "Europe/​London")
2. Pass it as the timezone parameter to sc_cron_add
3. Show scheduled times in both the specified timezone and UTC

Common timezone shortcuts:

Monitoring Cron Failures

Set up logging and monitoring for cron jobs:

# Add logging to crontab entries
*/​30 * * * * /​path/​to/​script.sh >> /​var/​log/​cron-heartbeat.log 2>&1

This captures stdout and stderr for debugging failed jobs.

Modifying Existing Jobs

To modify a job, edit the crontab:

crontab -e  # Opens editor to modify cron entries

Or programmatically:

crontab -l | sed '/​old-job/​d' | crontab -  # Remove old job
crontab -l > /​tmp/​crontab.txt
echo "0 9 * * 1-5 /​path/​to/​cmd # old-job" >> /​tmp/​crontab.txt
crontab /​tmp/​crontab.txt

Troubleshooting