cronfish 0.12.1 → 0.13.0

package/README.md

@@ -173,23 +173,34 @@ Sync behavior:
 | ----------------------------- | ------------------------------------------------- |
 | Future                        | plist installed with `StartCalendarInterval` for the exact minute |
 | Within `grace_seconds` of now | plist installed with `RunAtLoad: true` — fires on bootstrap |
-| Past `grace_seconds`          | **refused**; sentinel written to `cron/.errors/`  |
+| Past `grace_seconds`          | **refused**; sentinel written + file archived out of `cron/one-time/` |
 | `executed_at:` already set    | skipped (file should already be archived)         |
 
-After firing, the runner stamps `executed_at: <ISO>` and moves the file to
-`~/Library/Application Support/cronfish/done/` — outside the repo, so the
-audit trail doesn't bloat git. A `flock` plus the `executed_at` re-check guard
-against double-fires. The next `cronfish sync` removes the orphaned plist.
+After firing, the runner stamps `executed_at: <ISO>`, moves the file to
+`~/Library/Application Support/cronfish/done/` (outside the repo, so the audit
+trail doesn't bloat git), and **removes its own plist** so a reboot/login in
+the window before the next `cronfish sync` can't reload and re-fire it. A
+`flock` plus the `executed_at` re-check guard against double-fires.
 
-**One-time jobs must be idempotent.** launchd can re-fire on machine restart,
-system unsleep, or load spikes; the flock + `executed_at` guard catches the
+The runner also **re-checks `grace_seconds` at fire time**: launchd runs a
+`StartCalendarInterval` job once on wake if the machine slept through the
+scheduled minute (a coalesced missed fire), which can land long after `run_at`.
+A fire that arrives past grace is refused (sentinel) instead of running late.
+
+**One-time jobs must be idempotent.** The guards above catch the common
 double-fire, but only after the file is stamped. Anything destructive between
 "start" and "stamp" can repeat. Write handlers that tolerate two invocations.
 
-**Failure surface — `cron/.errors/`.** Any sync-time refusal (past-grace, bad
-YAML, missing `run_at`) writes a sentinel file there with the slug, timestamp,
-and reason. Runner-side failures (archive failed, executed_at write failed)
-also land here. Wire a heartbeat cron to alert on non-empty.
+**Failure surface — `cron/.errors/`.** Any refusal (past-grace, bad YAML,
+missing `run_at`) and any runner-side failure (archive failed, `executed_at`
+write failed) writes a sentinel there with slug, timestamp, and reason. Wire a
+heartbeat cron to alert on non-empty. Two properties keep the folder bounded:
+sentinels **dedup** (the same recurring error overwrites one file, not one per
+sync), and sync-time sentinels **self-heal** — the next clean `cronfish sync`
+clears any whose error no longer occurs. Inspect or clear by hand with
+`cronfish errors` / `cronfish errors --clear [slug]`. cronfish only manages
+files it wrote (`*.cronfish.txt`); a consumer can drop its own sentinels in the
+same folder without them being reaped.
 
 Smoke-test template: `templates/_examples/one-time/echo-at.md`.
 
@@ -207,6 +218,11 @@ Smoke-test template: `templates/_examples/one-time/echo-at.md`.
 fires them. Use it for scheduling candidates — jobs you're staging in `cron/` before flipping on
 a real schedule. Pure on-demand scripts that aren't scheduling candidates belong outside `cron/`.
 
+**Sub-10s schedules don't work.** launchd enforces a ~10s floor between relaunches of the same
+job (its implicit `ThrottleInterval`). A `schedule:` faster than `10s` fires no quicker than every
+10s; `cronfish sync` warns when it sees one. Need true high-frequency work? Run a long-lived loop
+as a single job instead of many fast fires.
+
 ## Config — `.cronfish.json` (optional, at repo root)
 
 ```json
@@ -245,6 +261,7 @@ cronfish enable <slug>              flip enabled, then sync
 cronfish disable <slug>             flip disabled, then sync
 cronfish delete <slug> --yes        bootout + remove plist + job file
 cronfish status [slug]              launchctl print + tail of latest log
+cronfish errors [--clear] [slug]    list error sentinels (cron/.errors/); --clear removes them
 cronfish run <slug>                 invoke runner directly (no launchd) — for testing
 cronfish watchdog                   detect missed schedules → fire alerts
 cronfish alerts test [adapter]      send a test alert via the named (or default) adapter
@@ -531,10 +548,15 @@ via plist `WorkingDirectory`), so no shell wrapper is needed.
 
 - macOS (launchd). Linux (systemd) and Windows (Task Scheduler) are on the backlog.
 - Bun ≥ 1.0.
+- **A logged-in GUI (Aqua) session.** cronfish installs per-user LaunchAgents under
+  `~/Library/LaunchAgents`, which only load while the user is logged into the desktop. On a
+  headless box reached only over SSH (no console login), agents never load and jobs never fire —
+  enable auto-login, or keep a desktop session active. (A system-wide `LaunchDaemon` backend that
+  runs without a login session is on the backlog.)
 
 ## Status
 
-v0.11 — used in production by the author. API may still break before v1. File issues if you hit
+v0.x — used in production by the author. API may still break before v1. File issues if you hit
 something rough.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronfish",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A file-based job scheduler for macOS. Drop a script in a folder; launchd runs it on a schedule.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -15,7 +15,15 @@ import { basename, join } from "node:path";
 import { setFrontmatterKey, setShellFrontmatterKey } from "./frontmatter.ts";
 import { discoverJobs, findJobFile, loadJob, type JobMeta } from "./jobs.ts";
 import { dispatchSchedule, type Dispatched } from "./schedule.ts";
-import { resolveOneTime, writeSentinel } from "./oneTime.ts";
+import {
+  archiveOneTime,
+  clearSentinels,
+  listSentinels,
+  reapStaleSentinels,
+  resolveOneTime,
+  writeSentinel,
+} from "./oneTime.ts";
+import { defaultBundlePrefix } from "./config.ts";
 import { platform } from "./platform/index.ts";
 import { loadState, rememberPrefix } from "./state.ts";
 import { dbPath, markDeleted, openDb, upsertJob } from "./db.ts";
@@ -97,7 +105,7 @@ function parseRetention(raw: unknown): RetentionConfig | undefined {
 
 function loadConfig(): CronfishConfig {
   const path = join(CONSUMER_ROOT, ".cronfish.json");
-  const defaultPrefix = `com.cronfish.${basename(CONSUMER_ROOT)}`;
+  const defaultPrefix = defaultBundlePrefix(CONSUMER_ROOT);
   if (!existsSync(path)) return { bundle_prefix: defaultPrefix };
   let parsed: Partial<CronfishConfig>;
   try {
@@ -327,6 +335,9 @@ function loadRunnerNames(): Set<string> {
 function cmdSync(): void {
   const p = platform();
   const { jobs, errors } = discoverJobs(CRON_DIR);
+  // "sync"-class sentinel filenames written this run. Anything still on disk
+  // from a prior sync that ISN'T in here gets reaped at the end (self-heal).
+  const writtenSentinels = new Set<string>();
   for (const e of errors) {
     console.error(`[cronfish] ${e.path}: ${e.message}`);
     // Bad YAML / invalid run_at on a one-time file → sentinel. Any other
@@ -334,7 +345,13 @@ function cmdSync(): void {
     // cron/one-time/ since silent-skip is the failure mode we're killing.
     if (e.path.includes(`/${"one-time"}/`)) {
       const slug = e.path.split("/").pop() ?? "unknown";
-      writeSentinel(CRON_DIR, slug, `discovery error: ${e.message}`);
+      const written = writeSentinel(
+        CRON_DIR,
+        slug,
+        `discovery error: ${e.message}`,
+        "sync",
+      );
+      writtenSentinels.add(basename(written));
     }
   }
 
@@ -349,6 +366,15 @@ function cmdSync(): void {
         `[cronfish] WARN ${j.slug}: runner "${j.runner}" not in .cronfish.json#runners — known: ${known}`,
       );
     }
