feat(api): extract pure wake-scheduler helpers (nextDailyAfter, recoverScheduleEntry)

Side-effect-free module so missed-wake recovery and rescheduling can be
unit-tested without booting Hono or touching SQLite.

- nextDailyAfter: advances by 24h increments until strictly > now (handles
  multi-day gaps in a single step instead of looping a day at a time).
- recoverScheduleEntry: classifies a past next_wake_at into 'fire now,
  then advance' vs 'silently advance' based on MISSED_WAKE_GRACE_MS (2h).
- CLAUDE_RESET_OFFSET_HOURS / resetHourFor: single source of truth for the
  '+5h reset' display, previously hardcoded in three places.

Includes 12 unit tests covering grace boundaries, multi-day skip, custom
grace windows, and midnight wraparound.

2 files changed, 180 insertions, 0 deletions

diff --git a/packages/api/src/wake-scheduler.ts b/packages/api/src/wake-scheduler.ts
new file mode 100644
index 0000000..7bd2fad
--- /dev/null
+++ b/packages/api/src/wake-scheduler.ts
@@ -0,0 +1,82 @@
+/**
+ * Pure helpers for the Claude wake scheduler. Kept side-effect-free so the
+ * recovery & rescheduling logic can be unit-tested without spinning up the
+ * Hono app or touching SQLite.
+ *
+ * Semantics — read this before editing:
+ *
+ *   1. The user picks an hour (0-23) on the frontend. The frontend computes
+ *      the *first* fire timestamp in **its** local timezone (target HH:15
+ *      tomorrow, or today if still future) and sends absolute Unix ms to
+ *      the backend. That absolute ms is the source of truth.
+ *
+ *   2. After each successful (or attempted) fire we advance by exactly
+ *      24h from the previous `next_wake_at`. This preserves the user's
+ *      original local wall-clock intent regardless of the *server*'s
+ *      timezone (Docker is often UTC, the user is often not). DST can
+ *      drift the fire by ±1h on transition day; it self-corrects the next
+ *      time the user toggles the hour.
+ *
+ *   3. On server boot, any persisted entry whose `next_wake_at` is in the
+ *      past is "recovered": if it was missed by ≤ MISSED_WAKE_GRACE_MS we
+ *      fire it *now* (signal: `shouldFireNow = true`) and then jump
+ *      forward 24h at a time until the next slot is in the future. If
+ *      missed by more than the grace window we silently skip and jump
+ *      forward without firing. Either way the entry stays scheduled.
+ */
+
+/** How long after a missed fire we still consider it worth running. */
+export const MISSED_WAKE_GRACE_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+/** Day length used when advancing recurring wakes. */
+export const DAILY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** Fixed offset (hours) from a wake to the "Claude session reset" display. */
+export const CLAUDE_RESET_OFFSET_HOURS = 5;
+
+/**
+ * Advance `previous` by 24-hour increments until strictly after `now`.
+ * Pure: only does math on the given numbers.
+ */
+export function nextDailyAfter(previous: number, now: number): number {
+	if (previous > now) return previous;
+	const deltaMs = now - previous;
+	// Ceiling division so the result is strictly > now.
+	const stepsAhead = Math.floor(deltaMs / DAILY_INTERVAL_MS) + 1;
+	return previous + stepsAhead * DAILY_INTERVAL_MS;
+}
+
+export interface RecoveredEntry {
+	/** New `next_wake_at` to persist (always strictly in the future). */
+	nextWakeAt: number;
+	/** True if the caller should fire a wake *right now* before scheduling. */
+	shouldFireNow: boolean;
+}
+
+/**
+ * Compute the post-boot state for a single persisted schedule entry.
+ *
+ *   - Entry still in the future → keep as-is, no fire.
+ *   - Missed by ≤ grace window  → fire now, then advance to next day.
+ *   - Missed by > grace window  → skip the fire, advance to next day.
+ */
+export function recoverScheduleEntry(
+	storedNextWakeAt: number,
+	now: number,
+	graceMs: number = MISSED_WAKE_GRACE_MS,
+): RecoveredEntry {
+	if (storedNextWakeAt > now) {
+		return { nextWakeAt: storedNextWakeAt, shouldFireNow: false };
+	}
+	const overdueBy = now - storedNextWakeAt;
+	const shouldFireNow = overdueBy <= graceMs;
+	return {
+		nextWakeAt: nextDailyAfter(storedNextWakeAt, now),
+		shouldFireNow,
+	};
+}
+
+/** Display hour (0-23) for the "reset" label paired with a wake hour. */
+export function resetHourFor(wakeHour: number): number {
+	return (wakeHour + CLAUDE_RESET_OFFSET_HOURS) % 24;
+}
diff --git a/packages/api/tests/wake-scheduler.test.ts b/packages/api/tests/wake-scheduler.test.ts
new file mode 100644
index 0000000..0e5731c
--- /dev/null
+++ b/packages/api/tests/wake-scheduler.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import {
+	CLAUDE_RESET_OFFSET_HOURS,
+	DAILY_INTERVAL_MS,
+	MISSED_WAKE_GRACE_MS,
+	nextDailyAfter,
+	recoverScheduleEntry,
+	resetHourFor,
+} from "../src/wake-scheduler.js";
+
+const HOUR = 60 * 60 * 1000;
+
+describe("nextDailyAfter", () => {
+	it("returns the input when it is already strictly in the future", () => {
+		const now = 1_700_000_000_000;
+		const future = now + 60_000;
+		expect(nextDailyAfter(future, now)).toBe(future);
+	});
+
+	it("advances by exactly 24h when the input is 1ms in the past", () => {
+		const now = 1_700_000_000_000;
+		const previous = now - 1;
+		expect(nextDailyAfter(previous, now)).toBe(previous + DAILY_INTERVAL_MS);
+	});
+
+	it("skips multiple missed days in a single step when far in the past", () => {
+		const now = 1_700_000_000_000;
+		const previous = now - 3 * DAILY_INTERVAL_MS - HOUR; // 3d 1h ago
+		const next = nextDailyAfter(previous, now);
+		expect(next).toBeGreaterThan(now);
+		// Should be the next 24h-multiple boundary, not just +24h.
+		expect((next - previous) % DAILY_INTERVAL_MS).toBe(0);
+		expect(next - previous).toBe(4 * DAILY_INTERVAL_MS);
+	});
+
+	it("returns previous + 1 day exactly when previous == now", () => {
+		const now = 1_700_000_000_000;
+		expect(nextDailyAfter(now, now)).toBe(now + DAILY_INTERVAL_MS);
+	});
+});
+
+describe("recoverScheduleEntry", () => {
+	const now = 1_700_000_000_000;
+
+	it("leaves a future entry unchanged and does not fire", () => {
+		const stored = now + 5 * HOUR;
+		expect(recoverScheduleEntry(stored, now)).toEqual({
+			nextWakeAt: stored,
+			shouldFireNow: false,
+		});
+	});
+
+	it("fires now for an entry missed by less than the grace window", () => {
+		const stored = now - HOUR; // 1h ago, within 2h grace
+		const recovered = recoverScheduleEntry(stored, now);
+		expect(recovered.shouldFireNow).toBe(true);
+		expect(recovered.nextWakeAt).toBeGreaterThan(now);
+	});
+
+	it("fires now for an entry missed by exactly the grace window", () => {
+		const stored = now - MISSED_WAKE_GRACE_MS;
+		expect(recoverScheduleEntry(stored, now).shouldFireNow).toBe(true);
+	});
+
+	it("does NOT fire for an entry missed by more than the grace window", () => {
+		const stored = now - MISSED_WAKE_GRACE_MS - 1;
+		const recovered = recoverScheduleEntry(stored, now);
+		expect(recovered.shouldFireNow).toBe(false);
+		expect(recovered.nextWakeAt).toBeGreaterThan(now);
+	});
+
+	it("always returns a future nextWakeAt for past entries (regardless of grace)", () => {
+		for (const ageDays of [0.1, 0.5, 1, 2, 7, 30]) {
+			const stored = now - ageDays * DAILY_INTERVAL_MS;
+			const { nextWakeAt } = recoverScheduleEntry(stored, now);
+			expect(nextWakeAt, `age=${ageDays}d`).toBeGreaterThan(now);
+		}
+	});
+
+	it("respects a custom grace window", () => {
+		const stored = now - 10 * 60_000; // 10 min ago
+		expect(recoverScheduleEntry(stored, now, 5 * 60_000).shouldFireNow).toBe(false);
+		expect(recoverScheduleEntry(stored, now, 15 * 60_000).shouldFireNow).toBe(true);
+	});
+});
+
+describe("resetHourFor / CLAUDE_RESET_OFFSET_HOURS", () => {
+	it("adds the offset modulo 24", () => {
+		expect(resetHourFor(0)).toBe(CLAUDE_RESET_OFFSET_HOURS);
+		expect(resetHourFor(20)).toBe((20 + CLAUDE_RESET_OFFSET_HOURS) % 24);
+		expect(resetHourFor(23)).toBe((23 + CLAUDE_RESET_OFFSET_HOURS) % 24);
+	});
+
+	it("wraps cleanly across midnight", () => {
+		// Wake at 22:15, +5h = 03:00
+		expect(resetHourFor(22)).toBe(3);
+	});
+});