feat(cron): precheck gate — skip the LLM session when a shell check finds no work

[nyem69]

What

Adds optional CronJob.precheck — a cheap shell command the scheduler runs before creating the (expensive) LLM session, skipping the session entirely when there's nothing to do.

Why

The fleet's dominant cost pattern is high-frequency watcher/queue jobs that boot a full LLM session every fire just to run a deterministic prefilter that usually finds no work:

Job	~$/mo	sched	shape
jinn-group-watcher	~$210 (≈25% of spend)	hourly 8–23	shell prefilter run inside a session every fire
plan-url-queue-processor	~$95	every 30m	empty-queue most fires
sitrep-regen-watch	~$57	every 15m 1–7am	"needs regen?" usually no
social-alert	~$54	11×/day
top-4	~$520 / 41%		mostly no-op LLM boots

jinn-group-watcher already has jinn-watcher-prefilter.sh, but the session boots, reads context, runs the prefilter, finds nothing, and exits — every hour. This moves the gate to the scheduler so no-op fires never spawn Claude.

Contract

exit 0                 -> proceed (spawn as today)
exit ∈ skipExitCodes   -> gated-skip   (no session, no alert, runlog only)
any other non-zero     -> precheck_error (no session, ops alert)
timeout                -> precheck_error

skipExitCodes is required for any skip — with none set, every non-zero is an error. Deliberate: stops a real outage being silently skipped. The first adopter's prefilter proves why blanket "non-zero = skip" is wrong — 0=URLs, 10=no-op, 20=lock-contention, 21–24=wacli/JSON/state/watermark failures. So skipExitCodes: [10,20]; 21–24 surface as precheck_error.

Implementation

• shared/types.ts — CronJob.precheck { command, timeoutMs?, skipExitCodes? }, optional/back-compat.
• cron/precheck.ts — runPrecheck(): /bin/bash -c in JINN_HOME, timeout (default 60s), captured output; never rejects.
• cron/runner.ts — gate before session creation; new runlog statuses gated-skip / precheck_error; ops-alert only on error, never on a no-work skip. Gated-skip still writes a runlog entry + lastStartedAt, so catch-up dedup treats the slot as serviced (no double-fire).

Tests (790 pass, tsc clean)

• precheck.test.ts (real bash): proceed / skip / 2nd-skip-code / non-listed-nonzero=error / no-skip-codes-never-skips-blind / timeout / invalid-config / stdout.
• runner.test.ts: proceed spawns; skip+error+timeout don't; skip silent; error ops-alerts; no-precheck jobs bypass (back-compat).

Rollout (staged)

Migrate only jinn-group-watcher first (jinn-data repo, after this deploys): prefilter moves from in-session Step 1 to precheck, prompt collapses to the process-URLs branch. Observe live skip rate + cost delta, then apply to plan-url-queue-processor / sitrep-regen-watch / social-alert.

🤖 Generated with Claude Code