+    // launchd enforces a ~10s floor between relaunches (its implicit
+    // ThrottleInterval). A faster `schedule:` silently fires no quicker than
+    // every 10s, so warn rather than let it look like it works.
+    const d = safeDispatch(j.schedule);
+    if (d.kind === "seconds" && d.value < 10) {
+      console.error(
+        `[cronfish] WARN ${j.slug}: schedule ${d.value}s is below launchd's ~10s relaunch floor — it will fire no faster than every 10s`,
+      );
+    }
   }
 
   const state = rememberPrefix(CONSUMER_ROOT, PREFIX);
@@ -367,7 +393,20 @@ function cmdSync(): void {
     ) {
       console.error(`[cronfish] ${j.slug}: ${decision.reason}`);
       if (j.oneTime && decision.reason?.startsWith("one-time past grace:")) {
-        writeSentinel(CRON_DIR, j.slug, decision.reason);
+        // A past-grace one-time file would otherwise be re-discovered on
+        // EVERY sync and re-write a sentinel forever. Record one durable
+        // ("run"-class, never reaped) sentinel so the missed window is
+        // visible, then archive the file out of cron/one-time/ so it stops
+        // recurring.
+        writeSentinel(CRON_DIR, j.slug, decision.reason, "run");
+        try {
+          const dest = archiveOneTime(j.path);
+          console.error(`[cronfish] ${j.slug}: archived past-grace one-time → ${dest}`);
+        } catch (e) {
+          console.error(
+            `[cronfish] ${j.slug}: archive of past-grace one-time failed: ${(e as Error).message}`,
+          );
+        }
       }
     }
   }
