alvin-bot 4.8.9 → 4.9.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.9.0] — 2026-04-11
+
+### 🛡 Stability batch: crash-loop eliminated, cron jobs restart-resistant, cleaner logs
+
+Production users reported a daily-job-alert that "kept crashing" — the cron job triggered at 08:00, died mid-execution, and the next scheduled run silently disappeared until the next day. Root cause was not a single bug but a chain of four: the HTTP Web UI never released its port on shutdown → `EADDRINUSE :::3100` uncaught crash-loop → the cron scheduler persisted `nextRunAt = null` pre-execution → restart rewrote it to "tomorrow 08:00" → the run was lost. In parallel, sub-agents that ended on a tool call reported "completed" with only the pre-tool text as output, and grammy's "message is not modified" races leaked into Telegram replies as `Fehler: Call to 'editMessageText' failed!`.
+
+This release closes the whole chain, adds the Tier 0 of the browser fallback, and installs timestamped logs so future forensics don't need timestamp-free grep archaeology.
+
+**Pure functions extracted for isolated testing** (36 new tests, 154 total):
+
+- `src/services/cron-scheduling.ts` — `prepareForExecution(job, now)` and `handleStartupCatchup(jobs, now, graceMs)`. The old scheduler set `nextRunAt = null` before `await executeJob(job)` and only recomputed after completion. A crash mid-execution left `nextRunAt = null`; the next boot recomputed it from the current time → always landed on tomorrow's trigger. Now `prepareForExecution` persists the NEXT regular trigger BEFORE running, and stamps `lastAttemptAt`. If `lastAttemptAt > lastRunAt` at boot and the attempt is ≤ 6 h old, `handleStartupCatchup` rewinds `nextRunAt` to `now` so the next tick picks it up. New `CronJob.lastAttemptAt` field (`number | null`).
+- `src/services/watchdog-brake.ts` — `decideBrakeAction(prev, now, opts)` and `shouldResetCrashCounter(uptimeMs, opts)`. The old brake reset `crashCount` after 5 minutes of clean uptime, which was shorter than the typical sub-agent lifetime — chronic crashes with 5–10 min gaps passed the brake indefinitely. New policy: **1 h clean uptime required for reset**, plus a hard **20 crashes / 24 h** daily cap alongside the existing 10 crashes / 10 min short-window cap. Both counters persist in the beacon.
+- `src/util/debounce.ts` — trailing-edge debounce for fs.watch coalescing.
+- `src/util/console-formatter.ts` — `installConsoleFormatter()`: monkey-patches `console.log/warn/info/error` to prefix every line with an ISO timestamp, and drops libsignal "Closing session" multi-line SessionEntry dumps + `[claude] Native binary` spam that were pushing tens of KB per day into `alvin-bot.out.log` / `alvin-bot.err.log`.
+- `src/util/telegram-error-filter.ts` — `isHarmlessTelegramError(err)`: single source of truth for benign grammy races (`message is not modified`, `query is too old`, `message to edit not found`, `MESSAGE_ID_INVALID`, …).
+- `src/services/browser-webfetch.ts` — `webfetchNavigate(url, opts)` + `parseTitle(html)` + `WebfetchFailed`: Tier 0 of the browser fallback chain. Plain `fetch()` instead of Playwright for static pages.
+- `src/platforms/whatsapp-auth-helpers.ts` — `makeResilientSaveCreds(authDir, inner)`: wraps baileys' `saveCreds` so an ENOENT from a vanished auth dir transparently recreates the directory and retries once.
+
+**Fixes wired into the existing modules:**
+
+- **`src/web/server.ts` — new `stopWebServer(server)`.** Closes WebSocket clients, calls `closeIdleConnections()` + `closeAllConnections()` (Node 18.2+) so long-poll clients can't stall the shutdown, then awaits `server.close()`. Called from `shutdown()` in `src/index.ts`. Before this fix, launchd restarted the bot → new process tried `server.listen(3100)` → `EADDRINUSE` → uncaught exception → exit → launchd again. Classic crash-loop. **This single fix stops the chain.**
+- **`src/services/cron.ts`** — scheduler rewired to call `prepareForExecution` pre-execution and `handleStartupCatchup` at boot. `lastResult` truncation bumped from 500 → 4000 chars so post-mortem is possible without running the job again.
+- **`src/services/watchdog.ts`** — beacon schema extended with `dailyCrashCount` + `dailyCrashWindowStart`; `startWatchdog` now delegates the brake decision to the pure `decideBrakeAction`. Recovery timer still fires, but only resets the counter if `shouldResetCrashCounter` agrees (≥ 1 h uptime).
+- **`src/services/subagents.ts`** — `runSubAgent` now reads `finalText` from the `done` chunk as the authoritative final output (was ignored before), preserves buffered text when the stream emits an `error` chunk, and — most importantly — keeps `finalText` when the catch handler fires (was `output: ""`, throwing away multi-minute runs). Variable scope moved outside the try block. New `error` status branch for mid-stream provider failures.
+- **`src/services/subagent-delivery.ts`** — `buildBanner` now renders `⚠️ completed · empty output` for the "successful run with zero text" case so truncated runs are immediately visible instead of hiding behind a green tick.
+- **`src/services/skills.ts`** — `fs.watch` callbacks wrapped in `debounce(…, 300)` so macOS FSEvents duplicates coalesce into one reload.
+- **`src/services/browser-manager.ts`** — new `webfetch` tier added as default for non-interactive tasks. `resolveStrategy` cascade is now `webfetch → hub-stealth → cdp → gateway → cli`. `navigate()` has an error-based fallback: if `webfetch` throws (403, 5xx, content-type mismatch), it transparently upgrades to `hub-stealth` then `cli` before giving up.
+- **`src/platforms/whatsapp.ts`** — `saveCreds` wrapped in `makeResilientSaveCreds` so a vanished auth dir self-heals instead of becoming an unhandled rejection.
+- **`src/handlers/message.ts`, `src/services/telegram.ts`, `src/index.ts` (bot.catch + streaming finalize)** — all three call sites that used to ship the raw grammy error to users now route through `isHarmlessTelegramError`. The `Fehler: Call to 'editMessageText' failed!` noise that 2-3 users per day were seeing is gone.
+
+**What is NOT changed:**
+
+- **Timeouts.** The v4.8.8 `defaultTimeoutMs = -1` (unlimited) behavior is preserved. Sub-agents and cron jobs can still run as long as they need.
+- **The cron job `payload.prompt`s.** Users' existing cron definitions keep working unchanged.
+- **The beacon file format back-compat.** Old beacons without the daily counters are read correctly; the new fields are seeded to 0/now on first boot.
+
+**How to verify after update:**
+
+1. `launchctl unload ~/Library/LaunchAgents/com.alvinbot.app.plist && launchctl load ~/Library/LaunchAgents/com.alvinbot.app.plist`
+2. Tail `~/.alvin-bot/logs/alvin-bot.out.log` — every line should now carry an ISO timestamp and libsignal SessionEntry dumps should be gone.
+3. Check `~/.alvin-bot/state/watchdog.json` — should contain `dailyCrashCount` / `dailyCrashWindowStart` within a minute.
+4. Send `/cron run Daily Job Alert` — subagent-delivery banner should render fully, `~/.alvin-bot/cron-jobs.json` should show `lastAttemptAt` and a post-execution `lastRunAt`.
+5. Trigger a deliberate edit race (double-tap an inline button quickly) — no `Fehler: Call to 'editMessageText' failed!` reply should land in the chat.
+
 ## [4.8.9] — 2026-04-11
 
 ### 🐛 Browser automation: dead `browse-server.cjs` path removed, 3-tier router now the source of truth

