Add startup health check to prevent silent scheduler failure on non-default PORT (#665)

* Add startup health check to prevent silent scheduler failure on non-default PORT

The scheduler now calls a new `schedulerHealthCheck` function at startup which
fetches `/api/health` using the configured bearer token. This verifies the
scheduler can reach its own endpoints before periodic jobs begin firing.

The health check returns true on HTTP 200 and false otherwise, logging
descriptive errors via the injected deps.log. It does not prevent the scheduler
from running — it provides visibility into misconfiguration without blocking
periodic work.

Fixes #653

Signed-off-by: Saffron <263493777+itsmiso-ai@users.noreply.github.com>

* Move schedulerHealthCheck outside job loop to fire once at startup

Address review feedback on #665 — health check was inside the per-job
loop, causing N checks at startup instead of one.

---------

Signed-off-by: Saffron <263493777+itsmiso-ai@users.noreply.github.com>
Co-authored-by: Saffron <263493777+itsmiso-ai@users.noreply.github.com>
Co-authored-by: Saffron <saffron@jory.dev>
Co-authored-by: Jory Irving <46251616+joryirving@users.noreply.github.com>

Author: 3 people

src/lib/scheduler.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { schedulerConfigFromEnv, runJob, startScheduler, type SchedulerConfig, type SchedulerDeps } from "./scheduler";
+import { schedulerConfigFromEnv, schedulerHealthCheck, runJob, startScheduler, type SchedulerConfig, type SchedulerDeps } from "./scheduler";
 
 function fakeDeps(overrides: Partial<SchedulerDeps> = {}): SchedulerDeps & { logs: Array<[string, unknown]> } {
   const logs: Array<[string, unknown]> = [];
@@ -112,15 +112,50 @@ describe("startScheduler", () => {
     expect(deps.logs.some(([m]) => m.includes("DISPATCH_AGENT_TOKEN is unset"))).toBe(true);
   });
 
-  it("schedules each job after the startup delay, then on an interval", () => {
+  it("schedules a single health check and each job after the startup delay, then on an interval", () => {
     const deps = fakeDeps();
     startScheduler(CONFIG, deps);
-    expect(deps.setTimeout).toHaveBeenCalledTimes(1);
+    // one setTimeout for the health check, one for the job
+    expect(deps.setTimeout).toHaveBeenCalledTimes(2);
     expect(deps.setTimeout).toHaveBeenCalledWith(expect.any(Function), 5000);
-    // fire the startup timer -> it runs once and arms the interval
-    const startupCb = (deps.setTimeout as ReturnType<typeof vi.fn>).mock.calls[0][0] as () => void;
-    startupCb();
-    expect(deps.fetch).toHaveBeenCalledTimes(1);
+    // fire both startup timers
+    const calls = (deps.setTimeout as ReturnType<typeof vi.fn>).mock.calls;
+    for (const c of calls) (c[0] as () => void)();
+    expect(deps.fetch).toHaveBeenCalledTimes(2); // health check + job
     expect(deps.setInterval).toHaveBeenCalledWith(expect.any(Function), 900000);
   });
 });
+
+describe("schedulerHealthCheck", () => {
+  it("returns true when health endpoint responds with 200", async () => {
+    const mockFetch = vi.fn(async () => new Response(null, { status: 200 })) as unknown as typeof globalThis.fetch;
+    const deps = fakeDeps({ fetch: mockFetch });
+    const result = await schedulerHealthCheck(CONFIG, deps);
+
+    expect(result).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledWith("http://127.0.0.1:3000/api/health", {
+      headers: { Authorization: "Bearer tok" },
+    });
+  });
+
+  it("returns false and logs when health endpoint returns non-ok status", async () => {
+    const mockFetch = vi.fn(async () => new Response(null, { status: 503 })) as unknown as typeof globalThis.fetch;
+    const log = vi.fn();
+    const deps = fakeDeps({ fetch: mockFetch, log });
+    const result = await schedulerHealthCheck(CONFIG, deps);
+
+    expect(result).toBe(false);
+    expect(log).toHaveBeenCalledWith("scheduler health check failed — HTTP 503");
+  });
+
+  it("returns false and logs when fetch throws", async () => {
+    const mockFetch = vi.fn(async () => { throw new Error("ECONNREFUSED"); }) as unknown as typeof globalThis.fetch;
+    const log = vi.fn();
+    const deps = fakeDeps({ fetch: mockFetch, log });
+    const result = await schedulerHealthCheck(CONFIG, deps);
+
+    expect(result).toBe(false);
+    expect(log).toHaveBeenCalledWith("scheduler health check failed: ECONNREFUSED", expect.any(Error));
+  });
+});

src/lib/scheduler.ts

@@ -109,6 +109,31 @@ export function schedulerConfigFromEnv(env: Record<string, string | undefined>):
   };
 }
 
+/**
+ * Startup health check: verify the scheduler can reach its own endpoints.
+ * Returns true on HTTP 200, false otherwise. Does not prevent the scheduler
+ * from running — provides visibility into misconfiguration without blocking
+ * periodic work.
+ */
+export async function schedulerHealthCheck(config: SchedulerConfig, deps: SchedulerDeps): Promise<boolean> {
+  try {
+    const res = await deps.fetch(`${config.baseUrl}/api/health`, {
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+      },
+    });
+    if (!res.ok) {
+      deps.log(`scheduler health check failed — HTTP ${res.status}`);
+      return false;
+    }
+    return true;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    deps.log(`scheduler health check failed: ${msg}`, error);
+    return false;
+  }
+}
+
 /** Fire one job. Never throws — a transient failure must not kill the interval. */
 export async function runJob(job: ScheduledJob, config: SchedulerConfig, deps: SchedulerDeps): Promise<void> {
   try {
@@ -145,6 +170,12 @@ export function startScheduler(config: SchedulerConfig, deps: SchedulerDeps): un
   }
 
   const handles: unknown[] = [];
+
+  // Single health check after startup delay, not per-job
+  deps.setTimeout(() => {
+    void schedulerHealthCheck(config, deps);
+  }, config.startupDelayMs);
+
   for (const job of config.jobs) {
     deps.log(`scheduling "${job.name}" every ${job.intervalMs}ms -> ${job.path}`);
     deps.setTimeout(() => {