station-kit 1.0.9 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "station-kit",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "Dashboard for station-signal — inspect and control signals and broadcasts",
   "type": "module",
   "engines": {
@@ -35,7 +35,6 @@
   },
   "dependencies": {
     "@hono/node-server": "^1",
-    "better-sqlite3": "^11.9.1",
     "esbuild": "^0.25.12",
     "hono": "^4",
     "next": "^15",
@@ -47,20 +46,20 @@
     "station-schedules": "1.0.4"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.3.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@types/ws": "^8",
+    "better-sqlite3": "^11.9.1",
     "typescript": "^5.9.3",
-    "station-broadcast": "1.0.4",
     "station-signal": "1.0.4",
+    "station-broadcast": "1.0.4",
     "station-adapter-sqlite": "1.0.4"
   },
   "scripts": {
     "build": "tsc && next build && cp -r .next/static .next/standalone/packages/station-kit/.next/static",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/**/*.test.ts"
+    "test": "node --import tsx --test \"test/**/*.test.ts\""
   }
 }

package/src/config/schema.ts

@@ -2,15 +2,17 @@ import type { SignalQueueAdapter } from "station-signal";
 import type { BroadcastQueueAdapter } from "station-broadcast";
 import type { ScheduleAdapter } from "station-schedules";
 import type { ApiKeyStorageAdapter } from "../server/auth/keys.js";
+import type { LogStorageAdapter } from "../server/log-store.js";
 
 export interface AuthConfig {
   username: string;
   password: string;
   sessionTtlMs?: number;
   /**
-   * Pluggable storage backend for API keys. Defaults to a SQLite store at
-   * `<dataDir>/station-keys.db`. Provide a custom adapter to host keys in
-   * Postgres, MySQL, Redis, etc.
+   * Pluggable storage backend for API keys. Defaults to a JSON file at
+   * `<dataDir>/station-keys.json` (no native dependencies required).
+   * Provide a custom adapter to host keys in SQLite, Postgres, MySQL,
+   * Redis, etc.
    */
   keyStorage?: ApiKeyStorageAdapter;
 }
