station-kit 1.1.0 → 2.0.0

package/src/server/index.ts

@@ -1,29 +1,35 @@
 import { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
+import { bodyLimit } from "hono/body-limit";
 import { serve } from "@hono/node-server";
 import { resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import type { Server } from "node:http";
 import { SignalRunner, MemoryAdapter, parseInterval } from "station-signal";
 import { BroadcastRunner, BroadcastMemoryAdapter } from "station-broadcast";
+import { BeaconRunner, BeaconMemoryAdapter } from "station-beacon";
 import type { SignalQueueAdapter } from "station-signal";
 import type { BroadcastQueueAdapter } from "station-broadcast";
+import type { BeaconStateAdapter } from "station-beacon";
 import {
   ScheduleReconciler,
   type Schedule,
   type ScheduleAdapter,
 } from "station-schedules";
+import { EnvStore, FileEnvStorage } from "station-env";
 import type { StationConfig } from "../config/schema.js";
 import { ensureStationDir } from "../station-dir.js";
 import { WebSocketHub } from "./ws.js";
 import { SSEHub } from "./sse.js";
 import { LogBuffer } from "./log-buffer.js";
 import { LogStore, FileLogStorage } from "./log-store.js";
-import { StationSignalSubscriber, StationBroadcastSubscriber } from "./subscriber.js";
+import { StationSignalSubscriber, StationBroadcastSubscriber, StationBeaconSubscriber } from "./subscriber.js";
 import { healthRoutes } from "./routes/health.js";
 import { signalRoutes } from "./routes/signals.js";
 import { runRoutes } from "./routes/runs.js";
 import { broadcastRoutes } from "./routes/broadcasts.js";
+import { beaconRoutes } from "./routes/beacons.js";
 import { KeyStore, FileKeyStorage } from "./auth/keys.js";
 import { verifySessionToken, verifyCredentials, createSessionToken, type SessionConfig } from "./auth/session.js";
 import { authResolver } from "./middleware/auth.js";
@@ -39,6 +45,7 @@ import { v1AuthRoutes } from "./routes/v1/auth.js";
 import { v1EventRoutes } from "./routes/v1/events.js";
 import { v1DefinitionRoutes, v1DefinitionReadRoutes } from "./routes/v1/definitions.js";
 import { v1ScheduleRoutes, v1ScheduleReadRoutes } from "./routes/v1/schedules.js";
+import { v1EnvRoutes, v1EnvReadRoutes } from "./routes/v1/env.js";
 import { v1ExpressionRoutes } from "./routes/v1/expressions.js";
 
 export {
@@ -78,6 +85,8 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   const signalAdapter: SignalQueueAdapter = config.adapter ?? new MemoryAdapter();
   const broadcastAdapter: BroadcastQueueAdapter | undefined =
     config.broadcastAdapter ?? (config.broadcastsDir ? new BroadcastMemoryAdapter() : undefined);
+  const beaconAdapter: BeaconStateAdapter | undefined =
+    config.beaconAdapter ?? (config.beaconsDir ? new BeaconMemoryAdapter() : undefined);
 
   const { dataDir } = ensureStationDir(cwd, config.stationDir);
 
@@ -93,6 +102,13 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     }),
   );
 
+  // Runtime env store: defaults to a JSON file so `.env()` requirements and
+  // dashboard-defined variables work out of the box. Pass a durable adapter
+  // via `envStorage` for multi-process deployments.
+  const envStore = new EnvStore(
+    config.envStorage ?? new FileEnvStorage({ filePath: resolve(dataDir, "station-env.json") }),
+  );
+
   // Auth: create KeyStore and SessionConfig if auth is configured
   let keyStore: KeyStore | undefined;
   let sessionConfig: SessionConfig | undefined;
