alvin-bot 4.8.9 → 4.9.0

package/dist/util/debounce.js

@@ -0,0 +1,24 @@
+/**
+ * Trailing-edge debounce. Delays `fn` until `waitMs` has elapsed since
+ * the most recent call. Coalesces bursts into a single invocation with
+ * the most recent arguments.
+ *
+ * Used by fs.watch consumers (skills, plugins) where macOS FSEvents
+ * delivers many duplicate events for a single logical change.
+ */
+export function debounce(fn, waitMs) {
+    let timer = null;
+    let lastArgs = null;
+    return function debounced(...args) {
+        lastArgs = args;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            const call = lastArgs;
+            lastArgs = null;
+            if (call)
+                fn(...call);
+        }, waitMs);
+    };
+}

package/dist/util/telegram-error-filter.js

@@ -0,0 +1,62 @@
+/**
+ * Telegram error filter — single source of truth for "which grammy
+ * errors are harmless and should never reach the end user as a
+ * 'Fehler: ...' reply."
+ *
+ * Context: grammy's Bot API wrapper surfaces these as plain Error
+ * objects with the description baked into `.message`. Some call sites
+ * (live-stream edit races, callback-answer races after a modal was
+ * already dismissed, message-to-edit-gone races when the user just
+ * deleted the message) produce errors that are 100% benign — they
+ * just mean the UI state we were about to write is already there.
+ *
+ * This file centralises the list so we can update one regex and have
+ * the filter apply everywhere. Used by bot.catch(), by the streaming
+ * `telegram.ts` finalize path, by handlers/message.ts, and by any
+ * future caller that needs to decide "report this to the user or
+ * drop it silently."
+ */
+const HARMLESS_PATTERNS = [
+    // The big one — live-stream edit races
+    /message is not modified/i,
+    /specified new message content and reply markup are exactly the same/i,
+    // Callback-answer race: the user tapped a stale inline button
+    /query is too old and response timeout expired/i,
+    /query ID is invalid/i,
+    // The user deleted the message we were about to edit
+    /message to edit not found/i,
+    /message to delete not found/i,
+    /MESSAGE_ID_INVALID/i,
+];
+/**
+ * True if the error is one of the known-harmless Telegram races.
+ * Accepts Error objects, grammy's GrammyError (which has an additional
+ * `description` field), and plain strings. `null` / `undefined` return
+ * false so callers can use this directly in catch blocks.
+ */
+export function isHarmlessTelegramError(err) {
+    if (err === null || err === undefined)
+        return false;
+    let haystack = "";
+    if (typeof err === "string") {
+        haystack = err;
+    }
+    else if (err instanceof Error) {
+        haystack = err.message || "";
+        // grammy's GrammyError carries the server's reason on .description
+        const desc = err.description;
+        if (typeof desc === "string")
+            haystack += " " + desc;
+    }
+    else if (typeof err === "object") {
+        // Plain object — look for message/description fields
+        const obj = err;
+        if (typeof obj.message === "string")
+            haystack += obj.message;
+        if (typeof obj.description === "string")
+            haystack += " " + obj.description;
+    }
+    if (!haystack)
+        return false;
+    return HARMLESS_PATTERNS.some((re) => re.test(haystack));
+}

package/dist/web/server.js

@@ -31,6 +31,9 @@ import { BOT_ROOT, ENV_FILE, PUBLIC_DIR, MEMORY_DIR, MEMORY_FILE, SOUL_FILE, DAT
 import { broadcast } from "../services/broadcast.js";
 import { BOT_VERSION } from "../version.js";
 const WEB_PORT = parseInt(process.env.WEB_PORT || "3100");
+/** Module-scope reference to the WebSocket server so stopWebServer() can
+ *  tear it down together with the HTTP server. Set inside startWebServer(). */
+let wsServerRef = null;
 const WEB_PASSWORD = process.env.WEB_PASSWORD || "";
 /** The actual port the Web UI is running on (may differ from WEB_PORT if busy). */
 let actualWebPort = WEB_PORT;
@@ -1426,6 +1429,7 @@ export function startWebServer() {
         });
     });
     const wss = new WebSocketServer({ server });
