alvin-bot 4.8.9 → 4.9.1

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.9.1] — 2026-04-11
+
+### 🐛 `/cron run <name>` accepts the job name, not just the opaque ID
+
+Reported via screenshot: `/cron run Daily Job Alert` replied with `❌ Job not found.` because `runJobNow(id)` only matched against `job.id` — the random base-36 string (`mn90rrsndzto`) that nobody types. Worse, when Claude tried to trigger the same job through a natural-language request in an earlier session, it retried with different variants until one happened to succeed — and the absence of a re-entry guard in `runJobNow` meant the retries sometimes spawned a second parallel sub-agent, producing the "ups… wurde doppelt ausgeführt" message.
+
+**Fix — pure resolver + guard, wired into the public API:**
+
+- **`src/services/cron-resolver.ts` (new).** Two pure helpers:
+  - `resolveJobByNameOrId(jobs, query)` — priority: exact ID > exact name > unique case-insensitive name > `null` on miss/ambiguous.
+  - `runJobNowGuard(id, isRunning, run)` — higher-order re-entry check, testable without the scheduler loop.
+- **`src/services/cron.ts` runJobNow**. Now returns a typed outcome (`not-found` | `already-running` | `ran`), consults the `runningJobs` set (previously only the scheduler loop did), and — when it actually runs — persists `lastAttemptAt` / `lastRunAt` / `runCount` / `lastResult` / `lastError` exactly like the scheduler path, so manual triggers show up in the timeline instead of vanishing.
+- **`src/handlers/commands.ts /cron run`**. Matches against name OR ID, prints a helpful "Available:" list on miss, and announces the already-running case instead of silently double-firing.
+- **10 new tests** (`test/cron-run-resolver.test.ts`) covering exact ID, exact name, case-insensitive, trimmed input, miss, ambiguity, ID-over-name preference, and both guard branches. **164 tests total.**
+
+**What this also quietly fixes:** natural-language triggers ("Alvin, run the daily job alert"). When Claude invokes `/cron run Daily Job Alert` via its own turn, the command now succeeds on the first try — no retry cascade, no double execution.
+
+## [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/commands.js

@@ -1441,17 +1441,28 @@ export function registerCommands(bot) {
             }
             return;
         }
-        // /cron run <id>
+        // /cron run <name-or-id>
         if (arg.startsWith("run ")) {
-            const id = arg.slice(4).trim();
+            const nameOrId = arg.slice(4).trim();
             await ctx.api.sendChatAction(ctx.chat.id, "typing");
-            const result = await (runJobNow(id) || Promise.resolve(null));
-            if (!result) {
-                await ctx.reply(`❌ Job not found.`);
+            const outcome = await runJobNow(nameOrId);
+            if (outcome.status === "not-found") {
+                const jobs = listJobs();
+                const hint = jobs.length > 0
+                    ? `\n\nAvailable:\n${jobs.slice(0, 10).map(j => `• ${j.name}`).join("\n")}`
+                    : "";
+                await ctx.reply(`❌ No job matches <code>${nameOrId}</code>.${hint}`, { parse_mode: "HTML" });
+                return;
+            }
+            if (outcome.status === "already-running") {
+                await ctx.reply(`⏳ Job "${outcome.job.name}" is already running — not starting a duplicate. ` +
+                    `Wait for the current run to finish, or /subagents cancel to abort it.`);
                 return;
             }
-            const output = result.output ? `\`\`\`\n${result.output.slice(0, 2000)}\n\`\`\`` : "(no output)";
-            await ctx.reply(`🔧 Job executed:\n${output}${result.error ? `\n\n❌ ${result.error}` : ""}`, { parse_mode: "Markdown" });
+            const output = outcome.output
+                ? `\`\`\`\n${outcome.output.slice(0, 2000)}\n\`\`\``
+                : "(no output)";
+            await ctx.reply(`🔧 Job "${outcome.job.name}" executed:\n${output}${outcome.error ? `\n\n❌ ${outcome.error}` : ""}`, { parse_mode: "Markdown" });
             return;
         }
         await ctx.reply("Unknown cron command. Use /cron for help.");

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-resolver.js

@@ -0,0 +1,58 @@
+/**
+ * Pure cron-job name/ID resolver and re-entry guard.
+ *
+ * See test/cron-run-resolver.test.ts for the regressions this closes:
+ *   - `/cron run Daily Job Alert` returned "Job not found" because the
+ *     old runJobNow only matched on `job.id`. Real IDs are random
+ *     base-36 strings, nobody types those.
+ *   - Natural-language triggers double-ran jobs because runJobNow
+ *     didn't consult the `runningJobs` set.
+ *
+ * Both helpers are pure (or pure-over-callbacks) so they can be unit-
+ * tested without touching the filesystem or the scheduler loop.
+ */
+/**
+ * Resolve a user-facing query (name, case-insensitive name, or ID) to
+ * a specific job. Priority:
+ *   1. Exact ID match
+ *   2. Exact name match (case-sensitive)
+ *   3. Unique case-insensitive name match
+ *   4. null (miss or ambiguous)
+ *
+ * Trimmed whitespace on the query. Never mutates the input array.
+ */
+export function resolveJobByNameOrId(jobs, query) {
+    const q = query.trim();
+    if (!q)
+        return null;
+    // 1. Exact ID match
+    const byId = jobs.find((j) => j.id === q);
+    if (byId)
+        return byId;
+    // 2. Exact name match
+    const byExactName = jobs.find((j) => j.name === q);
+    if (byExactName)
+        return byExactName;
+    // 3. Unique case-insensitive name match
+    const qLower = q.toLowerCase();
+    const ciMatches = jobs.filter((j) => j.name.toLowerCase() === qLower);
+    if (ciMatches.length === 1)
+        return ciMatches[0];
+    // 4. Ambiguous or not found
+    return null;
+}
+/**
+ * Re-entry guard for runJobNow: only calls `run` when `isRunning`
+ * reports the job is idle. Otherwise reports back "already-running"
+ * so the caller can tell the user instead of silently double-firing.
+ *
+ * Kept as a higher-order function so the test doesn't need to stand
+ * up the whole cron loop — we mock the two callbacks.
+ */
+export async function runJobNowGuard(id, isRunning, run) {
+    if (isRunning(id)) {
+        return { status: "already-running" };
+    }
+    const result = await run(id);
+    return { status: "ran", output: result.output, error: result.error };
+}