cronfish 0.13.0 → 0.15.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.
 
-- **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.
+cronfish runs both from one folder:
+
+- **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
@@ -234,6 +260,7 @@ as a single job instead of many fast fires.
     "on_failure": { "notify": "slack" },
     "default": "slack",
     "slack": { "webhook_url_env": "CRONFISH_SLACK_WEBHOOK" },
+    "slack_bot": { "bot_token_env": "CRONFISH_SLACK_BOT_TOKEN", "channel": "C0123456789" },
     "shell": { "command": "/Users/you/bin/cronfish-pushover.sh" }
   }
 }
@@ -279,6 +306,7 @@ Every failed (`fail` / `timeout` / `crashed`) scheduled run pings the configured
 Adapters ship with cronfish:
 
 - **`slack`** — POSTs Block Kit to an incoming webhook. Reads the URL from the env var named in `alerts.slack.webhook_url_env` (default `CRONFISH_SLACK_WEBHOOK`).
+- **`slack_bot`** — posts the same Block Kit via `chat.postMessage` with a bot token instead of a webhook. One token reaches any channel (with `chat:write.public`, no invite needed), so you skip the per-channel browser-OAuth webhook mint. Reads the token from `alerts.slack_bot.bot_token_env` (default `CRONFISH_SLACK_BOT_TOKEN`) and the target channel from `alerts.slack_bot.channel` (a `C…` id or `#name`) or `alerts.slack_bot.channel_env`. Unlike a webhook, `chat.postMessage` returns HTTP 200 on logical errors, so the adapter inspects the JSON `ok` field and fails on `ok:false` (e.g. `channel_not_found`, `not_in_channel`).
 - **`shell`** — runs an arbitrary command from `alerts.shell.command` with the payload as env vars (`CRONFISH_ALERT_SLUG`, `…_STATUS`, `…_EXIT_CODE`, `…_DURATION_MS`, `…_STARTED_AT`, `…_UI_URL`, `…_LOG_TAIL`) plus the JSON payload on stdin. Use this for Pushover/ntfy/osascript.
 
 Two knobs in `.cronfish.json`, two distinct jobs:
@@ -309,6 +337,10 @@ Sanity check:
 ```
 export CRONFISH_SLACK_WEBHOOK=https://hooks.slack.com/services/...
 cronfish alerts test slack
+
+# or, bot-token path (no webhook to mint):
+export CRONFISH_SLACK_BOT_TOKEN=xoxb-...
+cronfish alerts test slack_bot
 ```
 
 ## Always-on dashboard

package/examples/.cronfish.json

@@ -12,6 +12,7 @@
     "on_failure": { "notify": "slack" },
     "default": "slack",
     "slack": { "webhook_url_env": "CRONFISH_SLACK_WEBHOOK" },
+    "slack_bot": { "bot_token_env": "CRONFISH_SLACK_BOT_TOKEN", "channel": "C0123456789" },
     "shell": { "command": "/usr/local/bin/my-notify.sh" }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronfish",
-  "version": "0.13.0",
+  "version": "0.15.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/alerts/index.ts

@@ -1,6 +1,7 @@
 export { buildRegistry, type AdapterRegistry } from "./registry.ts";
 export { safeNotify, type AlertOutcome, type AlertOutcomeStatus } from "./safe.ts";
 export { createSlackAdapter, buildSlackBlocks } from "./slack.ts";