package/dist/handlers/message.js

@@ -14,6 +14,7 @@ import { emit } from "../services/hooks.js";
 import { trackUsage } from "../services/usage-tracker.js";
 import { emitUserMessage as broadcastUserMessage, emitResponseStart as broadcastResponseStart, emitResponseDelta as broadcastResponseDelta, emitResponseDone as broadcastResponseDone, } from "../services/broadcast.js";
 import { t } from "../i18n.js";
+import { isHarmlessTelegramError } from "../util/telegram-error-filter.js";
 /**
  * Stuck-only timeout — NO absolute cap.
  *
@@ -367,7 +368,7 @@ export async function handleMessage(ctx) {
                     if (timedOut) {
                         await ctx.reply(t("bot.error.timeoutStuck", session.language, { min: STUCK_TIMEOUT_MINUTES }));
                     }
-                    else {
+                    else if (!isHarmlessTelegramError(chunk.error)) {
                         await ctx.reply(`${t("bot.error.prefix", session.language)} ${chunk.error}`);
                     }
                     break;
@@ -419,7 +420,9 @@ export async function handleMessage(ctx) {
         else if (errorMsg.includes("abort")) {
             await ctx.reply(t("bot.error.requestCancelled", lang));
         }
-        else {
+        else if (!isHarmlessTelegramError(err)) {
+            // Drop benign grammy races ("message is not modified", etc.)
+            // instead of surfacing them as "Fehler: ..." replies.
             await ctx.reply(`${t("bot.error.prefix", lang)} ${errorMsg}`);
         }
     }

package/dist/index.js

@@ -1,6 +1,12 @@
 // ── Bootstrap: ensure ~/.alvin-bot/ exists + migrate legacy data ────
 import { ensureDataDirs, seedDefaults } from "./init-data-dir.js";
 import { hasLegacyData, migrateFromLegacy } from "./migrate.js";
+import { installConsoleFormatter } from "./util/console-formatter.js";
+import { isHarmlessTelegramError } from "./util/telegram-error-filter.js";
+// 0. Install timestamp + noise-filter formatters on console.* so every
+//    line in out.log / err.log carries an ISO timestamp and libsignal's
+//    SessionEntry dumps stop burying the signal.
+installConsoleFormatter();
 // 1. Create directory structure (no files yet)
 ensureDataDirs();
 // 2. Migrate legacy data BEFORE seeding defaults (so real data wins over templates)
@@ -70,7 +76,7 @@ import { handleVideo } from "./handlers/video.js";
 import { initEngine } from "./engine.js";
 import { loadPlugins, registerPluginCommands, unloadPlugins } from "./services/plugins.js";
 import { initMCP, disconnectMCP, hasMCPConfig } from "./services/mcp.js";
-import { startWebServer } from "./web/server.js";
+import { startWebServer, stopWebServer } from "./web/server.js";
 import { startScheduler, stopScheduler, setNotifyCallback } from "./services/cron.js";
 import { startSessionCleanup, stopSessionCleanup } from "./services/session.js";
 import { processQueue, cleanupQueue, setSenders, enqueue } from "./services/delivery-queue.js";
@@ -220,16 +226,11 @@ if (hasTelegram) {
     bot.catch((err) => {
         const ctx = err.ctx;
         const e = err.error;
-        // Telegram's "message is not modified" (400) is harmless — it fires
-        // when a callback handler re-renders an inline keyboard / edited
-        // message with content that happens to match the current message
-        // exactly (e.g. double-tapped toggle button, identical list after
-        // re-render). Swallow it silently so it neither pollutes the logs
-        // nor bubbles up to the user as "internal error".
-        const msg = e instanceof Error ? e.message : String(e);
-        if (/message is not modified/i.test(msg) || /specified new message content.*exactly the same/i.test(msg)) {
+        // Swallow the well-known harmless grammy races (message is not
+        // modified, query too old, message to edit not found …) silently.
+        // See src/util/telegram-error-filter.ts for the exhaustive list.
+        if (isHarmlessTelegramError(e))
             return;
-        }
         console.error(`Error handling update ${ctx?.update?.update_id}:`, e);
         // Try to notify the user
         if (ctx?.chat?.id) {
@@ -260,6 +261,9 @@ const shutdown = async () => {
         clearInterval(queueCleanupInterval);
     if (bot)
         bot.stop();
+    // Release :3100 so the next launchd boot doesn't hit EADDRINUSE.
+    // Must happen before exit — see src/web/server.ts stopWebServer() comment.
+    await stopWebServer(webServer).catch((err) => console.warn("[shutdown] stopWebServer failed:", err));
     await unloadPlugins().catch(() => { });
     await disconnectMCP().catch(() => { });
     // Tear down any bot-managed local runners (Ollama, LM Studio, …) so VRAM

package/dist/platforms/whatsapp-auth-helpers.js

@@ -0,0 +1,53 @@
+/**
+ * WhatsApp auth helpers — tiny resilience wrappers around baileys'
+ * use-multi-file-auth-state output.
+ *
+ * Why this exists: baileys' `saveCreds` is called asynchronously from
+ * the `creds.update` socket event, long after the auth directory was
+ * created at init time. If anything wipes the directory between init
+ * and the first save — a crash mid-init, a manual rm -rf, a stale
+ * worker on a different code path — the write throws ENOENT and becomes
+ * an `unhandledRejection`, which node 15+ default-reports as a crash.
+ *
+ * This module keeps the wrapper separate from `whatsapp.ts` so it can
+ * be unit-tested without having to drag baileys into the test process.
+ */
+import fs from "fs";
+/**
+ * Wrap a baileys saveCreds so a missing auth directory is transparently
+ * recreated once and the save is retried. Any other error, and any
+ * second ENOENT in a row, surfaces unchanged.
+ */
+export function makeResilientSaveCreds(authDir, innerSaveCreds) {
+    return async function resilientSaveCreds() {
+        try {
+            await innerSaveCreds();
+            return;
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+            // baileys-auth dir vanished between init and now — rebuild and retry once.
+            try {
+                fs.mkdirSync(authDir, { recursive: true });
+            }
+            catch {
+                // If mkdir itself fails, fall through to the retry — it will surface
+                // the real error below with its original stack.
+            }
+            await innerSaveCreds();
+        }
+    };
+}
+function isEnoent(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.code;
+    if (code === "ENOENT")
+        return true;
+    // Some baileys wrapper paths re-throw as a plain Error with a message
+    // like "ENOENT: no such file or directory, open '.../creds.json'" but
+    // without .code — match the message as a fallback.
+    const msg = err.message || "";
+    return /ENOENT/.test(msg);
+}

