cronfish 0.12.1 → 0.14.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">cronfish 🐟</h1>
 
-<p align="center"><strong>A file-based job scheduler for macOS. Drop a script in a folder; launchd runs it on a schedule.</strong></p>
+<p align="center"><strong>Write a cron job in Markdown — an LLM runs it on a schedule. Or drop a <code>.ts</code>/<code>.sh</code> script for the deterministic stuff. launchd fires all three.</strong></p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/cronfish"><img src="https://img.shields.io/npm/v/cronfish?logo=npm" alt="npm"></a>
@@ -14,9 +14,24 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
 </p>
 
-Cronfish is for personal automation — the small scheduled jobs you'd otherwise hand-roll as
-launchd plists or crontab lines. Drop a `.md` (Claude prompt), `.ts` (Bun program), or `.sh`
-(bash script) in `cron/`, run `cronfish sync`, and launchd takes it from there.
+The pitch in one file. This is a complete, scheduled cron job:
+
+```markdown
+---
+schedule: "every morning at 8"
+model: sonnet
+---
+
+Read my calendar for today, check the weather, and post a
+one-paragraph brief to the #daily Slack channel.
+```
+
+Drop it in `cron/`, run `cronfish sync`, and launchd runs it every morning — the body _is_ the job,
+handed to an LLM at fire time. No script to write, no glue code. **Markdown is a valid cron job.**
+
+When the work _is_ deterministic — a backup, a sync, a healthcheck — write it as `.ts` (Bun) or
+`.sh` (bash) instead. Same frontmatter, same `cronfish sync`, no LLM in the loop. One scheduler,
+three tiers; reach for the lightest that does the job.
 
 It makes the file the job: frontmatter is the schedule, the path is the slug — no hand-written
 plists, no registration step. You also get per-run logs, retries, concurrency guards, failure
@@ -31,20 +46,24 @@ every kind.
 
 ## Why cronfish?
 
-Claude's native scheduled agents are the obvious alternative, and for pure-LLM tasks they're great
-— zero setup, nothing to host. But everything runs on Anthropic's managed runtime: you pay their
-rates, and every job is a Claude job. Cronfish trades that convenience for control:
+Two kinds of scheduler exist today, and neither does both halves:
+
+- **cron / launchd** run scripts, never prose. A natural-language job isn't expressible.
+- **Claude's native scheduled agents** run prose, but _only_ prose — every job is an LLM job on
+  Anthropic's managed runtime, at their rates.
+
+cronfish runs both from one folder:
 
-- **Any job, not just LLM jobs.** Most scheduled work is plain bash or a TypeScript script — a
-  backup, a sync, a healthcheck. Cronfish runs those first-class, alongside `.md` Claude prompts.
-- **Any harness.** `.md` jobs shell out to a CLI you choose — Claude Code by default, or another
-  agent runner — so you're not locked to one model or one vendor.
-- **Local, so you control the bill.** Jobs run on your machine against whatever model you point
-  them at (hosted Claude, a local Ollama model, a LAN LiteLLM box). No managed-runtime markup, and
-  your data stays on your hardware.
+- **Markdown jobs are natural-language cron.** The body is the instruction; cronfish hands it to an
+  agent CLI (Claude Code by default) at fire time. No other scheduler runs a prose job.
+- **Script jobs stay deterministic.** `.ts` and `.sh` run code you wrote — the standard cron trust
+  model, first-class alongside `.md`.
+- **Any harness, any model, local or hosted.** `.md` jobs shell out to a CLI you choose — point them
+  at hosted Claude, a local Ollama model, or a LAN LiteLLM box. No managed-runtime markup; your data
+  stays on your hardware.
 
 Reach for Claude's scheduler when you want zero-ops and a single LLM task. Reach for cronfish when
-you have a mix of scripts and agents, care about cost, or want to choose the model.
+you want a mix of prose and scripts, care about cost, or want to choose the model.
 
 ## Quickstart
 
@@ -79,7 +98,7 @@ you can document a folder of crons without the README getting parsed as a job.
 ```markdown
 ---
 schedule: "every 5 minutes" # see below for all accepted shapes
-model: haiku # claude alias | raw ID | local:<name>
+model: haiku # claude alias | raw ID | local:<name> | subconscious/<name>
 enabled: true # default true
 timeout: 300 # seconds; runner kills past this
 retries: 0 # retry count on non-zero exit
@@ -129,7 +148,7 @@ invokes the file as `/bin/bash <path>` with `cwd = consumer repo root`; stdout/s
 per-run log. **A `.sh` file with no frontmatter block fails at discovery** — cronfish prints the
 error in `list`/`sync` so you know to add one.
 
-## `model:` — claude alias, raw ID, or local
+## `model:` — claude alias, raw ID, local, or subconscious
 
 For Anthropic-hosted models, use the aliases `haiku` / `sonnet` / `opus` (resolve to the latest
 pinned IDs), or pass a raw ID like `claude-sonnet-4-6` verbatim.
@@ -153,6 +172,13 @@ will hallucinate tool calls. Use 14B+ for any agentic loop; 32B is the practical
 multi-step work. Local providers serve one request at a time — set `concurrency: queue` on
 overlapping jobs.
 
+For a **[Subconscious](https://subconscious.dev)-hosted model**, use the id verbatim with its
+`subconscious/` prefix — e.g. `subconscious/glm-5.2`. Same mechanics as `local:` (base URL +
+slot overrides injected at spawn), pointed at `https://api.subconscious.dev` and authenticated
+with `SUBCONSCIOUS_API_KEY` from the consumer `.env` (scope it into the job with
+`env: [SUBCONSCIOUS_API_KEY]`). Override the endpoint with `SUBCONSCIOUS_BASE_URL`. The job
+fails with a clear error if the key is unset.
+
 ## One-shot jobs — `cron/one-time/`
 
 Drop a `.md`, `.ts`, or `.sh` under `cron/one-time/` to schedule a job that