+    wsServerRef = wss;
     handleWebSocket(wss);
     // Smart port: try WEB_PORT, increment if busy (up to +20)
     const MAX_TRIES = 20;
@@ -1449,6 +1453,58 @@ export function startWebServer() {
     tryListen(WEB_PORT);
     return server;
 }
+/**
+ * Gracefully stop the web server so the port is released.
+ *
+ * Why this exists: `shutdown()` in src/index.ts used to stop grammy and the
+ * scheduler but leave the HTTP server listening. macOS then held the
+ * listening socket in the socket table, so launchd's next boot of the bot
+ * hit `EADDRINUSE :::3100`, threw an Uncaught exception and crash-looped.
+ *
+ * What this does:
+ *   1. Force-close idle keep-alive sockets (otherwise close() hangs on them).
+ *   2. Force-close active open requests (long-poll clients, WebSocket
+ *      upgrades that never completed).
+ *   3. Tear down the WebSocket server so its own sockets don't linger.
+ *   4. Await `server.close()` so the listening socket is truly released
+ *      before the caller's shutdown continues.
+ *
+ * Safe to call multiple times; no-op when the server is already closed or
+ * never listened. Never throws.
+ */
+export async function stopWebServer(server) {
+    try {
+        if (wsServerRef) {
+            for (const client of wsServerRef.clients) {
+                try {
+                    client.terminate();
+                }
+                catch { /* ignore */ }
+            }
+            await new Promise((resolve) => wsServerRef.close(() => resolve()));
+            wsServerRef = null;
+        }
+    }
+    catch { /* ignore */ }
+    if (!server.listening)
+        return;
+    try {
+        // Node 18.2+ APIs — break any keep-alive / long-poll stalls so
+        // server.close() can actually resolve.
+        const s = server;
+        if (typeof s.closeIdleConnections === "function")
+            s.closeIdleConnections();
+        if (typeof s.closeAllConnections === "function")
+            s.closeAllConnections();
+    }
+    catch { /* ignore */ }
+    await new Promise((resolve) => {
+        // close() callback fires with an Error arg when the server wasn't
+        // listening — we just resolve in either case. The caller only cares
+        // that the port is free when this awaits.
+        server.close(() => resolve());
+    });
+}
 /** Get the actual port the Web UI is running on. */
 export function getWebPort() {
     return actualWebPort;

package/package.json

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

package/test/browser-webfetch.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Fix #11 (minimal) — webfetch Tier 0 for browser-manager.
+ *
+ * Background: the current browser fallback chain is
+ *   gateway → cdp → hub-stealth → cli
+ * Every tier spawns playwright (or talks to a CDP-controlled Chrome),
+ * which is slow and occasionally impossible under load. Many scraping
+ * tasks only need plain HTTP — an RSS feed, a JSON API, an OG meta-
+ * tag sniff. For those, Node's native `fetch` is 100× faster and
+ * doesn't need a browser at all.
+ *
+ * Contract: `webfetchNavigate(url)` returns `{ title, url }` for a
+ * successful GET, or throws a distinct `WebfetchFailed` error that the
+ * cascade can catch and fall through to the next tier. Title is the
+ * first `<title>` tag content; if none, the URL is returned.
+ *
+ * Keep it small — this is a Tier 0 helper, not a full scraper.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  webfetchNavigate,
+  WebfetchFailed,
+  parseTitle,
+} from "../src/services/browser-webfetch.js";
+
+describe("parseTitle (Fix #11)", () => {
+  it("extracts a simple <title>", () => {
+    expect(parseTitle("<html><head><title>Hello World</title></head></html>")).toBe("Hello World");
+  });
+
+  it("handles whitespace and newlines", () => {
+    expect(parseTitle("<title>\n  Multi  line  \n</title>")).toBe("Multi line");
+  });
+
+  it("returns empty string when there's no title", () => {
+    expect(parseTitle("<html><body>no title</body></html>")).toBe("");
+  });
+
+  it("decodes basic HTML entities", () => {
+    expect(parseTitle("<title>A &amp; B</title>")).toBe("A & B");
+    expect(parseTitle("<title>&quot;quoted&quot;</title>")).toBe('"quoted"');
+  });
+
+  it("is case-insensitive for the tag name", () => {
+    expect(parseTitle("<HEAD><TITLE>Foo</TITLE></HEAD>")).toBe("Foo");
+  });
+});
+
+describe("webfetchNavigate (Fix #11)", () => {
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns title + url on a 200 response", async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        "<html><head><title>GitHub · alvbln/alvin-bot</title></head></html>",
+        { status: 200, headers: { "content-type": "text/html" } },
+      ),
+    ) as unknown as typeof fetch;
+
+    const result = await webfetchNavigate("https://github.com/alvbln/alvin-bot");
+    expect(result.title).toBe("GitHub · alvbln/alvin-bot");
+    expect(result.url).toBe("https://github.com/alvbln/alvin-bot");
+  });
+
+  it("throws WebfetchFailed with the HTTP status on 4xx/5xx", async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response("blocked", { status: 403 }),
+    ) as unknown as typeof fetch;
+
+    await expect(webfetchNavigate("https://example.com")).rejects.toThrow(WebfetchFailed);
+    try {
+      await webfetchNavigate("https://example.com");
+    } catch (err) {
+      expect((err as WebfetchFailed).status).toBe(403);
+    }
+  });
+
+  it("throws WebfetchFailed when the response is not HTML and forceHtml=true", async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response('{"json":true}', {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    ) as unknown as typeof fetch;
+
+    await expect(
+      webfetchNavigate("https://api.example.com/data", { forceHtml: true }),
+    ).rejects.toThrow(WebfetchFailed);
+  });
+
+  it("accepts non-HTML responses when forceHtml is false (default)", async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response("plain text", {
+        status: 200,
+        headers: { "content-type": "text/plain" },
+      }),
+    ) as unknown as typeof fetch;
+
+    const result = await webfetchNavigate("https://example.com/raw");
+    // No <title> in plain text → falls back to URL as display title
+    expect(result.url).toBe("https://example.com/raw");
+    expect(result.title).toBe("https://example.com/raw");
+  });
+
+  it("wraps network errors in WebfetchFailed so the cascade can catch a single type", async () => {
+    globalThis.fetch = vi.fn(async () => {
+      throw new Error("getaddrinfo ENOTFOUND nonexistent.invalid");
+    }) as unknown as typeof fetch;
+
+    await expect(
+      webfetchNavigate("https://nonexistent.invalid/"),
+    ).rejects.toThrow(WebfetchFailed);
+  });
+});