+export { createSlackBotAdapter, type SlackBotAdapterOptions } from "./slack-bot.ts";
 export { createShellAdapter, payloadEnv } from "./shell.ts";
 export {
   alertStatusFor,

package/src/alerts/registry.ts

@@ -1,4 +1,5 @@
 import { createShellAdapter } from "./shell.ts";
+import { createSlackBotAdapter } from "./slack-bot.ts";
 import { createSlackAdapter } from "./slack.ts";
 import type { Adapter, AlertsConfig } from "./types.ts";
 
@@ -11,6 +12,7 @@ export interface AdapterRegistry {
 export function buildRegistry(cfg: AlertsConfig = {}): AdapterRegistry {
   const map = new Map<string, Adapter>();
   map.set("slack", createSlackAdapter(cfg.slack));
+  map.set("slack_bot", createSlackBotAdapter(cfg.slack_bot));
   map.set("shell", createShellAdapter(cfg.shell));
   return {
     get(name) {

package/src/alerts/slack-bot.ts

@@ -0,0 +1,80 @@
+// Bot-token Slack adapter — the API-driveable twin of the webhook `slack`
+// adapter. Where `slack` POSTs Block Kit to a per-channel incoming webhook (URL
+// bound to one channel at mint time, only creatable via browser OAuth), this
+// posts via `chat.postMessage` with a bot token: one credential reaches any
+// channel by id/name (with `chat:write.public`, without being invited). Same
+// Block Kit body — it reuses `buildSlackBlocks`, so alerts render identically.
+//
+// Unlike an incoming webhook (which signals failure with a non-2xx status),
+// `chat.postMessage` returns HTTP 200 even on logical errors and carries the
+// real outcome in the JSON `ok`/`error` fields — so this adapter parses the
+// body and throws on `ok:false`, not just on a bad status.
+
+import { buildSlackBlocks } from "./slack.ts";
+import type { Adapter, AlertPayload, AlertsConfig } from "./types.ts";
+
+const DEFAULT_TOKEN_ENV = "CRONFISH_SLACK_BOT_TOKEN";
+const POST_MESSAGE_URL = "https://slack.com/api/chat.postMessage";
+
+export interface SlackBotAdapterOptions {
+  botToken?: string;
+  channel?: string;
+  fetchFn?: typeof fetch;
+}
+
+export function createSlackBotAdapter(
+  cfg: AlertsConfig["slack_bot"] = {},
+  opts: SlackBotAdapterOptions = {},
+): Adapter {
+  const tokenEnv = cfg.bot_token_env ?? DEFAULT_TOKEN_ENV;
+  const fetchFn = opts.fetchFn ?? fetch;
+  return {
+    name: "slack_bot",
+    async notify(payload: AlertPayload): Promise<void> {
+      const token = opts.botToken ?? process.env[tokenEnv];
+      if (!token) {
+        throw new Error(`slack-bot adapter: env var ${tokenEnv} not set`);
+      }
+      const channel =
+        opts.channel ??
+        (cfg.channel_env ? process.env[cfg.channel_env] : undefined) ??
+        cfg.channel;
+      if (!channel) {
+        throw new Error(
+          "slack-bot adapter: no channel configured " +
+            "(set alerts.slack_bot.channel or alerts.slack_bot.channel_env)",
+        );
+      }
+      const blocks = buildSlackBlocks(payload);
+      const res = await fetchFn(POST_MESSAGE_URL, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json; charset=utf-8",
+          authorization: `Bearer ${token}`,
+        },
+        // `text` is the notification/accessibility fallback Slack shows when
+        // blocks can't render (push notifications, screen readers).
+        body: JSON.stringify({
+          channel,
+          text: `${payload.status.toUpperCase()} — ${payload.slug}`,
+          blocks,
+        }),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(
+          `slack-bot adapter: chat.postMessage returned ${res.status} ${body.slice(0, 200)}`,
+        );
+      }
+      const data = (await res.json().catch(() => ({}))) as {
+        ok?: boolean;
+        error?: string;
+      };
+      if (!data.ok) {
+        throw new Error(
+          `slack-bot adapter: chat.postMessage failed: ${data.error ?? "unknown error"}`,
+        );
+      }
+    },
+  };
+}

package/src/alerts/types.ts

@@ -28,6 +28,14 @@ export interface AlertsConfig {
   slack?: {
     webhook_url_env?: string;
   };
+  slack_bot?: {
+    // Env var holding the bot token (xoxb-…). Default CRONFISH_SLACK_BOT_TOKEN.
+    bot_token_env?: string;
+    // Target channel — id (C…) or #name. Literal value…
+    channel?: string;
+    // …or the env var to read it from (takes precedence over `channel`).
+    channel_env?: string;
+  };
   shell?: {
     command?: string;
   };

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/runner.ts

@@ -35,7 +35,7 @@ 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,
@@ -367,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);
@@ -708,6 +708,23 @@ async function main(): Promise<void> {
     }
   }
 
+  // Install lock-release signal handlers the instant a lock exists. There is
+  // real setup below (DB init, log open) before the full `cleanup` handler is
+  // registered, and a SIGTERM in that window would otherwise kill the process
+  // by default disposition — no handler runs, and the concurrency lockfile is
+  // orphaned (unlike the flock, it is not reclaimed by the OS on exit). This
+  // minimal handler is superseded by `cleanup` once the invocation state exists.
+  let releasing = false;
+  const earlyCleanup = (sig: NodeJS.Signals): void => {
+    if (releasing) return;
+    releasing = true;
+    if (job.concurrency) releaseLock(job.slug);
+    if (oneTimeLock) releaseFlock(oneTimeLock);
+    process.exit(sig === "SIGTERM" ? 143 : 130);
+  };
+  process.on("SIGTERM", earlyCleanup);
+  process.on("SIGINT", earlyCleanup);
+
   const db = tryOpenDb();
 
   // Open the log file BEFORE we know the invocation id (we need a real
@@ -739,8 +756,12 @@ async function main(): Promise<void> {
     appendLog(fd, `[runner] invocation_id=${invocationId} trigger=${trigger}`);
   }
 
-  // Signal handlers — release lock + record crash on launchd shutdown.
-  let releasing = false;
+  // Signal handlers — release lock + record crash on launchd shutdown. This
+  // supersedes earlyCleanup now that the invocation row exists, so a SIGTERM
+  // also records the run as crashed. The off→on swap is synchronous (no await
+  // between), so no signal can slip through with zero handlers installed.
+  process.off("SIGTERM", earlyCleanup);
+  process.off("SIGINT", earlyCleanup);
   const cleanup = (sig: NodeJS.Signals): void => {
     if (releasing) return;
     releasing = true;