@@ -173,23 +199,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.
+
+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.** launchd can re-fire on machine restart,
-system unsleep, or load spikes; the flock + `executed_at` guard catches the
+**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 +244,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 +287,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 +574,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.14.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/models.ts

@@ -8,8 +8,12 @@
 // Messages natively; LiteLLM proxies it for everything else). The model
 // ID after the `local:` prefix is passed verbatim to `--model` and as
 // the three slot overrides so sub-agents route locally too.
+//
+// `subconscious/<id>` models route the same way to api.subconscious.dev
+// (a hosted Anthropic-compatible endpoint), authenticated with
+// SUBCONSCIOUS_API_KEY from the job env.
 
-export type Provider = "anthropic" | "local";
+export type Provider = "anthropic" | "local" | "subconscious";
 
 export interface Resolved {
   provider: Provider;
@@ -27,6 +31,11 @@ export function resolveModel(input: string | undefined): Resolved {
   if (raw.startsWith("local:")) {
     return { provider: "local", id: raw.slice("local:".length) };
   }
+  if (raw.startsWith("subconscious/")) {
+    // Subconscious's model namespace includes the prefix (e.g.
+    // subconscious/glm-5.2) — pass the id through verbatim.
+    return { provider: "subconscious", id: raw };
+  }
   if (ALIASES[raw]) return { provider: "anthropic", id: ALIASES[raw] };
   return { provider: "anthropic", id: raw };
 }
@@ -39,6 +48,38 @@ export function localClaudeEnv(modelId: string): Record<string, string> {
   const baseUrl =
     process.env.CRONFISH_LOCAL_BASE_URL ?? "http://localhost:11434";
   const authToken = process.env.CRONFISH_LOCAL_AUTH_TOKEN ?? "ollama";
+  return backendClaudeEnv(baseUrl, authToken, modelId);
+}
+
+// Env block for a `subconscious/*` model — api.subconscious.dev speaks the
+// Anthropic Messages API. Requires SUBCONSCIOUS_API_KEY in the job env
+// (consumer .env; scope with frontmatter `env: [SUBCONSCIOUS_API_KEY]`).
+export function subconsciousClaudeEnv(modelId: string): Record<string, string> {
+  const baseUrl = (
+    process.env.SUBCONSCIOUS_BASE_URL ?? "https://api.subconscious.dev"
+  ).replace(/\/$/, "");
+  const authToken = process.env.SUBCONSCIOUS_API_KEY;
+  if (!authToken) {
+    throw new Error(
+      "[models] SUBCONSCIOUS_API_KEY is not set — required for subconscious/* models",
+    );
+  }
+  return backendClaudeEnv(baseUrl, authToken, modelId);
+}
+
+// Env block for spawning `claude` against the given provider, or undefined
+// for api.anthropic.com models. Single dispatch point for the runner.
+export function claudeEnvFor(r: Resolved): Record<string, string> | undefined {
+  if (r.provider === "local") return localClaudeEnv(r.id);
+  if (r.provider === "subconscious") return subconsciousClaudeEnv(r.id);
+  return undefined;
+}
+
+function backendClaudeEnv(
+  baseUrl: string,
+  authToken: string,
+  modelId: string,
+): Record<string, string> {
   return {
     ANTHROPIC_BASE_URL: baseUrl,
     ANTHROPIC_AUTH_TOKEN: authToken,

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

@@ -35,16 +35,20 @@ import {
   type InvocationTrigger,
 } from "./db.ts";
 import { loadJob, slugFromPath, type JobMeta } from "./jobs.ts";
-import { resolveModel, localClaudeEnv } from "./models.ts";
+import { resolveModel, claudeEnvFor } 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 {
@@ -363,11 +367,11 @@ async function execMarkdown(
     appendLog(fd, `[runner] read-only: deny [${READ_ONLY_DENY.join(", ")}]`);
   }
   const cmd = buildClaudeArgs(CLAUDE_BIN, job, model.id, prompt);
-  const env = model.provider === "local" ? localClaudeEnv(model.id) : undefined;
+  const env = claudeEnvFor(model);
   if (env) {
     appendLog(
       fd,
-      `[runner] local base_url=${env.ANTHROPIC_BASE_URL} model=${model.id}`,
+      `[runner] ${model.provider} base_url=${env.ANTHROPIC_BASE_URL} model=${model.id}`,
     );
   }
   return runSpawn({ cmd, cwd: consumerRoot(), env }, fd, timeoutS);
@@ -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);
 }