package/test/console-timestamps.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Fix #10 — console output must carry ISO timestamps so out.log / err.log
+ * are actually debuggable. Also: silence libsignal's "Closing session"
+ * SessionEntry dumps which were pushing tens of KB per day into the logs
+ * and making forensic work painful.
+ *
+ * Contract: `installConsoleFormatter(console)` wraps console.log /
+ * console.warn / console.error so every line is prefixed with the
+ * current ISO timestamp (zero-padded, UTC), and certain noise patterns
+ * (libsignal session dumps) are dropped entirely.
+ *
+ * The wrapper is idempotent — calling it twice is a no-op.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  installConsoleFormatter,
+  uninstallConsoleFormatter,
+  isNoisyLine,
+} from "../src/util/console-formatter.js";
+
+describe("installConsoleFormatter (Fix #10)", () => {
+  let stdoutWrites: string[];
+  let stderrWrites: string[];
+  let origStdout: typeof process.stdout.write;
+  let origStderr: typeof process.stderr.write;
+
+  beforeEach(() => {
+    stdoutWrites = [];
+    stderrWrites = [];
+    origStdout = process.stdout.write.bind(process.stdout);
+    origStderr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = ((chunk: unknown) => {
+      stdoutWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+    process.stderr.write = ((chunk: unknown) => {
+      stderrWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+  });
+
+  afterEach(() => {
+    uninstallConsoleFormatter();
+    process.stdout.write = origStdout;
+    process.stderr.write = origStderr;
+  });
+
+  it("prefixes console.log output with an ISO timestamp", () => {
+    installConsoleFormatter();
+    console.log("hello world");
+    const line = stdoutWrites.join("");
+    // ISO format like 2026-04-11T14:00:00.000Z
+    expect(line).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\s+hello world/);
+  });
+
+  it("prefixes console.error output with an ISO timestamp", () => {
+    installConsoleFormatter();
+    console.error("boom");
+    const line = stderrWrites.join("");
+    expect(line).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\s+boom/);
+  });
+
+  it("is idempotent — second install call does not double-prefix", () => {
+    installConsoleFormatter();
+    installConsoleFormatter();
+    console.log("once");
+    const line = stdoutWrites.join("");
+    // Exactly one ISO timestamp, not two
+    const matches = line.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/g);
+    expect(matches).not.toBeNull();
+    expect(matches!.length).toBe(1);
+  });
+});
+
+describe("isNoisyLine (Fix #10)", () => {
+  it("treats libsignal session dumps as noise", () => {
+    const dump = `Closing session: SessionEntry {
+  _chains: {
+    'BUQxzJlwgVTCxCL5C4rTbZP/7a0ciMPnyo47Pwr4flJt': { chainKey: [Object], chainType: 1, messageKeys: {} }
+  },
+  registrationId: 1446528770`;
+    expect(isNoisyLine(dump)).toBe(true);
+  });
+
+  it("treats the one-line 'Closing open session' as noise", () => {
+    expect(isNoisyLine("Closing open session in favor of incoming prekey bundle")).toBe(true);
+  });
+
+  it("treats the repetitive claude native binary banner as noise", () => {
+    expect(isNoisyLine("[claude] Native binary: /Users/foo/.local/share/claude/versions/2.1.101")).toBe(true);
+  });
+
+  it("does NOT silence normal log output", () => {
+    expect(isNoisyLine("⏰ Cron scheduler started (30s interval)")).toBe(false);
+    expect(isNoisyLine("[watchdog] started — beacon every 30s")).toBe(false);
+    expect(isNoisyLine("Cron: Running job \"Daily Job Alert\"")).toBe(false);
+  });
+});

package/test/cron-restart-resilience.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Fix #3 — Cron scheduler must survive a bot restart during job execution.
+ *
+ * Background: the old scheduler set `nextRunAt = null` immediately before
+ * `await executeJob(job)` and only re-calculated it after completion. A
+ * crash mid-execution (EADDRINUSE, unhandled rejection, launchd restart)
+ * left `nextRunAt = null`, so the next boot called `calculateNextRun()`
+ * from the current time — which for a cron expression always yields a
+ * FUTURE trigger (e.g. tomorrow 08:00). Today's run was lost forever.
+ *
+ * New contract (pure-function pair):
+ *
+ *   prepareForExecution(job, now)
+ *     - updates lastAttemptAt = now
+ *     - updates nextRunAt = <next regular trigger from `now`>
+ *     - returns the mutated job
+ *
+ *   handleStartupCatchup(jobs, now, graceMs)
+ *     - for every enabled job where `lastAttemptAt > lastRunAt`
+ *       (i.e. the last attempt never completed) AND the attempt is
+ *       within `graceMs`, rewinds `nextRunAt` to `now` so the next
+ *       scheduler tick picks it up immediately
+ *     - for every enabled job where `lastAttemptAt > lastRunAt` but
+ *       the attempt is older than `graceMs`, gives up and recalculates
+ *       `nextRunAt` normally
+ *     - never touches disabled jobs
+ *     - returns a NEW array of jobs (pure, no mutation of input)
+ */
+import { describe, it, expect } from "vitest";
+import {
+  prepareForExecution,
+  handleStartupCatchup,
+} from "../src/services/cron-scheduling.js";
+import type { CronJob } from "../src/services/cron.js";
+
+function makeJob(overrides: Partial<CronJob> = {}): CronJob {
+  return {
+    id: "job-1",
+    name: "Daily Job Alert",
+    type: "ai-query",
+    schedule: "00 08 * * *",
+    oneShot: false,
+    payload: { prompt: "x" },
+    target: { platform: "telegram", chatId: "1" },
+    enabled: true,
+    createdAt: 1_700_000_000_000,
+    lastRunAt: null,
+    lastResult: null,
+    lastError: null,
+    nextRunAt: null,
+    runCount: 0,
+    createdBy: "test",
+    ...overrides,
+  };
+}
+
+describe("prepareForExecution (Fix #3)", () => {
+  it("sets lastAttemptAt to now", () => {
+    const job = makeJob();
+    const now = 1_775_887_200_000; // 2026-04-11 08:00 Berlin
+    const updated = prepareForExecution(job, now);
+    expect(updated.lastAttemptAt).toBe(now);
+  });
+
+  it("advances nextRunAt to the NEXT regular trigger, not null", () => {
+    const job = makeJob({ schedule: "00 08 * * *" });
+    const now = 1_775_887_200_000; // today 08:00
+    const updated = prepareForExecution(job, now);
+    // nextRunAt must be a future timestamp, not null, not zero
+    expect(updated.nextRunAt).not.toBeNull();
+    expect(updated.nextRunAt!).toBeGreaterThan(now);
+  });
+
+  it("works with interval schedules — base = now, not lastRunAt", () => {
+    const job = makeJob({ schedule: "5m", lastRunAt: 1_000_000_000_000 });
+    const now = 1_775_887_200_000;
+    const updated = prepareForExecution(job, now);
+    expect(updated.nextRunAt).toBe(now + 5 * 60_000);
+  });
+
+  it("does not touch lastRunAt", () => {
+    const job = makeJob({ lastRunAt: 123 });
+    const updated = prepareForExecution(job, 9999);
+    expect(updated.lastRunAt).toBe(123);
+  });
+
+  it("is pure — returns a new object, leaves the input alone", () => {
+    const job = makeJob();
+    const before = JSON.stringify(job);
+    prepareForExecution(job, 42);
+    expect(JSON.stringify(job)).toBe(before);
+  });
+});
+
+describe("handleStartupCatchup (Fix #3)", () => {
+  const GRACE = 6 * 60 * 60 * 1000; // 6 h
+
+  it("rewinds nextRunAt to now when a recent attempt never completed", () => {
+    // Scenario: 08:00 triggered, 08:05 bot crashed, 10:30 bot restarts.
+    const job = makeJob({
+      lastRunAt: null,                              // never completed
+      lastAttemptAt: 1_775_887_200_000,             // 08:00
+      nextRunAt: 1_775_973_600_000,                 // tomorrow 08:00 (set pre-execution)
+    });
+    const now = 1_775_896_200_000;                  // 10:30
+    const [out] = handleStartupCatchup([job], now, GRACE);
+    expect(out.nextRunAt).toBe(now); // rewind → picked up on next tick
+  });
+
+  it("does not rewind when attempt completed (lastRunAt >= lastAttemptAt)", () => {
+    const tomorrow8am = 1_775_973_600_000;
+    const job = makeJob({
+      lastRunAt: 1_775_896_200_000,                 // completed at 10:30
+      lastAttemptAt: 1_775_887_200_000,             // started at 08:00
+      nextRunAt: tomorrow8am,
+    });
+    const now = 1_775_900_000_000;
+    const [out] = handleStartupCatchup([job], now, GRACE);
+    expect(out.nextRunAt).toBe(tomorrow8am); // unchanged
+  });
+
+  it("gives up when the attempt is older than the grace window", () => {
+    // Scenario: attempt was 7h ago, never completed, bot only now back up.
+    const sevenHoursAgo = 1_775_887_200_000 - 60_000;
+    const now = sevenHoursAgo + 7 * 60 * 60 * 1000 + 60_000;
+    const job = makeJob({
+      lastRunAt: null,
+      lastAttemptAt: sevenHoursAgo,
+      nextRunAt: now + 86_400_000, // whatever — scheduler will replace
+    });
+    const [out] = handleStartupCatchup([job], now, GRACE);
+    // Must NOT rewind to `now`. Must either keep the future value or
+    // recompute — either way it has to stay strictly greater than now.
+    expect(out.nextRunAt).not.toBe(now);
+    expect(out.nextRunAt!).toBeGreaterThan(now);
+  });
+
+  it("ignores disabled jobs", () => {
+    const job = makeJob({
+      enabled: false,
+      lastRunAt: null,
+      lastAttemptAt: 1_775_887_200_000,
+      nextRunAt: 1_775_973_600_000,
+    });
+    const now = 1_775_896_200_000;
+    const [out] = handleStartupCatchup([job], now, GRACE);
+    expect(out).toEqual(job); // untouched
+  });
+
+  it("handles jobs without any attempt history (no-op)", () => {
+    const job = makeJob({
+      lastRunAt: null,
+      lastAttemptAt: null,
+      nextRunAt: 1_775_973_600_000,
+    });
+    const now = 1_775_896_200_000;
+    const [out] = handleStartupCatchup([job], now, GRACE);
+    expect(out).toEqual(job);
+  });
+
+  it("is pure — does not mutate the input array", () => {
+    const job = makeJob({
+      lastRunAt: null,
+      lastAttemptAt: 1_775_887_200_000,
+      nextRunAt: 1_775_973_600_000,
+    });
+    const input = [job];
+    const snapshot = JSON.stringify(input);
+    handleStartupCatchup(input, 1_775_896_200_000, GRACE);
+    expect(JSON.stringify(input)).toBe(snapshot);
+  });
+
+  it("processes multiple jobs independently", () => {
+    const now = 1_775_896_200_000;
+    const recent = makeJob({
+      id: "a",
+      lastRunAt: null,
+      lastAttemptAt: 1_775_887_200_000, // within grace
+      nextRunAt: 1_775_973_600_000,
+    });
+    const completed = makeJob({
+      id: "b",
+      lastRunAt: 1_775_887_500_000,
+      lastAttemptAt: 1_775_887_200_000,
+      nextRunAt: 1_775_973_600_000,
+    });
+    const out = handleStartupCatchup([recent, completed], now, GRACE);
+    expect(out[0].nextRunAt).toBe(now);            // caught up
+    expect(out[1].nextRunAt).toBe(1_775_973_600_000); // untouched
+  });
+});

package/test/debounce.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Fix #7 — fs.watch emits duplicates on macOS; we need a simple debounce.
+ *
+ * Contract: `debounce(fn, waitMs)` returns a wrapped function. Calling
+ * the wrapped function schedules `fn()` to run `waitMs` ms after the
+ * last call. Multiple calls inside the window coalesce into one
+ * invocation. Each "quiet period" starts a fresh cycle.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { debounce } from "../src/util/debounce.js";
+
+beforeEach(() => { vi.useFakeTimers(); });
+afterEach(() => { vi.useRealTimers(); });
+
+describe("debounce (Fix #7)", () => {
+  it("runs the function once after the wait period", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 200);
+    d();
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(199);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("coalesces many rapid calls into one invocation", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 300);
+    d(); d(); d(); d();
+    vi.advanceTimersByTime(299);
+    d(); // resets the timer
+    vi.advanceTimersByTime(299);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows a second invocation after the wait elapses between calls", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+    d();
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+    d();
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("passes through the latest arguments to the final call", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 50);
+    d("first");
+    d("second");
+    d("third");
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledWith("third");
+  });
+});