package/dist/platforms/whatsapp.js

@@ -19,6 +19,7 @@
 import fs from "fs";
 import { dirname, join } from "path";
 import { WHATSAPP_AUTH as AUTH_DIR, WA_GROUPS as GROUP_CONFIG_FILE, WA_MEDIA_DIR } from "../paths.js";
+import { makeResilientSaveCreds } from "./whatsapp-auth-helpers.js";
 function loadGroupConfig() {
     try {
         return JSON.parse(fs.readFileSync(GROUP_CONFIG_FILE, "utf-8"));
@@ -250,8 +251,11 @@ export class WhatsAppAdapter {
             generateHighQualityLinkPreview: false,
         });
         this.sock = sock;
-        // Save credentials on update
-        sock.ev.on("creds.update", saveCreds);
+        // Save credentials on update. Wrapped so a vanished auth dir (crash
+        // mid-init, manual cleanup, etc.) doesn't turn the next creds.update
+        // into an unhandled ENOENT rejection.
+        const resilientSaveCreds = makeResilientSaveCreds(authDir, saveCreds);
+        sock.ev.on("creds.update", resilientSaveCreds);
         // Connection state
         sock.ev.on("connection.update", (update) => {
             const { connection, lastDisconnect, qr } = update;

package/dist/services/browser-manager.js

@@ -16,6 +16,7 @@ import fs from "fs";
 import { config } from "../config.js";
 import { BROWSE_SERVER_SCRIPT, HUB_BROWSER_SH } from "../paths.js";
 import { screenshotUrl, extractText, generatePdf } from "./browser.js";
+import { webfetchNavigate, WebfetchFailed } from "./browser-webfetch.js";
 const CDP_PORT = 9222;
 const EXEC_TIMEOUT = 60_000; // 60s for page loads via shell
 // ── Logging ──────────────────────────────────────────────────────────
@@ -53,30 +54,52 @@ async function isCDPAvailable() {
     });
 }
 // ── Strategy Selection with Fallback ─────────────────────────────────
-/** Pick the preferred strategy based on task type */
+/** Pick the preferred strategy based on task type.
+ *
+ *  Default for a one-shot read is `webfetch` — the cheapest tier. It
+ *  only fails on JS-heavy or bot-guarded pages, and the cascade in
+ *  resolveStrategy() handles the upgrade path automatically.
+ */
 export function selectStrategy(task = {}) {
     if (task.useUserBrowser || config.cdpUrl)
         return "cdp";
     if (task.interactive || task.multiStep)
         return "gateway";
-    return "hub-stealth";
+    return "webfetch";
 }
 /**
  * Resolve the preferred strategy to one that's actually available.
- * Cascades: gateway → cdp → hub-stealth → cli
+ *
+ * Cascade order:
+ *   webfetch → hub-stealth → cdp → gateway → cli
+ *
+ * Rationale:
+ *   - `webfetch` is a plain HTTP GET — instant, zero footprint.
+ *   - `hub-stealth` (playwright+stealth) handles JS-rendered pages
+ *     without a persistent browser process.
+ *   - `cdp` brings cookies/auth for login-walled sites.
+ *   - `gateway` exposes the multi-step HTTP API (ref-based ops, long
+ *     sessions) when the browse-server.cjs helper is available.
+ *   - `cli` (raw Playwright) is the last-resort fallback.
  */
 export async function resolveStrategy(preferred) {
     const chain = [];
-    // Build fallback chain starting from preferred
+    // Build fallback chain starting from preferred. webfetch and
+    // hub-stealth are always available (no external state check), so
+    // they're included as floor entries. CDP/gateway only get in if the
+    // caller asked for them explicitly, since they need running daemons.
     switch (preferred) {
+        case "webfetch":
+            chain.push("webfetch", "hub-stealth", "cli");
+            break;
         case "gateway":
-            chain.push("gateway", "cdp", "hub-stealth", "cli");
+            chain.push("gateway", "cdp", "hub-stealth", "webfetch", "cli");
             break;
         case "cdp":
-            chain.push("cdp", "hub-stealth", "cli");
+            chain.push("cdp", "hub-stealth", "webfetch", "cli");
             break;
         case "hub-stealth":
-            chain.push("hub-stealth", "cli");
+            chain.push("hub-stealth", "webfetch", "cli");
             break;
         case "cli":
             chain.push("cli");
@@ -84,6 +107,11 @@ export async function resolveStrategy(preferred) {
     }
     for (const strategy of chain) {
         switch (strategy) {
+            case "webfetch":
+                // Native fetch is always present on Node ≥ 18 — no availability
+                // probe needed. Each call is self-contained, so we return the
+                // strategy tag and let navigate() handle per-call errors.
+                return "webfetch";
             case "gateway":
                 if (isGatewayScriptPresent() && (await isGatewayRunning()))
                     return "gateway";
@@ -202,11 +230,55 @@ async function ensureGateway() {
     return false;
 }
 // ── Unified Operations ───────────────────────────────────────────────
-/** Navigate to URL using best available strategy */
+/** Navigate to URL using best available strategy.
+ *
+ *  Error-based cascade: if the chosen tier throws, we walk DOWN the
+ *  priority chain until one succeeds or we exhaust the list. This lets
+ *  a 403 from webfetch transparently upgrade to hub-stealth without
+ *  callers having to know about the fallback graph.
+ */
 export async function navigate(url, task = {}) {
-    const strategy = await resolveStrategy(selectStrategy(task));
-    log(`navigate(${url}) using strategy: ${strategy}`);
+    const primary = await resolveStrategy(selectStrategy(task));
+    log(`navigate(${url}) using strategy: ${primary}`);
+    // Try primary, then hub-stealth as a universal fallback. We keep the
+    // fallback list short here to avoid cascading timeouts — the full
+    // cascade is only for resolveStrategy's availability check.
+    const attempt = async (strategy) => {
+        return navigateOne(strategy, url);
+    };
+    try {
+        return await attempt(primary);
+    }
+    catch (err) {
+        log(`navigate(${url}) ${primary} failed: ${err.message}`);
+        if (primary === "webfetch") {
+            // Webfetch is the most common tier and the most common to hit a
+            // bot guard — cascade to hub-stealth explicitly, then cli.
+            try {
+                return await attempt("hub-stealth");
+            }
+            catch (err2) {
+                log(`navigate(${url}) hub-stealth fallback failed: ${err2.message}`);
+                return await attempt("cli");
+            }
+        }
+        throw err;
+    }
+}
+/** Single-strategy navigate — no fallback logic, just do the thing. */
+async function navigateOne(strategy, url) {
     switch (strategy) {
+        case "webfetch": {
+            try {
+                const r = await webfetchNavigate(url);
+                return { title: r.title, url: r.url };
+            }
+            catch (err) {
+                if (err instanceof WebfetchFailed)
+                    throw err;
+                throw new WebfetchFailed(url, err.message, { cause: err });
+            }
+        }
         case "gateway": {
             await ensureGateway();
             return gatewayRequest("/navigate", { url });

package/dist/services/browser-webfetch.js

@@ -0,0 +1,93 @@
+/**
+ * WebFetch — Tier 0 of the browser fallback chain.
+ *
+ * For URLs that don't need JavaScript, cookies, or a real browser —
+ * RSS feeds, JSON APIs, static HTML, OG-tag sniffs — a plain `fetch()`
+ * is 100× faster than spinning up Playwright and never shows up in
+ * bot-detection traffic. When this tier fails (4xx, 5xx, JS-heavy
+ * page, certificate error), callers should catch `WebfetchFailed`
+ * and cascade to the next tier (hub-stealth → cdp → gateway).
+ *
+ * See browser-manager.ts for the full cascade; this module is the
+ * leaf-level primitive with no dependencies on that file so both can
+ * be unit-tested in isolation.
+ */
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15 " +
+    "(KHTML, like Gecko) Version/17.0 Safari/605.1.15 AlvinBot/webfetch";
+export class WebfetchFailed extends Error {
+    status;
+    url;
+    cause;
+    constructor(url, message, opts = {}) {
+        super(`webfetch(${url}): ${message}`);
+        this.name = "WebfetchFailed";
+        this.url = url;
+        this.status = opts.status;
+        this.cause = opts.cause;
+    }
+}
+const ENTITY_MAP = {
+    "&": "&",
+    """: '"',
+    "'": "'",
+    "'": "'",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&nbsp;": " ",
+};
+function decodeEntities(s) {
+    return s.replace(/&(amp|quot|#39|apos|lt|gt|nbsp);/gi, (m) => ENTITY_MAP[m.toLowerCase()] ?? m);
+}
+/**
+ * Return the contents of the first `<title>` tag, normalised:
+ * whitespace collapsed, common HTML entities decoded. If there's no
+ * `<title>` at all, returns the empty string — callers decide what to
+ * do with that (the URL is a reasonable default display value).
+ */
+export function parseTitle(html) {
+    const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (!match)
+        return "";
+    const inner = match[1].replace(/\s+/g, " ").trim();
+    return decodeEntities(inner);
+}
+export async function webfetchNavigate(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "GET",
+                headers: {
+                    "User-Agent": options.userAgent ?? DEFAULT_USER_AGENT,
+                    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                },
+                redirect: "follow",
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new WebfetchFailed(url, err.message, { cause: err });
+        }
+        if (!response.ok) {
+            throw new WebfetchFailed(url, `HTTP ${response.status}`, { status: response.status });
+        }
+        const contentType = response.headers.get("content-type") || "";
+        const isHtml = /text\/html|application\/xhtml\+xml/i.test(contentType);
+        if (options.forceHtml && !isHtml) {
+            throw new WebfetchFailed(url, `expected HTML, got ${contentType || "unknown"}`, { status: response.status });
+        }
+        const body = await response.text();
+        const title = parseTitle(body);
+        return {
+            title: title || url,
+            url,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/services/cron-scheduling.js

@@ -0,0 +1,142 @@
+/**
+ * Pure scheduling helpers for the cron service.
+ *
+ * Extracted from cron.ts so the startup-catchup and pre-execution state
+ * updates can be unit-tested without booting the full scheduler loop.
+ * This module is side-effect-free: it does not touch the filesystem, the
+ * clock, or the sub-agent registry. Give it jobs + a `now` value and it
+ * returns what the next state should look like.
+ *
+ * Background — see test/cron-restart-resilience.test.ts for the exact
+ * contract and the regression it closes.
+ */
+// ── Pure parsers ────────────────────────────────────────────
+//
+// These mirror parseInterval / nextCronRun from cron.ts. We duplicate them
+// intentionally instead of importing — cron.ts is the scheduler-with-side-
+// effects, and importing it from a "pure" helper would reintroduce the
+// circular dependency we just broke. The duplication is small and well
+// covered by tests; keep the two in sync when editing.
+function parseInterval(input) {
+    const match = input.match(/^(\d+(?:\.\d+)?)\s*(s|sec|m|min|h|hr|d|day)s?$/i);
+    if (!match)
+        return null;
+    const value = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    const mult = {
+        s: 1000, sec: 1000, m: 60_000, min: 60_000,
+        h: 3_600_000, hr: 3_600_000, d: 86_400_000, day: 86_400_000,
+    };
+    return value * (mult[unit] || 60_000);
+}
+function nextCronRun(expression, after) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const [minExpr, hourExpr, dayExpr, monthExpr, weekdayExpr] = parts;
+    function parseField(expr, min, max) {
+        if (expr === "*")
+            return Array.from({ length: max - min + 1 }, (_, i) => i + min);
+        if (expr.includes("/")) {
+            const [, step] = expr.split("/");
+            const s = parseInt(step);
+            return Array.from({ length: max - min + 1 }, (_, i) => i + min).filter((v) => v % s === 0);
+        }
+        if (expr.includes(","))
+            return expr.split(",").map(Number);
+        if (expr.includes("-")) {
+            const [a, b] = expr.split("-").map(Number);
+            return Array.from({ length: b - a + 1 }, (_, i) => i + a);
+        }
+        return [parseInt(expr)];
+    }
+    const minutes = parseField(minExpr, 0, 59);
+    const hours = parseField(hourExpr, 0, 23);
+    const days = parseField(dayExpr, 1, 31);
+    const months = parseField(monthExpr, 1, 12);
+    const weekdays = parseField(weekdayExpr, 0, 6);
+    const candidate = new Date(after);
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1);
+    for (let i = 0; i < 366 * 24 * 60; i++) {
+        const m = candidate.getMinutes();
+        const h = candidate.getHours();
+        const d = candidate.getDate();
+        const mo = candidate.getMonth() + 1;
+        const wd = candidate.getDay();
+        if (minutes.includes(m) &&
+            hours.includes(h) &&
+            days.includes(d) &&
+            months.includes(mo) &&
+            weekdays.includes(wd)) {
+            return candidate;
+        }
+        candidate.setMinutes(candidate.getMinutes() + 1);
+    }
+    return null;
+}
+/** Compute the next run relative to an explicit base timestamp.
+ *  Used by prepareForExecution to make the interval calculation stable
+ *  even when `lastRunAt` is stale or null. */
+export function calculateNextRunFrom(job, base) {
+    if (!job.enabled)
+        return null;
+    const intervalMs = parseInterval(job.schedule);
+    if (intervalMs)
+        return base + intervalMs;
+    const next = nextCronRun(job.schedule, new Date(base));
+    return next ? next.getTime() : null;
+}
+// ── Pre-execution state update ─────────────────────────────
+/**
+ * Mark a job as "being attempted" and advance `nextRunAt` to the next
+ * regular trigger, pure-functionally. Returns a NEW job object.
+ *
+ * Why not set `nextRunAt = null`: if the bot crashes between this call
+ * and the post-execution save, we still know when the next regular run
+ * is — the scheduler simply won't re-trigger. The `lastAttemptAt >
+ * lastRunAt` asymmetry is then the signal for handleStartupCatchup to
+ * nachholen the current attempt on the next boot.
+ */
+export function prepareForExecution(job, now) {
+    return {
+        ...job,
+        lastAttemptAt: now,
+        nextRunAt: calculateNextRunFrom(job, now),
+    };
+}
+// ── Startup catch-up ───────────────────────────────────────
+/** Default grace window for catching up an interrupted attempt on boot. */
+export const DEFAULT_CATCHUP_GRACE_MS = 6 * 60 * 60 * 1000; // 6 h
+/**
+ * Rewind `nextRunAt` to `now` for every enabled job whose most recent
+ * attempt never completed AND is still inside the grace window. This
+ * makes the very next scheduler tick pick the job up again, without
+ * double-firing jobs that actually finished.
+ *
+ * Jobs whose crashed attempt is older than the grace window are NOT
+ * caught up — the assumption is that such a run is too stale to be
+ * meaningful (a "daily" run from yesterday isn't what the user wants
+ * at 2pm today). Those jobs keep their scheduled future nextRunAt.
+ *
+ * PURE: returns a fresh array, never mutates the input.
+ */
+export function handleStartupCatchup(jobs, now, graceMs = DEFAULT_CATCHUP_GRACE_MS) {
+    return jobs.map((job) => {
+        if (!job.enabled)
+            return job;
+        if (!job.lastAttemptAt)
+            return job;
+        const completed = typeof job.lastRunAt === "number" &&
+            job.lastRunAt >= job.lastAttemptAt;
+        if (completed)
+            return job;
+        const ageMs = now - job.lastAttemptAt;
+        if (ageMs <= 0)
+            return job; // clock weirdness — skip
+        if (ageMs > graceMs)
+            return job; // outside grace — give up
+        // Within grace, never completed → catch up on next tick.
+        return { ...job, nextRunAt: now };
+    });
+}