@@ -100,7 +116,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   if (config.auth) {
     const storage = config.auth.keyStorage
       ?? new FileKeyStorage({ filePath: resolve(dataDir, "station-keys.json") });
-    keyStore = new KeyStore(storage);
+    keyStore = new KeyStore(storage, { pepper: resolveKeyPepper(dataDir) });
     sessionConfig = {
       username: config.auth.username,
       password: config.auth.password,
@@ -121,17 +137,26 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       ? resolve(cwd, "broadcasts")
       : undefined;
 
+  const beaconsDir = config.beaconsDir
+    ? resolve(cwd, config.beaconsDir)
+    : existsSync(resolve(cwd, "beacons"))
+      ? resolve(cwd, "beacons")
+      : undefined;
+
   // Create subscribers (always — they collect metadata)
   const stationSignalSub = new StationSignalSubscriber(wsHub, logBuffer, logStore);
   const stationBroadcastSub = new StationBroadcastSubscriber(wsHub);
+  const stationBeaconSub = new StationBeaconSubscriber(wsHub, logBuffer, logStore);
 
   // Wire SSE hub into subscribers so events reach both WS and SSE clients
   stationSignalSub.setSSEHub(sseHub);
   stationBroadcastSub.setSSEHub(sseHub);
+  stationBeaconSub.setSSEHub(sseHub);
 
   // Create runners if enabled
   let signalRunner: SignalRunner | undefined;
   let broadcastRunner: BroadcastRunner | undefined;
+  let beaconRunner: BeaconRunner | undefined;
   const scheduleAdapter: ScheduleAdapter | undefined = config.scheduleAdapter;
 
   if (config.runRunners) {
@@ -158,6 +183,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       retryBackoffMs: config.runner.retryBackoffMs,
       subscribers: [stationSignalSub],
       scheduleReconciler: signalScheduleReconciler,
+      envProvider: envStore,
     });
 
     if (broadcastsDir || broadcastAdapter) {
@@ -182,11 +208,30 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
         scheduleReconciler: broadcastScheduleReconciler,
       });
     }
+
+    if (beaconsDir || beaconAdapter) {
+      beaconRunner = new BeaconRunner({
+        beaconsDir,
+        adapter: beaconAdapter ?? new BeaconMemoryAdapter(),
+        signalRunner, // beacons can trigger signals into the shared queue
+        subscribers: [stationBeaconSub],
+        envProvider: envStore,
+      });
+    }
   }
 
   // Build Hono app
   const app = new Hono();
 
+  // Bound request bodies so oversized payloads can't be parsed/stored.
+  app.use("/api/*", bodyLimit({
+    maxSize: 5 * 1024 * 1024,
+    onError: (c) => c.json({ error: "payload_too_large", message: "Request body too large." }, 413),
+  }));
+
+  // Brute-force protection for the dashboard login (the v1 login is limited below).
+  app.use("/api/auth/login", rateLimiter({ windowMs: 60_000, max: 10 }));
+
   // ── Dashboard auth routes (always accessible) ──────────────────────
   app.get("/api/auth/check", async (c) => {
     if (!sessionConfig) {
@@ -248,15 +293,18 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   app.route("/api", signalRoutes({ signalRunner, signalAdapter, signalSubscriber: stationSignalSub }));
   app.route("/api", runRoutes({ signalRunner, signalAdapter, logBuffer, logStore, signalSubscriber: stationSignalSub }));
   app.route("/api", broadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub, logBuffer, logStore }));
+  app.route("/api", beaconRoutes({ beaconRunner, beaconAdapter, logBuffer, logStore }));
 
   // ── v1 API routes (authenticated) ──────────────────────────────────
 
   // Public v1 routes (no auth required)
   app.route("/api/v1", v1HealthRoutes({ signalAdapter, broadcastAdapter }));
 
-  // Auth routes: public but rate-limited to prevent brute force
+  // Auth routes: public but rate-limited to prevent brute force. The limiter
+  // is scoped to /auth/* — a "/*" limiter here would run for every /api/v1
+  // route mounted after this app and throttle the whole API to 10 req/min.
   const authApp = new Hono();
-  authApp.use("/*", rateLimiter({ windowMs: 60_000, max: 10 }));
+  authApp.use("/auth/*", rateLimiter({ windowMs: 60_000, max: 10 }));
   authApp.route("/", v1AuthRoutes({ sessionConfig }));
   app.route("/api/v1", authApp);
 
@@ -264,9 +312,22 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   const v1 = new Hono();
   v1.use("/*", authResolver({ keyStore, sessionConfig }));
 
+  // Hono runs a sub-app's `use("/*")` middleware for routes that sibling
+  // sub-apps mount LATER under the same prefix, so per-group scope guards
+  // stack instead of isolating (a trigger-only key would be rejected by the
+  // read group's guard before reaching /trigger). Attach the guard to each
+  // route individually instead.
+  const guarded = (scope: string, group: Hono): Hono => {
+    const out = new Hono();
+    const guard = requireScope(scope);
+    for (const r of group.routes) {
+      out.on(r.method, r.path, guard, r.handler);
+    }
+    return out;
+  };
+
   // Read-scope routes
   const readRoutes = new Hono();
-  readRoutes.use("/*", requireScope("read"));
   readRoutes.route("/", v1SignalRoutes({ signalRunner, signalSubscriber: stationSignalSub }));
   readRoutes.route("/", v1RunRoutes({ signalRunner, signalAdapter, logBuffer, logStore }));
   readRoutes.route("/", v1BroadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub }));
