Schedule Crons

Schedule Crons

Re-create all session cron jobs for Sutando. Run this on startup or after a session restart.

Usage: /schedule-crons

How It Works

Jobs are defined per host in <workspace>/hosts/<hostname>/crons.json — per-host, synced + backed up via the vault (carried as part of the hosts/*/ per-host subtree (#1717), which is hostname-qualified so it never collapses across hosts; see docs/workspace-hosts-convention.md and docs/workspace-per-host-paths.md). <hostname> is bash scripts/sutando-config.sh host-label — the canonical per-host label ($SUTANDO_HOST_LABEL > scutil LocalHostName > short hostname), matching the sync layer's host slug. (Do NOT use a bare hostname | sed 's/\..*//': a DHCP lease can drift the hostname (e.g. Comcast → Chis-MBP) and split per-host paths from the stable label; #1745.) A template is in crons.example.json (in this skill dir, version-controlled). Copy it on first setup:

WS="$(bash scripts/sutando-config.sh workspace)"; H="$(bash scripts/sutando-config.sh host-label)"; mkdir -p "$WS/hosts/$H"
cp skills/schedule-crons/crons.example.json "$WS/hosts/$H/crons.json"

(Migrated from the old skills/schedule-crons/crons.json, which lived in the code checkout — misfiled per the workspace contract, and per-host-but-unsynced. The new path is proper per-user state: backed up + visible across hosts, each host keeping its own cron set.)

Each entry has:

• name — unique identifier (used to avoid duplicates)
• cron — 5-field cron expression
• prompt — the prompt to run (direct text)
• prompt_skill — OR a skill to invoke (e.g. "morning-briefing" → /morning-briefing)
• loop (optional, value "dynamic") — declares a dynamic (self-pacing) loop using the built-in /loop primitive. An entry with no interval (no cron field) + loop: "dynamic" is run by schedule-crons as /loop without an interval (see step 3) — which is exactly the built-in adaptive mode: the loop self-paces via ScheduleWakeup, deciding each next delay by its own judgment. Optional loop_hint (free text) guides that pacing (e.g. "~10 min when owner active, ~40 min quiet"). Durable because schedule-crons re-launches it every boot; adaptive because that's what /loop-no-interval already is. No min/max/signal schema and no custom gate — the built-in does the pacing. Example: {name:"inbox-score", prompt_skill:"inbox-score", loop:"dynamic", loop_hint:"…"}.
• execution (optional, value "codex-task") — opt this entry into the durable OS-backed Codex runner instead of session cron registration. Codex entries may also set timezone (IANA name, default America/Los_Angeles), delivery: "proactive", retry_minutes (default 15), max_attempts (default 3), and active_stale_minutes (default 60). Jobs require this explicit opt-in except for the canonical main-loop while the selected runtime is Codex; the runtime-specific exception is described below.
• launchd (optional bool) — when true, the entry is owned by the OS-level cron-runner (src/cron-runner.py, installed via src/install-cron-runner-launchd.sh), NOT by this session skill. /schedule-crons skips these so the two schedulers never double-fire. Use it for daily-deliverable crons that must fire even when no Claude session is idle (the reliability fix for the 2026-07-02 silent 6am-digest miss).
• monitor (optional object) — declares a persistent Monitor-based driver, NOT a cron: the entry is armed via the Monitor tool and re-armed on every /schedule-crons, so it survives restarts the way the task watcher (step 1.5) does. Shape: {"command": "<shell to run>", "description": "<one-line>", "match": "<argv substring that detects a running instance>"}. It is NOT CronCreated and NOT counted in the stamp's registered (it is not a session cron). Armed in step 5.4. Use it for a continuous event-emitting driver (e.g. the content-loop) that must re-arm across restarts.
• artifact (optional string) — the filename STEM of the dated output this job produces, e.g. "fleet-growth" for fleet-growth-2026-08-18.mp4. Read by health-check.py's daily-cron-punctuality probe. Without it the probe infers a stem from the last hyphenated token of the job name, so talk-events-nightly looks for nightly-<date>.*, never observes the real artifact, and reports the job UNCHECKED forever. Declare it whenever the name does not already equal the stem.
• conditional (optional bool) — set true when the job runs on schedule but produces output only if there is new input (a nightly render with no new beats). The punctuality probe then treats "no artifact today" as evidence of nothing rather than a miss; lateness is still measured from the artifacts that do exist. On macOS, the Codex core launcher automatically reconciles ordinary fixed-interval entries to this owner because Codex has no session CronCreate surface. It preserves main-loop, dynamic loops, and entries already owned by execution: "codex-task", and initializes the runner boundary before changing ownership so activation never replays an old action backlog.

Durable Codex schedules

Install or reconcile the per-minute launchd runner after adding an execution: "codex-task" entry:

python3 skills/schedule-crons/scripts/codex-scheduler.py install
python3 skills/schedule-crons/scripts/codex-scheduler.py health

The runner calculates cron slots in each job's declared timezone, catches up the newest missed slot after sleep, atomically enqueues a deterministic task ID, and uses distinct attempt IDs when an inactive task needs retrying. A queued, claimed, or processed attempt is never duplicated; if it remains active past active_stale_minutes, the run fails with a proactive alert so the schedule cannot stall forever. Durable run state lives at <workspace>/state/schedules/codex-scheduler.json. Exhausted retries produce a proactive-schedule-alert-*.txt result. health exits non-zero for a stale scheduler heartbeat or a latest-run failure.

When core.runtime is codex, the canonical unmarked main-loop entry (prompt_skill: "proactive-loop") is also owned automatically by this runner. Codex has no session CronCreate surface, so each fire emits one silent, low-priority proactive-pass task. The host's crons.json is not rewritten; switching back to Claude restores the normal session-owned loop. The Codex launcher reconciles the launchd runner on every start or attach.