@@ -40,6 +42,14 @@ export interface StationConfig {
    * schedules are persisted here and reconciled by both runners.
    */
   scheduleAdapter?: ScheduleAdapter;
+  /**
+   * Pluggable storage backend for run logs. Defaults to a `FileLogStorage`
+   * (append-only JSONL file at `<dataDir>/station-logs.jsonl`, no native
+   * dependencies). The default is single-process only — for multi-process
+   * deployments or guaranteed durability, implement `LogStorageAdapter`
+   * against Postgres, MySQL, Redis, S3, etc., and pass it here.
+   */
+  logStorage?: LogStorageAdapter;
   signalsDir?: string;
   broadcastsDir?: string;
   stationDir: string;
@@ -99,6 +109,7 @@ export function resolveConfig(input: StationUserConfig): StationConfig {
     adapter: input.adapter,
     broadcastAdapter: input.broadcastAdapter,
     scheduleAdapter: input.scheduleAdapter,
+    logStorage: input.logStorage,
     signalsDir: input.signalsDir,
     broadcastsDir: input.broadcastsDir,
     stationDir: input.stationDir ?? DEFAULTS.stationDir,

package/src/server/auth/keys.ts

@@ -1,5 +1,17 @@
 import crypto from "node:crypto";
-import Database from "better-sqlite3";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
 
 export interface ApiKey {
   id: string;
@@ -29,7 +41,116 @@ export interface ApiKeyStorageAdapter {
   close?(): Promise<void> | void;
 }
 
-// ─── SQLite default ─────────────────────────────────────────────────
+// ─── JSON file default ──────────────────────────────────────────────
+
+export interface FileKeyStorageOptions {
+  filePath: string;
+}
+
+/**
+ * Default ApiKeyStorageAdapter backed by a JSON file. Used by the Station
+ * server when no `keyStorage` is configured. Has no native dependencies —
+ * works on any Node 18+ install without compiling bindings.
+ *
+ * Crash-safety: writes go through a fsync'd tmp-file + rename, with a
+ * second fsync on the parent directory so the rename itself survives
+ * power loss. The keys file is created with `0o600` and the parent dir
+ * with `0o700` so a default umask doesn't expose key metadata.
+ *
+ * Single-process only: do not point two `createStation` instances at
+ * the same file or last-rename-wins will silently clobber writes. For
+ * multi-process or high-volume deployments, implement
+ * `ApiKeyStorageAdapter` against Postgres / MySQL / Redis.
+ */
+export class FileKeyStorage implements ApiKeyStorageAdapter {
+  private filePath: string;
+  private records = new Map<string, ApiKey>();
+
+  constructor(options: FileKeyStorageOptions) {
+    this.filePath = options.filePath;
+    mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+    this.load();
+  }
+
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const raw = readFileSync(this.filePath, "utf8");
+      const data = JSON.parse(raw) as ApiKey[];
+      if (Array.isArray(data)) {
+        for (const r of data) this.records.set(r.id, r);
+      }
+    } catch {
+      // Corrupt or unreadable file — start fresh rather than throwing.
+    }
+  }
+
+  private flush(): void {
+    const tmp = `${this.filePath}.tmp`;
+    const body = JSON.stringify(Array.from(this.records.values()), null, 2);
+    // Write tmp file with fsync so its bytes are durable before rename.
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+      writeSync(fd, body);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, this.filePath);
+    // fsync the parent directory so the rename's directory entry survives
+    // a crash. Best-effort: opening a directory for fsync isn't supported
+    // on every platform (notably Windows), so swallow errors.
+    try {
+      const dirFd = openSync(dirname(this.filePath), "r");
+      try {
+        fsyncSync(dirFd);
+      } finally {
+        closeSync(dirFd);
+      }
+    } catch {
+      // Platform doesn't support directory fsync; rename + tmp fsync
+      // already give us most of the durability we can offer.
+    }
+  }
+
+  insert(record: ApiKey): void {
+    this.records.set(record.id, { ...record });
+    this.flush();
+  }
+
+  findByHash(keyHash: string): ApiKey | null {
+    for (const r of this.records.values()) {
+      if (r.keyHash === keyHash) return { ...r };
+    }
+    return null;
+  }
+
+  list(): ApiKeyPublic[] {
+    return Array.from(this.records.values())
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .map((r) => {
+        const { keyHash: _h, ...rest } = r;
+        return rest;
+      });
+  }
+
+  touch(id: string, lastUsedIso: string): void {
+    const r = this.records.get(id);
+    if (!r) return;
+    r.lastUsed = lastUsedIso;
+    this.flush();
+  }
+
+  revoke(id: string): boolean {
+    const r = this.records.get(id);
+    if (!r) return false;
+    r.revoked = true;
+    this.flush();
+    return true;
+  }
+}
+
+// ─── SQLite (optional) ──────────────────────────────────────────────
 
 export interface SqliteKeyStorageOptions {
   dbPath: string;
@@ -37,13 +158,42 @@ export interface SqliteKeyStorageOptions {
   tableName?: string;
 }
 
+// Loaded lazily from `better-sqlite3` so the package isn't required at
+// install time. Users who don't construct SqliteKeyStorage never pay for it.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BetterSqlite3Module = any;
+let cachedBetterSqlite3: BetterSqlite3Module | null = null;
+
+function loadBetterSqlite3(): BetterSqlite3Module {
+  if (cachedBetterSqlite3) return cachedBetterSqlite3;
+  try {
+    const requireFn = createRequire(import.meta.url);
+    cachedBetterSqlite3 = requireFn("better-sqlite3");
+    return cachedBetterSqlite3;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `SqliteKeyStorage requires the optional 'better-sqlite3' package, ` +
+        `which isn't installed. Install it with:\n` +
+        `  npm install better-sqlite3\n` +
+        `Or use FileKeyStorage (default) / MemoryKeyStorage instead.\n` +
+        `Underlying error: ${reason}`,
+    );
+  }
+}
+
 /**
- * Default ApiKeyStorageAdapter backed by better-sqlite3. Used by the Station
- * server when no `keyStorage` is configured. For Postgres / MySQL / Redis,
- * implement `ApiKeyStorageAdapter` and pass it to `KeyStore` directly.
+ * Optional ApiKeyStorageAdapter backed by better-sqlite3. Requires the
+ * `better-sqlite3` package to be installed separately — Station Kit no
+ * longer ships it as a hard dependency.
+ *
+ * Prefer `FileKeyStorage` (the default) unless you specifically need
+ * sqlite features (concurrent reads from multiple processes, large
+ * key catalogs, etc.).
  */
 export class SqliteKeyStorage implements ApiKeyStorageAdapter {
-  private db: Database.Database;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private db: any;
   private table: string;
 
   constructor(options: SqliteKeyStorageOptions) {
@@ -52,6 +202,7 @@ export class SqliteKeyStorage implements ApiKeyStorageAdapter {
       throw new Error(`Invalid table name "${tableName}"`);
     }
     this.table = tableName;
+    const Database = loadBetterSqlite3();
     this.db = new Database(options.dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.exec(`
@@ -186,14 +337,18 @@ export class KeyStore {
 
   /**
    * Pass an `ApiKeyStorageAdapter` for any backend. The string overload is
-   * retained for backwards compatibility — it constructs a SqliteKeyStorage
-   * at the given path.
+   * retained for backwards compatibility — it constructs a FileKeyStorage
+   * at the given path. (Previously this returned a SqliteKeyStorage; SQLite
+   * is now opt-in to avoid native build dependencies.)
    */
-  constructor(storageOrDbPath: ApiKeyStorageAdapter | string) {
-    if (typeof storageOrDbPath === "string") {
-      this.storage = new SqliteKeyStorage({ dbPath: storageOrDbPath });
+  constructor(storageOrPath: ApiKeyStorageAdapter | string) {
+    if (typeof storageOrPath === "string") {
+      const filePath = storageOrPath.endsWith(".db")
+        ? storageOrPath.replace(/\.db$/, ".json")
+        : storageOrPath;
+      this.storage = new FileKeyStorage({ filePath });
     } else {
-      this.storage = storageOrDbPath;
+      this.storage = storageOrPath;
     }
   }
 

package/src/server/index.ts

@@ -18,13 +18,13 @@ import { ensureStationDir } from "../station-dir.js";
 import { WebSocketHub } from "./ws.js";
 import { SSEHub } from "./sse.js";
 import { LogBuffer } from "./log-buffer.js";
-import { LogStore } from "./log-store.js";
+import { LogStore, FileLogStorage } from "./log-store.js";
 import { StationSignalSubscriber, StationBroadcastSubscriber } 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 { KeyStore, SqliteKeyStorage } from "./auth/keys.js";
+import { KeyStore, FileKeyStorage } from "./auth/keys.js";
 import { verifySessionToken, verifyCredentials, createSessionToken, type SessionConfig } from "./auth/session.js";
 import { authResolver } from "./middleware/auth.js";
 import { requireScope } from "./middleware/scope-guard.js";
@@ -43,6 +43,7 @@ import { v1ExpressionRoutes } from "./routes/v1/expressions.js";
 
 export {
   KeyStore,
+  FileKeyStorage,
   SqliteKeyStorage,
   MemoryKeyStorage,
 } from "./auth/keys.js";
@@ -50,8 +51,19 @@ export type {
   ApiKey,
   ApiKeyPublic,
   ApiKeyStorageAdapter,
+  FileKeyStorageOptions,
   SqliteKeyStorageOptions,
 } from "./auth/keys.js";
+export {
+  LogStore,
+  FileLogStorage,
+  MemoryLogStorage,
+} from "./log-store.js";
+export type {
+  LogStorageAdapter,
+  FileLogStorageOptions,
+} from "./log-store.js";
+export type { LogEntry } from "./log-buffer.js";
 
 export interface StationInstance {
   start(): Promise<void>;
@@ -69,10 +81,17 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
 
   const { dataDir } = ensureStationDir(cwd, config.stationDir);
 
+  warnIfLegacySqliteFiles(dataDir);
+
   const wsHub = new WebSocketHub();
   const sseHub = new SSEHub();
   const logBuffer = new LogBuffer();
-  const logStore = new LogStore(resolve(dataDir, "station-logs.db"));
+  const logStore = new LogStore(
+    config.logStorage ?? new FileLogStorage({
+      filePath: resolve(dataDir, "station-logs.jsonl"),
+      onError: (err) => console.error("[station] log write failed:", err),
+    }),
+  );
 
   // Auth: create KeyStore and SessionConfig if auth is configured
   let keyStore: KeyStore | undefined;
@@ -80,7 +99,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
 
   if (config.auth) {
     const storage = config.auth.keyStorage
-      ?? new SqliteKeyStorage({ dbPath: resolve(dataDir, "station-keys.db") });
+      ?? new FileKeyStorage({ filePath: resolve(dataDir, "station-keys.json") });
     keyStore = new KeyStore(storage);
     sessionConfig = {
       username: config.auth.username,
@@ -401,7 +420,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       }
       wsHub.close();
       sseHub.close();
-      logStore.close();
+      await logStore.close();
       await keyStore?.close();
       if (httpServer) {
         httpServer.close();
@@ -409,3 +428,27 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     },
   };
 }
+
+// Existing deployments that ran older Station versions persisted keys
+// to `station-keys.db` (SQLite) and run logs to `station-logs.db`. The
+// 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 warnIfLegacySqliteFiles(dataDir: string): void {
+  const legacy: { file: string; replacement: string }[] = [
+    { file: "station-keys.db", replacement: "station-keys.json" },
+    { file: "station-logs.db", replacement: "station-logs.jsonl" },
+  ];
+  for (const { file, replacement } of legacy) {
+    const legacyPath = resolve(dataDir, file);
+    if (!existsSync(legacyPath)) continue;
+    const replacementPath = resolve(dataDir, replacement);
+    if (existsSync(replacementPath)) continue;
+    console.warn(
+      `[station] Legacy ${file} detected at ${legacyPath} but no ${replacement} found. ` +
+      `Station no longer reads SQLite-backed defaults; data in ${file} will not be loaded. ` +
+      `If you need the contents, export them with the better-sqlite3 CLI before upgrading. ` +
+      `To suppress this warning, delete or rename ${file}.`,
+    );
+  }
+}

package/src/server/log-store.ts

@@ -1,56 +1,207 @@
-import Database from "better-sqlite3";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import type { LogEntry } from "./log-buffer.js";
 
-export class LogStore {
-  private db: Database.Database;
-  private insertStmt: Database.Statement;
-  private selectStmt: Database.Statement;
-
-  constructor(dbPath: string) {
-    this.db = new Database(dbPath);
-    this.db.pragma("journal_mode = WAL");
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS logs (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        run_id TEXT NOT NULL,
-        signal_name TEXT NOT NULL,
-        level TEXT NOT NULL,
-        message TEXT NOT NULL,
-        timestamp TEXT NOT NULL
-      )
-    `);
-    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_logs_run_id ON logs(run_id)`);
-
-    this.insertStmt = this.db.prepare(
-      `INSERT INTO logs (run_id, signal_name, level, message, timestamp) VALUES (?, ?, ?, ?, ?)`,
-    );
-    this.selectStmt = this.db.prepare(
-      `SELECT run_id, signal_name, level, message, timestamp FROM logs WHERE run_id = ? ORDER BY id`,
+/**
+ * Pluggable storage backend for run logs. Implementations only persist
+ * and query records — bounded in-memory buffering for live UI streams
+ * lives in `LogBuffer`. May be sync or async; the LogStore wrapper
+ * normalizes both.
+ *
+ * Contract for implementers:
+ *
+ * - **`add(entry)`** is treated as fire-and-forget at the LogStore
+ *   boundary. Signal runners never block on log writes. Adapters that
+ *   need durability guarantees (queues, retries, batching) should
+ *   implement that internally; thrown errors and rejected promises are
+ *   caught and surfaced via the LogStore's `onError` hook (if set) but
+ *   never rethrown to the caller.
+ * - **`get(runId)`** must return entries for that run in append order
+ *   (oldest first). Routes that aggregate across runs may re-sort by
+ *   timestamp, but per-run ordering is the adapter's responsibility.
+ * - **`close?()`** is called once on graceful shutdown. Use it to flush
+ *   any in-flight buffers. It is NOT called on `SIGKILL` / OOM kill —
+ *   adapters that must guarantee durability per write should not rely
+ *   on it.
+ *
+ * Single-process semantics: the built-in `FileLogStorage` is safe for a
+ * single Node process. Running multiple processes against the same file
+ * path WILL produce interleaved bytes and lost entries — use a real
+ * database adapter (Postgres, MySQL, Redis, etc.) for multi-process or
+ * distributed deployments.
+ */
+export interface LogStorageAdapter {
+  add(entry: LogEntry): Promise<void> | void;
+  get(runId: string): Promise<LogEntry[]> | LogEntry[];
+  close?(): Promise<void> | void;
+}
+
+// ─── File-backed default ────────────────────────────────────────────
+
+export interface FileLogStorageOptions {
+  filePath: string;
+  /**
+   * Called when a background write to the underlying file fails. Use
+   * this to surface persistence problems (disk full, permission denied,
+   * etc.) to your monitoring system. If unset, write failures are
+   * silently dropped — acceptable for local dev, NOT for production.
+   */
+  onError?: (err: unknown) => void;
+}
+
+/**
+ * File-backed log storage using append-only JSONL framing. Each line is
+ * a JSON-serialized `LogEntry`; existing entries are loaded into memory
+ * on construction; appends are serialized through an async write queue
+ * so concurrent writers can't interleave bytes within one process.
+ *
+ * No native dependencies — works on any Node 18+ install.
+ *
+ * **Production caveats** (in order of severity):
+ *
+ * 1. **Single-process only.** Two Node processes appending to the same
+ *    file WILL interleave bytes once individual JSON lines exceed the
+ *    OS pipe buffer (4 KB on Linux), corrupting the file.
+ * 2. **Best-effort durability.** Writes are queued and flushed via
+ *    `fs.appendFile`; on `SIGKILL` / OOM kill, in-flight writes are lost.
+ *    Set `onError` to surface fs failures.
+ * 3. **Unbounded memory on replay.** The whole file is loaded into a
+ *    Map on startup. For high-volume deployments (gigabytes of logs)
+ *    use a database-backed adapter instead.
+ *
+ * For multi-process, distributed, or high-durability deployments,
+ * implement `LogStorageAdapter` against Postgres / MySQL / Redis / S3.
+ */
+export class FileLogStorage implements LogStorageAdapter {
+  private path: string;
+  private byRunId = new Map<string, LogEntry[]>();
+  private writeQueue: Promise<void> = Promise.resolve();
+  private onError: (err: unknown) => void;
+
+  constructor(options: FileLogStorageOptions) {
+    // Backwards compat: callers used to pass `.db` paths for the sqlite store.
+    // Transparently swap to `.jsonl` so existing config files keep working.
+    this.path = options.filePath.endsWith(".db")
+      ? options.filePath.replace(/\.db$/, ".jsonl")
+      : options.filePath;
+    this.onError = options.onError ?? (() => {});
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    this.replay();
+  }
+
+  private replay(): void {
+    if (!existsSync(this.path)) return;
+    let content: string;
+    try {
+      content = readFileSync(this.path, "utf8");
+    } catch (err) {
+      this.onError(err);
+      return;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line) as LogEntry;
+        this.indexEntry(entry);
+      } catch {
+        // Skip malformed line; a partial write may have left a truncated tail.
+      }
+    }
+  }
+
+  private indexEntry(entry: LogEntry): void {
+    let entries = this.byRunId.get(entry.runId);
+    if (!entries) {
+      entries = [];
+      this.byRunId.set(entry.runId, entries);
+    }
+    entries.push(entry);
+  }
+
+  add(entry: LogEntry): void {
+    this.indexEntry(entry);
+    const line = JSON.stringify(entry) + "\n";
+    this.writeQueue = this.writeQueue.then(
+      () => appendFile(this.path, line, { mode: 0o600 }).catch((err) => {
+        this.onError(err);
+      }),
     );
   }
 
+  get(runId: string): LogEntry[] {
+    return this.byRunId.get(runId) ?? [];
+  }
+
+  async close(): Promise<void> {
+    await this.writeQueue;
+  }
+}
+
+// ─── In-memory storage for tests / ephemeral deployments ────────────
+
+export class MemoryLogStorage implements LogStorageAdapter {
+  private byRunId = new Map<string, LogEntry[]>();
+
   add(entry: LogEntry): void {
-    this.insertStmt.run(entry.runId, entry.signalName, entry.level, entry.message, entry.timestamp);
+    let entries = this.byRunId.get(entry.runId);
+    if (!entries) {
+      entries = [];
+      this.byRunId.set(entry.runId, entries);
+    }
+    entries.push(entry);
   }
 
   get(runId: string): LogEntry[] {
-    const rows = this.selectStmt.all(runId) as Array<{
-      run_id: string;
-      signal_name: string;
-      level: string;
-      message: string;
-      timestamp: string;
-    }>;
-    return rows.map((row) => ({
-      runId: row.run_id,
-      signalName: row.signal_name,
-      level: row.level as "stdout" | "stderr",
-      message: row.message,
-      timestamp: row.timestamp,
-    }));
-  }
-
-  close(): void {
-    this.db.close();
+    return this.byRunId.get(runId) ?? [];
+  }
+}
+
+// ─── LogStore — thin wrapper that delegates to an adapter ───────────
+
+/**
+ * LogStore is the consumer-facing handle that wraps a `LogStorageAdapter`.
+ * It exists so signal runners and route handlers can interact with a
+ * single concrete type, while the underlying persistence is swappable.
+ *
+ * `add` is fire-and-forget — adapter promises are caught at this boundary
+ * so a slow or failing log backend can never block (or crash) a signal
+ * runner. `get` always returns a Promise so callers can transparently
+ * support async backends (Postgres, Redis, etc.).
+ */
+export class LogStore {
+  private storage: LogStorageAdapter;
+
+  /**
+   * Pass a `LogStorageAdapter` for any backend. The string overload is
+   * a shortcut for `new FileLogStorage({ filePath })` — useful for
+   * local dev and the default Station data directory.
+   */
+  constructor(storageOrPath: LogStorageAdapter | string) {
+    if (typeof storageOrPath === "string") {
+      this.storage = new FileLogStorage({ filePath: storageOrPath });
+    } else {
+      this.storage = storageOrPath;
+    }
+  }
+
+  add(entry: LogEntry): void {
+    try {
+      const result = this.storage.add(entry);
+      if (result && typeof (result as Promise<void>).catch === "function") {
+        (result as Promise<void>).catch(() => {});
+      }
+    } catch {
+      // Swallow sync throws; a broken log adapter must not crash signal runs.
+    }
+  }
+
+  async get(runId: string): Promise<LogEntry[]> {
+    return await this.storage.get(runId);
+  }
+
+  async close(): Promise<void> {
+    if (this.storage.close) await this.storage.close();
   }
 }

package/src/server/routes/broadcasts.ts

@@ -123,7 +123,9 @@ export function broadcastRoutes(deps: BroadcastDeps) {
     const allLogs: Array<{ runId: string; signalName: string; level: string; message: string; timestamp: string; nodeName: string }> = [];
     for (const nr of nodes) {
       if (nr.signalRunId) {
-        const logs = deps.logStore?.get(nr.signalRunId) ?? deps.logBuffer?.get(nr.signalRunId) ?? [];
+        const logs = deps.logStore
+          ? await deps.logStore.get(nr.signalRunId)
+          : deps.logBuffer?.get(nr.signalRunId) ?? [];
         for (const log of logs) {
           allLogs.push({ ...log, nodeName: nr.nodeName });
         }

package/src/server/routes/runs.ts

@@ -120,7 +120,7 @@ export function runRoutes(deps: RunDeps) {
 
   app.get("/runs/:id/logs", async (c) => {
     const id = c.req.param("id");
-    const logs = deps.logStore?.get(id) ?? deps.logBuffer.get(id);
+    const logs = deps.logStore ? await deps.logStore.get(id) : deps.logBuffer.get(id);
     return c.json({ data: logs });
   });