@@ -274,23 +335,21 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   readRoutes.route("/", v1ExpressionRoutes());
   // Schedule GET + preview are read-scoped; mutating routes are mounted under admin below.
   readRoutes.route("/", v1ScheduleReadRoutes({ scheduleAdapter }));
+  // Env GET is read-scoped (secret values redacted); mutations are admin-only below.
+  readRoutes.route("/", v1EnvReadRoutes({ envStore }));
   readRoutes.route("/", v1DefinitionReadRoutes({
     broadcastRunner,
     broadcastAdapter,
     signalRunner,
     signalSubscriber: stationSignalSub,
   }));
-  v1.route("/", readRoutes);
+  v1.route("/", guarded("read", readRoutes));
 
   // Trigger-scope routes
-  const triggerRoutes = new Hono();
-  triggerRoutes.use("/*", requireScope("trigger"));
-  triggerRoutes.route("/", v1TriggerRoutes({ signalRunner, signalAdapter, broadcastRunner, broadcastAdapter, signalSubscriber: stationSignalSub }));
-  v1.route("/", triggerRoutes);
+  v1.route("/", guarded("trigger", v1TriggerRoutes({ signalRunner, signalAdapter, broadcastRunner, broadcastAdapter, signalSubscriber: stationSignalSub })));
 
   // Cancel-scope routes — only the cancel endpoints
   const cancelRoutes = new Hono();
-  cancelRoutes.use("/*", requireScope("cancel"));
   cancelRoutes.post("/runs/:id/cancel", async (c) => {
     const id = c.req.param("id");
     if (!signalRunner) {
@@ -313,11 +372,10 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     }
     return c.json({ data: { cancelled: true } });
   });
-  v1.route("/", cancelRoutes);
+  v1.route("/", guarded("cancel", cancelRoutes));
 
   // Admin-scope routes — destructive / mutating endpoints
   const adminRoutes = new Hono();
-  adminRoutes.use("/*", requireScope("admin"));
   adminRoutes.route("/", v1KeyRoutes({ keyStore }));
   adminRoutes.route("/", v1DefinitionRoutes({
     broadcastRunner,
@@ -326,7 +384,8 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     signalSubscriber: stationSignalSub,
   }));
   adminRoutes.route("/", v1ScheduleRoutes({ scheduleAdapter }));
-  v1.route("/", adminRoutes);
+  adminRoutes.route("/", v1EnvRoutes({ envStore }));
+  v1.route("/", guarded("admin", adminRoutes));
 
   app.route("/api/v1", v1);
 