@@ -440,6 +479,11 @@ function cmdSync(): void {
     }
   }
 
+  // Self-heal: drop any "sync"-class sentinel that was NOT re-written this
+  // run (its error no longer occurs). "run"-class + foreign files survive.
+  const reaped = reapStaleSentinels(CRON_DIR, writtenSentinels);
+  if (reaped > 0) console.log(`[cronfish] cleared ${reaped} resolved sentinel(s)`);
+
   console.log("[cronfish] sync complete");
 }
 
@@ -949,6 +993,28 @@ function cmdInit(): void {
   );
 }
 
+function cmdErrors(clear: boolean, slug?: string): void {
+  if (clear) {
+    const n = clearSentinels(CRON_DIR, slug);
+    console.log(
+      `[cronfish] cleared ${n} sentinel(s)${slug ? ` for ${slug}` : ""}`,
+    );
+    return;
+  }
+  const files = listSentinels(CRON_DIR);
+  if (files.length === 0) {
+    console.log("[cronfish] no error sentinels");
+    return;
+  }
+  console.log(
+    `[cronfish] ${files.length} error sentinel(s) in cron/.errors/ (clear with \`cronfish errors --clear\`):\n`,
+  );
+  for (const f of files.sort()) {
+    const body = readFileSync(join(CRON_DIR, ".errors", f), "utf-8").trim();
+    console.log(`--- ${f} ---\n${body}\n`);
+  }
+}
+
 function usage(): void {
   console.log(
     `cronfish ${VERSION} — drop a file, schedule it.
@@ -964,6 +1030,7 @@ usage:
   cronfish disable <slug>             flip disabled, then sync
   cronfish delete <slug> --yes        bootout + remove plist + job file
   cronfish status [slug]              all jobs (no arg) or one slug's launchctl + log tail
+  cronfish errors [--clear] [slug]    list error sentinels (cron/.errors/); --clear removes them
   cronfish run <slug>                 invoke runner directly (no launchd)
   cronfish watchdog                   check enabled jobs for missed schedules → fire alerts
   cronfish alerts test [adapter]      send a test alert via the named (or default) adapter
@@ -1055,6 +1122,12 @@ async function main(): Promise<void> {
     case "status":
       cmdStatus(rest[0]);
       return;
+    case "errors": {
+      const clear = rest.includes("--clear");
+      const slug = rest.find((a) => !a.startsWith("-"));
+      cmdErrors(clear, slug);
+      return;
+    }
     case "run":
       if (!rest[0]) throw new Error("usage: cronfish run <slug>");
       await cmdRun(rest[0]);

package/src/config.ts

@@ -0,0 +1,29 @@
+// Shared config helpers. The bundle-prefix formula has to be identical
+// everywhere a launchd label is computed — cli.ts (install/bootout) and
+// runner.ts (one-time self-removal) both derive labels from it, so it lives
+// here rather than being duplicated and drifting.
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export function defaultBundlePrefix(consumerRoot: string): string {
+  return `com.cronfish.${basename(consumerRoot)}`;
+}
+
+// Tolerant prefix read for non-CLI callers (the runner). Returns the default
+// on a missing/unparseable .cronfish.json — the strict validation that the
+// CLI applies at install time has already gated the value by the time a job
+// is running, so the runner only needs to reproduce the same string.
+export function loadBundlePrefix(consumerRoot: string): string {
+  const def = defaultBundlePrefix(consumerRoot);
+  const path = join(consumerRoot, ".cronfish.json");
+  if (!existsSync(path)) return def;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as {
+      bundle_prefix?: string;
+    };
+    return (parsed.bundle_prefix ?? "").trim() || def;
+  } catch {
+    return def;
+  }
+}

package/src/oneTime.ts

@@ -13,12 +13,15 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  readdirSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
   writeSync,
   fsyncSync,
 } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { dlopen, FFIType, suffix } from "bun:ffi";
@@ -111,23 +114,105 @@ export function resolveOneTime(
 
 // --- Error sentinel surface ---
 //
-// Any sync-time failure for a one-time job writes a sentinel here. The
-// heartbeat cron (Phase 2) sweeps this folder and alerts on non-empty.
+// A failure for a one-time job writes a sentinel here; consumers (e.g. a
+// heartbeat job) sweep the folder and alert on non-empty. Two invariants
+// keep the folder from running away:
+//
+//   1. Dedup — the filename is derived from (slug, hash(reason)), so the
+//      SAME error recurring on every sync overwrites one file instead of
+//      writing a new one each minute. An unfixed config error is 1 file,
+//      not thousands.
+//   2. Ownership + class — cronfish-written files carry a `.<class>.cronfish.txt`
+//      suffix so a consumer can drop its own sentinels alongside without
+//      cronfish reaping them. Class "sync" = re-derived every reconcile
+//      (self-heals: reapStaleSentinels removes it once the error stops
+//      recurring). Class "run" = a one-shot runtime failure that is NOT
+//      re-detected at sync, so it persists until `cronfish errors --clear`.
+
+export type SentinelClass = "sync" | "run";
+
+const SENTINEL_EXT = ".cronfish.txt";
 
-export function writeSentinel(cronDir: string, slug: string, reason: string): string {
+function safeSlug(slug: string): string {
+  return slug.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+// Deterministic dedup key: same (slug, reason) → same filename → overwrite.
+export function sentinelFilename(
+  slug: string,
+  reason: string,
+  cls: SentinelClass,
+): string {
+  const hash = createHash("sha1").update(reason).digest("hex").slice(0, 8);
+  return `${safeSlug(slug)}--${hash}.${cls}${SENTINEL_EXT}`;
+}
+
+export function writeSentinel(
+  cronDir: string,
+  slug: string,
+  reason: string,
+  cls: SentinelClass = "run",
+): string {
   const dir = errorsDir(cronDir);
   mkdirSync(dir, { recursive: true });
-  const ts = Date.now();
-  const safeSlug = slug.replace(/[^A-Za-z0-9._-]/g, "_");
-  const path = join(dir, `${ts}-${safeSlug}.txt`);
+  const path = join(dir, sentinelFilename(slug, reason, cls));
   const body =
     `slug: ${slug}\n` +
-    `at: ${new Date(ts).toISOString()}\n` +
+    `at: ${new Date().toISOString()}\n` +
     `reason:\n${reason}\n`;
   writeFileSync(path, body, "utf-8");
   return path;
 }
 
+// Every file currently in cron/.errors/ (basenames), or [] when absent.
+export function listSentinels(cronDir: string): string[] {
+  const dir = errorsDir(cronDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".txt"));
+}
+
+// Remove sentinels. With no slug, clears the whole folder (cronfish-owned
+// AND any legacy/consumer .txt files — the manual `errors --clear` escape
+// hatch). With a slug, clears only files for that slug. Returns the count.
+export function clearSentinels(cronDir: string, slug?: string): number {
+  const dir = errorsDir(cronDir);
+  if (!existsSync(dir)) return 0;
+  const prefix = slug ? `${safeSlug(slug)}--` : null;
+  let n = 0;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".txt")) continue;
+    if (prefix && !f.startsWith(prefix)) continue;
+    try {
+      rmSync(join(dir, f));
+      n++;
+    } catch {}
+  }
+  return n;
+}
+
+// Self-heal for "sync"-class sentinels: after a reconcile, delete any
+// cronfish "sync" sentinel whose filename was NOT (re)written this run —
+// i.e. the error it recorded no longer occurs. "run"-class and foreign
+// files are never touched here.
+export function reapStaleSentinels(
+  cronDir: string,
+  keep: Set<string>,
+): number {
+  const dir = errorsDir(cronDir);
+  if (!existsSync(dir)) return 0;
+  const suffix = `.sync${SENTINEL_EXT}`;
+  let n = 0;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(suffix)) continue;
+    if (keep.has(f)) continue;
+    try {
+      rmSync(join(dir, f));
+      n++;
+    } catch {}
+  }
+  return n;
+}
+
 // --- flock-based re-fire guard ---
 //
 // Real OS-level advisory lock via libc flock(2). Returns the fd on success

package/src/platform/launchd.ts

@@ -360,6 +360,25 @@ export function uninstall(prefix: string, slug: string): boolean {
   return existed;
 }
 
+// Self-removal for a one-time job from inside its own runner process. The
+// runner IS the launchd-managed process here, so `bootout` may SIGTERM us
+// mid-call — remove the plist FILE first so that even if we're killed before
+// bootout returns, launchd can't reload (and RunAtLoad-refire) the job on the
+// next login/reboot. The live bootout is best-effort cleanup of the already-
+// fired service.
+export function removeOneTimeSelf(prefix: string, slug: string): boolean {
+  const label = labelFor(prefix, slug);
+  const dest = plistPathFor(label);
+  const existed = existsSync(dest) || isLoaded(label);
+  if (existsSync(dest)) {
+    try {
+      rmSync(dest);
+    } catch {}
+  }
+  sh(["launchctl", "bootout", `${gui()}/${label}`]);
+  return existed;
+}
+
 export function statusOf(prefix: string, slug: string): string {
   const label = labelFor(prefix, slug);
   const { code, out, err } = sh(["launchctl", "print", `${gui()}/${label}`]);

package/src/runner.ts

@@ -37,14 +37,18 @@ import {
 import { loadJob, slugFromPath, type JobMeta } from "./jobs.ts";
 import { resolveModel, localClaudeEnv } from "./models.ts";
 import {
+  DEFAULT_GRACE_SECONDS,
   archiveOneTime,
   releaseFlock,
+  resolveOneTime,
   setTsExecutedAt,
   tryFlockExclusive,
   writeAndFsync,
   writeSentinel,
   type FlockHandle,
 } from "./oneTime.ts";
+import { loadBundlePrefix } from "./config.ts";
+import { platform } from "./platform/index.ts";
 import { setFrontmatterKey, setShellFrontmatterKey } from "./frontmatter.ts";
 import { parseLastResult } from "./result.ts";
 import {
@@ -550,6 +554,27 @@ function stampExecutedAt(job: JobMeta, iso: string): void {
   writeAndFsync(job.path, next);
 }
 
+// Remove this one-time job's own launchd plist after it has fired. Without
+// this, a fire-now plist (RunAtLoad=true, no calendar) lingers in
+// ~/Library/LaunchAgents until the NEXT `cronfish sync` boots it out — and a
+// reboot/login in that window reloads it and re-fires (against an already-
+// archived file). Self-removing here closes that window regardless of when
+// the consumer next syncs. Best-effort: failures never block completion.
+function selfRemoveOneTimePlist(job: JobMeta): void {
+  // Logs to console (→ launchd.out/err), not the per-run fd: this runs as the
+  // last act after the log fd is already closed, and the bootout it performs
+  // may terminate this process, so it must follow all ledger/alert work.
+  try {
+    const prefix = loadBundlePrefix(consumerRoot());
+    const existed = platform().removeOneTimeSelf(prefix, job.slug);
+    console.log(`[runner] one-time: removed own plist (existed=${existed})`);
+  } catch (e) {
+    console.error(
+      `[runner] one-time: self-remove plist failed: ${(e as Error).message}`,
+    );
+  }
+}
+
 function completeOneTime(job: JobMeta, fd: number): void {
   if (!job.oneTime) return;
   const iso = new Date().toISOString();
@@ -642,6 +667,33 @@ async function main(): Promise<void> {
     } catch {
       // re-parse failed; proceed with the original meta.
     }
+
+    // Re-assert grace at RUN time. launchd fires a StartCalendarInterval job
+    // once on wake if the machine was asleep/off through the scheduled minute
+    // (coalesced) — which can land long past run_at. Grace is checked at sync
+    // time, but nothing re-checks it when launchd actually fires. Refuse a
+    // stale wake-up fire so a one-time job can't run hours/days late, and
+    // remove the plist so it won't try again on the next wake.
+    if (job.runAtMs !== undefined) {
+      const grace = job.graceSeconds ?? DEFAULT_GRACE_SECONDS;
+      const status = resolveOneTime(job.runAtMs, grace, Date.now(), undefined);
+      if (status.kind === "past-grace") {
+        console.error(
+          `[runner] one-time: ${job.slug} fired past grace — refusing. ${status.reason}`,
+        );
+        try {
+          writeSentinel(
+            join(consumerRoot(), "cron"),
+            job.slug,
+            `runtime past grace: ${status.reason}`,
+            "run",
+          );
+        } catch {}
+        if (oneTimeLock) releaseFlock(oneTimeLock);
+        selfRemoveOneTimePlist(job);
+        process.exit(0);
+      }
+    }
   }
 
   if (job.concurrency) {
@@ -761,6 +813,9 @@ async function main(): Promise<void> {
     try {
       db?.close();
     } catch {}
+    // LAST act for a one-time job: remove its own plist. May SIGTERM us via
+    // bootout, so everything above (ledger, alert) is already done.
+    if (job.oneTime) selfRemoveOneTimePlist(job);
   }
   process.exit(lastResult.code);
 }