alvin-bot 4.9.0 → 4.9.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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

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/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 };
+}

package/dist/services/cron.js

@@ -14,6 +14,7 @@ import { execSync } from "child_process";
 import { dirname } from "path";
 import { CRON_FILE, BOT_ROOT } from "../paths.js";
 import { prepareForExecution, handleStartupCatchup, calculateNextRunFrom, } from "./cron-scheduling.js";
+import { resolveJobByNameOrId } from "./cron-resolver.js";
 // ── Storage ─────────────────────────────────────────────
 function loadJobs() {
     try {
@@ -391,11 +392,44 @@ export function toggleJob(id) {
     saveJobs(jobs);
     return job;
 }
-export function runJobNow(id) {
-    const job = getJob(id);
+/**
+ * Manual /cron run — resolves `nameOrId` against the job list, then
+ * executes the job while honouring the in-memory `runningJobs` guard
+ * so a simultaneous scheduler-trigger can't overlap.
+ */
+export async function runJobNow(nameOrId) {
+    const job = resolveJobByNameOrId(loadJobs(), nameOrId);
     if (!job)
-        return null;
-    return executeJob(job);
+        return { status: "not-found" };
+    if (runningJobs.has(job.id)) {
+        return { status: "already-running", job };
+    }
+    runningJobs.add(job.id);
+    try {
+        const result = await executeJob(job);
+        // Persist the manual run the same way the scheduler does so the
+        // timeline stays honest: lastAttemptAt + lastRunAt + runCount bump.
+        try {
+            const freshJobs = loadJobs();
+            const freshJob = freshJobs.find((j) => j.id === job.id);
+            if (freshJob) {
+                const now = Date.now();
+                freshJob.lastAttemptAt = now;
+                freshJob.lastRunAt = now;
+                freshJob.lastResult = result.output.slice(0, 4000);
+                freshJob.lastError = result.error || null;
+                freshJob.runCount++;
+                saveJobs(freshJobs);
+            }
+        }
+        catch (err) {
+            console.error("[cron] failed to persist manual run state:", err);
+        }
+        return { status: "ran", job, output: result.output, error: result.error };
+    }
+    finally {
+        runningJobs.delete(job.id);
+    }
 }
 /**
  * Convert a cron expression or interval string to a human-readable German description.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/cron-run-resolver.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Fix #13 — `/cron run` must resolve a job by name OR ID, and must
+ * reject a second concurrent run of the same job.
+ *
+ * Regressions this closes:
+ *   (a) `/cron run Daily Job Alert` returned "❌ Job not found."
+ *       because runJobNow() only matched against `job.id`. Real job
+ *       IDs look like `mn90rrsndzto` — nobody types those.
+ *   (b) Natural-language triggers through Claude ended up running the
+ *       job twice because the main message handler retried after the
+ *       first "Job not found" / parallel path succeeded. runJobNow()
+ *       didn't consult `runningJobs`, so two concurrent calls both
+ *       spawned sub-agents.
+ *
+ * Contract — pure resolver (tested here), side-effectful runner
+ * (integration-tested via runJobNowGuard below):
+ *
+ *   resolveJobByNameOrId(jobs, query)
+ *     - exact `job.id` match wins
+ *     - exact `job.name` match wins next
+ *     - case-insensitive `job.name` match third
+ *     - returns `null` on ambiguous case-insensitive match or miss
+ *
+ *   runJobNowGuard(id, isRunning, run)
+ *     - calls `run(id)` only when `isRunning(id)` is false
+ *     - returns `{ status: "already-running" }` otherwise
+ */
+import { describe, it, expect, vi } from "vitest";
+import {
+  resolveJobByNameOrId,
+  runJobNowGuard,
+} from "../src/services/cron-resolver.js";
+import type { CronJob } from "../src/services/cron.js";
+
+function makeJob(overrides: Partial<CronJob>): CronJob {
+  return {
+    id: "abc123",
+    name: "Test Job",
+    type: "ai-query",
+    schedule: "0 8 * * *",
+    oneShot: false,
+    payload: { prompt: "x" },
+    target: { platform: "telegram", chatId: "1" },
+    enabled: true,
+    createdAt: 0,
+    lastRunAt: null,
+    lastResult: null,
+    lastError: null,
+    nextRunAt: null,
+    runCount: 0,
+    createdBy: "test",
+    ...overrides,
+  };
+}
+
+describe("resolveJobByNameOrId (Fix #13)", () => {
+  const jobs = [
+    makeJob({ id: "mn90rrsndzto", name: "Daily Job Alert" }),
+    makeJob({ id: "abc123", name: "Weekly Stock Report" }),
+    makeJob({ id: "def456", name: "Perseus Health Check" }),
+  ];
+
+  it("matches by exact ID", () => {
+    const j = resolveJobByNameOrId(jobs, "mn90rrsndzto");
+    expect(j?.name).toBe("Daily Job Alert");
+  });
+
+  it("matches by exact name", () => {
+    const j = resolveJobByNameOrId(jobs, "Daily Job Alert");
+    expect(j?.id).toBe("mn90rrsndzto");
+  });
+
+  it("matches case-insensitive on name", () => {
+    const j = resolveJobByNameOrId(jobs, "daily job alert");
+    expect(j?.id).toBe("mn90rrsndzto");
+  });
+
+  it("matches trimmed input", () => {
+    const j = resolveJobByNameOrId(jobs, "  Daily Job Alert  ");
+    expect(j?.id).toBe("mn90rrsndzto");
+  });
+
+  it("returns null on miss", () => {
+    expect(resolveJobByNameOrId(jobs, "Nothing Like That")).toBeNull();
+  });
+
+  it("returns null on ambiguous case-insensitive match", () => {
+    const dupes = [
+      makeJob({ id: "a", name: "test job" }),
+      makeJob({ id: "b", name: "Test Job" }),
+      makeJob({ id: "c", name: "TEST JOB" }),
+    ];
+    // Exact-case match wins over ambiguous siblings
+    expect(resolveJobByNameOrId(dupes, "Test Job")?.id).toBe("b");
+    // Ambiguous query (no exact-case match) returns null
+    expect(resolveJobByNameOrId(dupes, "TeSt JoB")).toBeNull();
+  });
+
+  it("prefers ID match over an accidental name collision", () => {
+    const collision = [
+      makeJob({ id: "Daily Job Alert", name: "Something Else" }),
+      makeJob({ id: "mn90rrsndzto", name: "Daily Job Alert" }),
+    ];
+    const j = resolveJobByNameOrId(collision, "Daily Job Alert");
+    expect(j?.id).toBe("Daily Job Alert"); // ID match wins
+  });
+});
+
+describe("runJobNowGuard (Fix #13)", () => {
+  it("runs when the job is not already running", async () => {
+    const run = vi.fn(async () => ({ output: "ok" }));
+    const result = await runJobNowGuard("job-1", () => false, run);
+    expect(run).toHaveBeenCalledWith("job-1");
+    expect(result.status).toBe("ran");
+  });
+
+  it("rejects when the job is already running", async () => {
+    const run = vi.fn(async () => ({ output: "ok" }));
+    const result = await runJobNowGuard("job-1", () => true, run);
+    expect(run).not.toHaveBeenCalled();
+    expect(result.status).toBe("already-running");
+  });
+
+  it("passes through the inner result on the ran path", async () => {
+    const run = vi.fn(async () => ({ output: "done", error: undefined }));
+    const result = await runJobNowGuard("job-1", () => false, run);
+    if (result.status === "ran") {
+      expect(result.output).toBe("done");
+    } else {
+      throw new Error("expected ran");
+    }
+  });
+});