@@ -384,6 +443,14 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     keyStore,
     dataDir,
     async start() {
+      if (!config.auth && !isLoopbackHost(config.host)) {
+        console.warn(
+          `[station] WARNING: no auth configured while binding to ${config.host} — ` +
+          "anyone who can reach this port can view logs and trigger, cancel, or rerun jobs. " +
+          "Set auth (STATION_AUTH_USERNAME/STATION_AUTH_PASSWORD) or bind to 127.0.0.1.",
+        );
+      }
+
       // Start runners (non-blocking — they have internal poll loops)
       if (config.runRunners) {
         if (signalRunner) {
@@ -396,6 +463,11 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
             console.error("[station] Broadcast runner error:", err);
           });
         }
+        if (beaconRunner) {
+          beaconRunner.start().catch((err: unknown) => {
+            console.error("[station] Beacon runner error:", err);
+          });
+        }
       }
 
       // Start Hono server
@@ -406,12 +478,31 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
         },
       ) as unknown as Server;
 
-      // Attach WebSocket to the HTTP server
-      wsHub.attach(httpServer);
+      // Attach WebSocket to the HTTP server. The upgrade path never passes
+      // through Hono middleware, so it enforces auth itself: session cookie
+      // or a read-scoped API key, mirroring the SSE endpoint.
+      wsHub.attach(httpServer, async (req) => {
+        if (!sessionConfig && !keyStore) return true;
+        const cookie = req.headers.cookie;
+        if (cookie && sessionConfig) {
+          const match = cookie.match(/station_session=([^;]+)/);
+          if (match && verifySessionToken(match[1], sessionConfig)) return true;
+        }
+        const authHeader = req.headers.authorization;
+        if (authHeader?.startsWith("Bearer ") && keyStore) {
+          const key = await keyStore.verify(authHeader.slice(7));
+          if (key?.scopes.includes("read")) return true;
+        }
+        return false;
+      });
     },
 
     async stop() {
-      // Stop broadcast runner first — it queries the DB during graceful shutdown
+      // Stop beacons first — they are producers that may trigger signals.
+      if (beaconRunner) {
+        await beaconRunner.stop({ graceful: true, timeoutMs: 5000 });
+      }
+      // Stop broadcast runner next — it queries the DB during graceful shutdown
       if (broadcastRunner) {
         await broadcastRunner.stop({ graceful: true, timeoutMs: 5000 });
       }
@@ -422,6 +513,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       sseHub.close();
       await logStore.close();
       await keyStore?.close();
+      await envStore.close();
       if (httpServer) {
         httpServer.close();
       }
@@ -434,6 +526,40 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
 // new defaults are `station-keys.json` and `station-logs.jsonl`; the
 // legacy files are NOT auto-migrated. Emit a one-time warning so an
 // upgrade doesn't silently appear to wipe a user's API keys.
+function isLoopbackHost(host: string): boolean {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+}
+
+/**
+ * Resolve the API-key pepper (a server-side secret mixed into stored key
+ * hashes). Priority: STATION_KEY_PEPPER env var, else a persisted per-install
+ * secret at `<dataDir>/station-key-pepper` (generated with 0600 on first run).
+ * Persisting it means existing peppered keys keep verifying across restarts.
+ */
+function resolveKeyPepper(dataDir: string): string {
+  const fromEnv = process.env.STATION_KEY_PEPPER;
+  if (fromEnv) return fromEnv;
+
+  const pepperPath = resolve(dataDir, "station-key-pepper");
+  try {
+    if (existsSync(pepperPath)) {
+      const existing = readFileSync(pepperPath, "utf8").trim();
+      if (existing) return existing;
+    }
+  } catch {
+    // Unreadable — fall through and regenerate.
+  }
+  const pepper = randomBytes(32).toString("hex");
+  try {
+    writeFileSync(pepperPath, pepper, { mode: 0o600 });
+  } catch (err) {
+    // If we can't persist it, warn: keys created this run won't verify after
+    // a restart (a new pepper would be generated). Better than failing boot.
+    console.warn(`[station] Could not persist key pepper to ${pepperPath}:`, err);
+  }
+  return pepper;
+}
+
 function warnIfLegacySqliteFiles(dataDir: string): void {
   const legacy: { file: string; replacement: string }[] = [
     { file: "station-keys.db", replacement: "station-keys.json" },

package/src/server/metadata.ts

@@ -24,6 +24,8 @@ export interface SignalMeta {
   maxConcurrency: number | null;
   hasSteps: boolean;
   stepNames: string[];
+  /** Env var keys this signal requires (declared via `.env()`). */
+  requiredEnv: string[];
 }
 
 export interface BroadcastMeta {

package/src/server/middleware/rate-limit.ts

@@ -15,11 +15,20 @@ interface BucketEntry {
   resetAt: number;
 }
 
+/** Upper bound on tracked buckets so unique keys can't grow the map unbounded. */
+const MAX_BUCKETS = 10_000;
+
 export function rateLimiter(options: RateLimitOptions = {}) {
   const windowMs = options.windowMs ?? 60_000;
   const max = options.max ?? 100;
   const keyFn = options.keyFn ?? ((c: Context) => {
-    return (c.get("apiKeyId") as string) ?? c.req.header("x-forwarded-for") ?? "anonymous";
+    const apiKeyId = c.get("apiKeyId") as string | undefined;
+    if (apiKeyId) return apiKeyId;
+    // Key on the socket's address, NOT x-forwarded-for: that header is
+    // client-controlled, so keying on it lets an attacker mint a fresh
+    // bucket per request and bypass the limit entirely.
+    const incoming = (c.env as { incoming?: { socket?: { remoteAddress?: string } } })?.incoming;
+    return incoming?.socket?.remoteAddress ?? "anonymous";
   });
 
   const buckets = new Map<string, BucketEntry>();
@@ -39,6 +48,16 @@ export function rateLimiter(options: RateLimitOptions = {}) {
 
     let entry = buckets.get(key);
     if (!entry || now > entry.resetAt) {
+      if (!entry && buckets.size >= MAX_BUCKETS) {
+        // Evict expired entries first; if everything is live, drop the oldest.
+        for (const [k, e] of buckets) {
+          if (now > e.resetAt) buckets.delete(k);
+        }
+        if (buckets.size >= MAX_BUCKETS) {
+          const oldest = buckets.keys().next().value;
+          if (oldest !== undefined) buckets.delete(oldest);
+        }
+      }
       entry = { count: 0, resetAt: now + windowMs };
       buckets.set(key, entry);
     }

package/src/server/routes/beacons.ts

@@ -0,0 +1,112 @@
+import { Hono } from "hono";
+import type { BeaconRunner, BeaconStateAdapter, BeaconInstance } from "station-beacon";
+import { beaconLogKey } from "../subscriber.js";
+
+export interface BeaconDeps {
+  beaconRunner?: BeaconRunner;
+  beaconAdapter?: BeaconStateAdapter;
+  logBuffer?: import("../log-buffer.js").LogBuffer;
+  logStore?: import("../log-store.js").LogStore;
+}
+
+function serializeInstance(inst: BeaconInstance): Record<string, unknown> {
+  return {
+    ...inst,
+    startedAt: inst.startedAt?.toISOString?.() ?? inst.startedAt,
+    readyAt: inst.readyAt?.toISOString?.() ?? inst.readyAt,
+    lastHeartbeatAt: inst.lastHeartbeatAt?.toISOString?.() ?? inst.lastHeartbeatAt,
+    lastExitAt: inst.lastExitAt?.toISOString?.() ?? inst.lastExitAt,
+    nextRestartAt: inst.nextRestartAt?.toISOString?.() ?? inst.nextRestartAt,
+    createdAt: inst.createdAt?.toISOString?.() ?? inst.createdAt,
+    updatedAt: inst.updatedAt?.toISOString?.() ?? inst.updatedAt,
+  };
+}
+
+export function beaconRoutes(deps: BeaconDeps) {
+  const app = new Hono();
+
+  // GET /beacons — list registered beacons merged with their instance state
+  app.get("/beacons", async (c) => {
+    if (!deps.beaconRunner) return c.json({ data: [] });
+    const registered = deps.beaconRunner.listRegistered();
+    const instances = await deps.beaconRunner.listInstances();
+    const byName = new Map(instances.map((i) => [i.beaconName, i]));
+    const data = registered.map((r) => {
+      const inst = byName.get(r.name);
+      return { ...r, instance: inst ? serializeInstance(inst) : null };
+    });
+    return c.json({ data });
+  });
+
+  // GET /beacons/:name — registered metadata + current instance
+  app.get("/beacons/:name", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.beaconRunner) {
+      return c.json({ error: "not_found", message: "No beacon runner configured." }, 404);
+    }
+    const meta = deps.beaconRunner.listRegistered().find((b) => b.name === name);
+    if (!meta) {
+      return c.json({ error: "not_found", message: `Beacon "${name}" not found.` }, 404);
+    }
+    const inst = await deps.beaconRunner.getInstance(name);
+    return c.json({ data: { ...meta, instance: inst ? serializeInstance(inst) : null } });
+  });
+
+  // GET /beacons/:name/events — lifecycle event log (if the adapter records one)
+  app.get("/beacons/:name/events", async (c) => {
+    const name = c.req.param("name");
+    // Clamp so a client can't request an unbounded (or NaN) event scan.
+    const raw = Number(c.req.query("limit") ?? "200");
+    const limit = Number.isFinite(raw) ? Math.min(Math.max(Math.trunc(raw), 1), 1000) : 200;
+    if (!deps.beaconAdapter?.listEvents) return c.json({ data: [] });
+    const events = await deps.beaconAdapter.listEvents(name, limit);
+    return c.json({
+      data: events.map((e) => ({ ...e, at: e.at?.toISOString?.() ?? e.at })),
+    });
+  });
+
+  // GET /beacons/:name/logs — captured stdout/stderr/log lines
+  app.get("/beacons/:name/logs", async (c) => {
+    const name = c.req.param("name");
+    const key = beaconLogKey(name);
+    const logs = deps.logStore
+      ? await deps.logStore.get(key)
+      : deps.logBuffer?.get(key) ?? [];
+    return c.json({ data: logs });
+  });
+
+  // POST /beacons/:name/{start,stop,restart} — operator controls
+  app.post("/beacons/:name/start", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.beaconRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      await deps.beaconRunner.startBeacon(name, "config" in body ? { config: body.config } : undefined);
+      return c.json({ data: { started: true } });
+    } catch (err: unknown) {
+      return c.json({ error: "start_failed", message: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  app.post("/beacons/:name/stop", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.beaconRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+    await deps.beaconRunner.stopBeacon(name);
+    return c.json({ data: { stopped: true } });
+  });
+
+  app.post("/beacons/:name/restart", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.beaconRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+    await deps.beaconRunner.restartBeacon(name);
+    return c.json({ data: { restarted: true } });
+  });
+
+  return app;
+}

package/src/server/routes/broadcasts.ts

@@ -77,10 +77,14 @@ export function broadcastRoutes(deps: BroadcastDeps) {
     if (!deps.broadcastAdapter) {
       return c.json({ data: [], meta: { total: 0 } });
     }
-    const runs = await deps.broadcastAdapter.listBroadcastRuns(name);
+    const limitRaw = parseInt(c.req.query("limit") ?? "100", 10);
+    const limit = Math.min(Number.isNaN(limitRaw) ? 100 : Math.max(limitRaw, 1), 500);
+    const offsetRaw = parseInt(c.req.query("offset") ?? "0", 10);
+    const offset = Number.isNaN(offsetRaw) ? 0 : Math.max(offsetRaw, 0);
+    const runs = await deps.broadcastAdapter.listBroadcastRuns(name, { limit, offset });
     return c.json({
       data: runs.map(serializeBroadcastRun),
-      meta: { total: runs.length },
+      meta: { count: runs.length, limit, offset },
     });
   });
 

package/src/server/routes/runs.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import type { SignalRunner, SignalQueueAdapter } from "station-signal";
+import type { SignalRunner, SignalQueueAdapter, Run, RunStatus } from "station-signal";
 import type { LogBuffer } from "../log-buffer.js";
 import type { LogStore } from "../log-store.js";
 import type { StationSignalSubscriber } from "../subscriber.js";
@@ -18,82 +18,28 @@ export function runRoutes(deps: RunDeps) {
   app.get("/runs", async (c) => {
     const status = c.req.query("status");
     const signalName = c.req.query("signalName");
+    const limit = clampInt(c.req.query("limit"), 100, 1, 500);
+    const offset = clampInt(c.req.query("offset"), 0, 0, Number.MAX_SAFE_INTEGER);
+    const statuses = status ? ([status] as RunStatus[]) : undefined;
 
-    // Gather runs from adapter
-    let runs: any[] = [];
-
-    if (signalName) {
-      runs = await deps.signalAdapter.listRuns(signalName);
-    } else {
-      // Get all runs by combining due + running + listing by known signals
-      const due = await deps.signalAdapter.getRunsDue();
-      const running = await deps.signalAdapter.getRunsRunning();
-      const seen = new Set<string>();
-      for (const r of [...due, ...running]) {
-        if (!seen.has(r.id)) {
-          seen.add(r.id);
-          runs.push(r);
-        }
-      }
-
-      // Also get runs from known signals
-      if (deps.signalRunner) {
-        for (const { name } of deps.signalRunner.listRegistered()) {
-          const signalRuns = await deps.signalAdapter.listRuns(name);
-          for (const r of signalRuns) {
-            if (!seen.has(r.id)) {
-              seen.add(r.id);
-              runs.push(r);
-            }
-          }
-        }
-      }
-    }
-
-    if (status) {
-      runs = runs.filter((r) => r.status === status);
-    }
-
-    // Sort by createdAt descending
-    runs.sort((a, b) => {
-      const aTime = a.createdAt instanceof Date ? a.createdAt.getTime() : new Date(a.createdAt).getTime();
-      const bTime = b.createdAt instanceof Date ? b.createdAt.getTime() : new Date(b.createdAt).getTime();
-      return bTime - aTime;
-    });
+    // Push filtering, ordering, and limiting into the adapter instead of
+    // loading every signal's full history and sorting in memory.
+    const runs: Run[] = signalName
+      ? await deps.signalAdapter.listRuns(signalName, { limit, offset, statuses })
+      : await deps.signalAdapter.listAllRuns({ limit, offset, statuses });
 
     return c.json({
       data: runs.map(serializeRun),
-      meta: { total: runs.length },
+      meta: { count: runs.length, limit, offset },
     });
   });
 
   app.get("/runs/stats", async (c) => {
-    const due = await deps.signalAdapter.getRunsDue();
-    const running = await deps.signalAdapter.getRunsRunning();
-
-    // Aggregate from known signals
-    let allRuns: any[] = [...due, ...running];
-    const seen = new Set(allRuns.map((r) => r.id));
-
-    if (deps.signalRunner) {
-      for (const { name } of deps.signalRunner.listRegistered()) {
-        const signalRuns = await deps.signalAdapter.listRuns(name);
-        for (const r of signalRuns) {
-          if (!seen.has(r.id)) {
-            seen.add(r.id);
-            allRuns.push(r);
-          }
-        }
-      }
-    }
-
+    const counts = await deps.signalAdapter.countRunsByStatus();
     const stats = { pending: 0, running: 0, completed: 0, failed: 0, cancelled: 0 };
-    for (const r of allRuns) {
-      if (r.status in stats) {
-        stats[r.status as keyof typeof stats]++;
-      }
+    for (const key of Object.keys(stats) as RunStatus[]) {
+      stats[key as keyof typeof stats] = counts[key] ?? 0;
     }
-
     return c.json({ data: stats });
   });
 
@@ -213,6 +159,13 @@ export function runRoutes(deps: RunDeps) {
   return app;
 }
 
+/** Parse an integer query param, clamping to [min, max] with a fallback. */
+function clampInt(raw: string | undefined, fallback: number, min: number, max: number): number {
+  const n = parseInt(raw ?? "", 10);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(Math.max(n, min), max);
+}
+
 function serializeRun(run: any): Record<string, unknown> {
   return {
     ...run,