bunqueue-dashboard 0.0.45 → 0.0.47

package/agent/compiledRuntime.ts

@@ -0,0 +1,27 @@
+/** Bun uses a POSIX virtual root and a drive-qualified Windows virtual root. */
+function compiledRoot(moduleUrl: string): URL | null {
+  const url = new URL(moduleUrl);
+  if (url.protocol !== 'file:') return null;
+  // Windows import.meta.url escapes the virtual root as /B:/%7EBUN/root/.
+  let pathname: string;
+  try { pathname = decodeURIComponent(url.pathname); } catch { return null; }
+  for (const marker of ['/$bunfs/root/', '/~BUN/root/']) {
+    const index = pathname.indexOf(marker);
+    if (index !== -1) {
+      url.pathname = pathname.slice(0, index + marker.length);
+      url.search = '';
+      url.hash = '';
+      return url;
+    }
+  }
+  return null;
+}
+
+export function isCompiledModule(moduleUrl: string): boolean {
+  return compiledRoot(moduleUrl) !== null;
+}
+
+export function compiledWorkerUrl(moduleUrl: string, path: string): string | null {
+  const root = compiledRoot(moduleUrl);
+  return root ? new URL(path, root).href : null;
+}

package/agent/db/boundedStream.ts

@@ -0,0 +1,18 @@
+/** Bound both pipe buffering and the final allocation before decoding a child response. */
+export async function readBoundedBytes(stream: ReadableStream<Uint8Array>, limit: number): Promise<Buffer> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      bytes += next.value.byteLength;
+      if (bytes > limit) throw new Error('Database process output exceeded its byte limit');
+      chunks.push(next.value);
+    }
+    return Buffer.concat(chunks, bytes);
+  } finally {
+    reader.releaseLock();
+  }
+}

package/agent/db/exportTimeout.ts

@@ -1,4 +1,5 @@
 import { validateWorkerBounds } from './core';
+import type { DatabaseWorker } from './processWorker';
 import { createExportWorker } from './workerFactory';
 import {
   DB_EXPORT_MAX_ROWS,
@@ -14,7 +15,7 @@ import {
 
 let liveExportWorkers = 0;
 
-/** Export workers alive now, including abandoned SQLite calls still unwinding. */
+/** Export workers alive now, including cancelled children being reaped. */
 export const exportWorkerLoad = (): number => liveExportWorkers;
 
 function validatedWorkerExport(value: unknown, expectedTable: string): DbCsvExport {
@@ -67,11 +68,11 @@ export async function exportWithTimeout(
   signal?.throwIfAborted();
   if (liveExportWorkers >= MAX_CONCURRENT_EXPORTS) {
     throw new DbExportBusyError(
-      'A database export is already running. Wait for it to finish, or restart the agent if it was abandoned.'
+      'A database export is already running. Retry after it finishes.'
     );
   }
 
-  let worker: Worker;
+  let worker: DatabaseWorker;
   try {
     worker = createExportWorker();
   } catch (error) {
@@ -117,7 +118,7 @@ export async function exportWithTimeout(
           reject(new DbExportUnavailableError('Database export worker exited unexpectedly'));
         }
       });
-      worker.addEventListener('message', (event: MessageEvent) => {
+      worker.addEventListener('message', (event) => {
         if (settled) return;
         settled = true;
         cleanup();
@@ -147,7 +148,7 @@ export async function exportWithTimeout(
           );
         }
       });
-      worker.addEventListener('error', (event: ErrorEvent) => {
+      worker.addEventListener('error', (event) => {
         if (settled) return;
         event.preventDefault?.();
         abandon(
@@ -161,7 +162,7 @@ export async function exportWithTimeout(
         () =>
           abandon(
             new DbExportUnavailableError(
-              `Database export exceeded the ${DB_EXPORT_TIMEOUT_MS / 1000}s time limit and was abandoned (SQLite may keep scanning until the worker exits).`
+              `Database export exceeded the ${DB_EXPORT_TIMEOUT_MS / 1000}s time limit and was terminated.`
             )
           ),
         DB_EXPORT_TIMEOUT_MS
@@ -186,5 +187,6 @@ export async function exportWithTimeout(
     });
   } finally {
     worker.terminate();
+    if (worker.exited) { await worker.exited; release(); }
   }
 }

package/agent/db/processWorker.ts

@@ -0,0 +1,121 @@
+import { fileURLToPath } from 'node:url';
+import { deserialize, serialize } from 'node:v8';
+import { readBoundedBytes } from './boundedStream';
+import { isCompiledModule } from '../compiledRuntime';
+
+type WorkerEvents = {
+  message: { data: unknown };
+  error: { message: string; preventDefault?: () => void };
+  close: Record<string, never>;
+};
+
+/** Minimal Worker-compatible seam retained for existing integrations and fault injection. */
+export interface DatabaseWorker {
+  addEventListener<K extends keyof WorkerEvents>(type: K, listener: (event: WorkerEvents[K]) => void): void;
+  postMessage(request: unknown): void;
+  terminate(): void;
+  /** Production workers resolve only after the OS has reaped the child. */
+  exited?: Promise<void>;
+}
+
+const active = new Set<DatabaseProcessWorker>();
+export const databaseProcessLoad = (): number => active.size;
+export function terminateDatabaseProcesses(): void {
+  for (const worker of active) worker.terminate();
+}
+process.once('exit', terminateDatabaseProcesses);
+
+/** Unlike Worker.terminate(), SIGKILL interrupts synchronous sqlite3_step. */
+export class DatabaseProcessWorker implements DatabaseWorker {
+  private listeners = new Map<string, Array<(event: unknown) => void>>();
+  private child?: Bun.Subprocess<'ignore', 'pipe', 'ignore' | 'inherit'>;
+  private stopped = false;
+  private started = false;
+  private closed = false;
+  private resolveExit!: () => void;
+  readonly exited = new Promise<void>((resolve) => { this.resolveExit = resolve; });
+  get pid(): number | undefined { return this.child?.pid; }
+
+  constructor(private readonly workerUrl?: string) {}
+
+  addEventListener<K extends keyof WorkerEvents>(type: K, listener: (event: WorkerEvents[K]) => void): void {
+    this.listeners.set(type, [...(this.listeners.get(type) ?? []), (event) => listener(event as WorkerEvents[K])]);
+  }
+
+  postMessage(request: unknown): void {
+    if (this.started || this.stopped) throw new Error('Database process is already used');
+    this.started = true;
+    active.add(this);
+    void this.run(request);
+  }
+
+  terminate(): void {
+    this.stopped = true;
+    if (this.child && this.child.exitCode === null) this.child.kill('SIGKILL');
+    if (!this.started) this.close();
+  }
+
+  private emit<K extends keyof WorkerEvents>(type: K, event: WorkerEvents[K]): void {
+    for (const listener of this.listeners.get(type) ?? []) listener(event);
+  }
+
+  private close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    active.delete(this);
+    this.resolveExit();
+    this.emit('close', {});
+    this.listeners.clear();
+  }
+
+  private async run(request: unknown): Promise<void> {
+    try {
+      const message = request as Record<string, unknown>;
+      const operation = message.operation ? request : message.kind === 'export'
+        ? { operation: 'dbExportCsv', args: [message.path, message.table, message.orderBy, message.dir, message.filter] }
+        : { operation: 'dbQuery', args: [message.path, message.sql] };
+      // Legacy overrides never handled the newly isolated browse/workflow operations.
+      const input = serialize(this.workerUrl !== undefined && !message.operation
+        ? { customWorkerUrl: this.workerUrl, request }
+        : operation);
+      if (input.byteLength > 128 * 1024) throw new Error('Database request exceeds 128 KiB');
+      const compiled = isCompiledModule(import.meta.url);
+      const trace = process.env.BQ_DB_PROCESS_TRACE === '1';
+      if (trace) console.error(JSON.stringify({ component: 'db-process', phase: 'spawn', module: import.meta.url, compiled, executable: process.execPath }));
+      let delivered = false;
+      this.child = Bun.spawn(compiled
+        ? [process.execPath, '--bq-db-read']
+        : [process.execPath, fileURLToPath(new URL('./readProcessMain.ts', import.meta.url))], {
+        // Database readers need no managed-server tokens or cloud credentials.
+        env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMPDIR: process.env.TMPDIR, BQ_DB_PROCESS_TRACE: trace ? '1' : undefined },
+        stdin: 'ignore', stdout: 'pipe', stderr: trace ? 'inherit' : 'ignore',
+        ipc: (message, subprocess) => {
+          if (message !== 'ready' || delivered || this.stopped) return;
+          delivered = true;
+          if (trace) console.error(JSON.stringify({ component: 'db-process', phase: 'ready', pid: subprocess.pid }));
+          try { subprocess.send(input); } catch { this.terminate(); }
+        },
+      });
+      const [output, code] = await Promise.all([
+        readBoundedBytes(this.child.stdout, 32 * 1024 * 1024), this.child.exited,
+      ]);
+      if (trace) console.error(JSON.stringify({ component: 'db-process', phase: 'exited', code, bytes: output.byteLength }));
+      if (this.stopped) return;
+      if (code !== 0) throw new Error(`Database process exited with code ${code}`);
+      const response = deserialize(output) as Record<string, unknown>;
+      if (message.kind === 'export' && response.ok && !Object.hasOwn(response, 'export') && Object.hasOwn(response, 'result')) {
+        response.export = response.result;
+      }
+      // The process has exited before any caller can release its lifecycle lease.
+      this.emit('message', { data: response });
+    } catch (error) {
+      this.terminate();
+      if (this.child) await this.child.exited;
+      this.emit('error', { message: error instanceof Error ? error.message : 'Database process failed' });
+    } finally {
+      try { this.child?.disconnect(); } catch { /* child already closed its IPC channel */ }
+      this.child = undefined;
+      this.close();
+    }
+  }
+}

package/agent/db/queryTimeout.ts

@@ -1,76 +1,88 @@
+import { ReadAdmission } from './readAdmission';
 import { createQueryWorker } from './workerFactory';
+import type { ReadArguments, ReadOperation, ReadResult } from './readOperations';
 import {
-  MAX_CONCURRENT_QUERIES,
-  MissingDbError,
-  QUERY_TIMEOUT_MS,
-  type DbQueryResult,
+  DbReadUnavailableError,
+  MissingDbError, QUERY_TIMEOUT_MS, type DbQueryResult,
 } from './types';
 
-let liveQueryWorkers = 0;
+const admission = new ReadAdmission();
+/** Active database read processes, including children being reaped after cancellation. */
+export const queryWorkerLoad = (): number => admission.load;
 
-/** Query worker threads currently alive, including timed-out queries. */
-export const queryWorkerLoad = (): number => liveQueryWorkers;
+export function queryWithTimeout(path: string, sql: string, signal?: AbortSignal): Promise<DbQueryResult> {
+  return runReadWorker({ path, sql }, signal);
+}
 
-export async function queryWithTimeout(path: string, sql: string): Promise<DbQueryResult> {
-  if (liveQueryWorkers >= MAX_CONCURRENT_QUERIES) {
-    throw new Error(
-      `Too many queries running (${liveQueryWorkers}/${MAX_CONCURRENT_QUERIES}). A previous query timed out and is still running inside SQLite — wait for it to finish, or restart the agent.`
-    );
-  }
-  let worker: Worker;
+/** Every HTTP SQLite read shares the same bounded admission pool. */
+export function readWithTimeout<K extends ReadOperation>(
+  operation: K, args: ReadArguments<K>, signal?: AbortSignal,
+  timeoutMs = QUERY_TIMEOUT_MS
+): Promise<ReadResult<K>> {
+  return runReadWorker({ operation, args }, signal, timeoutMs, true);
+}
+
+async function runReadWorker<T>(request: unknown, signal?: AbortSignal, timeoutMs = QUERY_TIMEOUT_MS, queue = false): Promise<T> {
+  const limit = Math.max(1, Math.min(timeoutMs, QUERY_TIMEOUT_MS));
+  const deadline = performance.now() + limit;
+  const ticket = admission.acquire(queue, deadline, signal);
+  const release = typeof ticket === 'function' ? ticket : await ticket;
+  let worker;
   try {
+    signal?.throwIfAborted();
+    if (performance.now() >= deadline) throw new Error('Database read exceeded the time limit while waiting for capacity');
     worker = createQueryWorker();
   } catch (error) {
-    throw new Error(`Query worker unavailable: ${(error as Error).message ?? String(error)}`);
+    release();
+    throw new DbReadUnavailableError(`Query worker unavailable: ${(error as Error).message}`);
   }
-  liveQueryWorkers++;
-  let released = false;
-  const release = () => {
-    if (released) return;
-    released = true;
-    liveQueryWorkers--;
-  };
-  worker.addEventListener('close', release);
+  let cleanup = () => {};
   try {
-    return await new Promise<DbQueryResult>((resolve, reject) => {
+    return await new Promise<T>((resolve, reject) => {
       let settled = false;
-      const timer = setTimeout(() => {
+      const fail = (error: Error) => {
         if (settled) return;
         settled = true;
+        cleanup();
         worker.terminate();
-        reject(
-          new Error(
-            `Query exceeded the ${QUERY_TIMEOUT_MS / 1000}s time limit and was abandoned (it may keep running inside SQLite until it completes).`
-          )
-        );
-      }, QUERY_TIMEOUT_MS);
-      worker.addEventListener('message', (event: MessageEvent) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
+        reject(error);
+      };
+      const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error('Database read aborted'));
+      const timer = setTimeout(() => fail(new DbReadUnavailableError(
+        `Query exceeded the ${limit / 1000}s time limit and was terminated.`
+      )), Math.max(1, deadline - performance.now()));
+      cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); };
+      worker.addEventListener('close', () => {
         release();
-        const response = event.data as {
-          ok: boolean;
-          result?: DbQueryResult;
-          error?: string;
-          missing?: boolean;
-        };
-        if (response.ok && response.result) resolve(response.result);
-        else if (response.missing) {
-          reject(new MissingDbError(response.error ?? 'Database not found'));
-        } else reject(new Error(response.error ?? 'Query failed'));
+        if (!settled) fail(new DbReadUnavailableError('Query worker exited unexpectedly'));
       });
-      worker.addEventListener('error', (event: ErrorEvent) => {
+      worker.addEventListener('message', (event) => {
         if (settled) return;
+        const response = event.data as { ok?: unknown; result?: unknown; missing?: unknown; error?: unknown } | null;
+        if (!response || typeof response !== 'object' || typeof response.ok !== 'boolean') {
+          fail(new DbReadUnavailableError('Query worker returned a malformed response'));
+          return;
+        }
         settled = true;
-        clearTimeout(timer);
-        release();
+        cleanup();
+        if (!worker.exited) release();
+        if (response.ok && Object.hasOwn(response, 'result')) resolve(response.result as T);
+        else if (response.missing === true) reject(new MissingDbError(typeof response.error === 'string' ? response.error : 'Database not found'));
+        else reject(new Error(typeof response.error === 'string' ? response.error : 'Query failed'));
+      });
+      worker.addEventListener('error', (event) => {
         event.preventDefault?.();
-        reject(new Error(`Query worker failed: ${event.message || 'unknown worker error'}`));
+        fail(new DbReadUnavailableError(`Query worker failed: ${event.message || 'unknown worker error'}`));
       });
-      worker.postMessage({ path, sql });
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) { onAbort(); return; }
+      try { worker.postMessage(request); } catch (error) {
+        fail(new DbReadUnavailableError(`Could not start database read: ${(error as Error).message}`));
+      }
     });
   } finally {
+    cleanup();
     worker.terminate();
+    if (worker.exited) { await worker.exited; release(); }
   }
 }

package/agent/db/readAdmission.ts

@@ -0,0 +1,53 @@
+import { DbReadBusyError, DbReadUnavailableError, MAX_CONCURRENT_QUERIES } from './types';
+
+type Release = () => void;
+interface Waiter { admit(): void; cancel(error: unknown): void }
+const MAX_PENDING_READS = 32;
+
+/** Fair, bounded admission absorbs a page's parallel polls without spawning more SQLite processes. */
+export class ReadAdmission {
+  private active = 0;
+  private waiting: Waiter[] = [];
+  get load(): number { return this.active; }
+  get pending(): number { return this.waiting.length; }
+
+  acquire(queue: boolean, deadline: number, signal?: AbortSignal): Release | Promise<Release> {
+    signal?.throwIfAborted();
+    if (this.active < MAX_CONCURRENT_QUERIES) return this.reserve();
+    if (!queue || this.waiting.length >= MAX_PENDING_READS) {
+      throw new DbReadBusyError(`Too many queries running (${this.active}/${MAX_CONCURRENT_QUERIES}). Retry after a current read finishes.`);
+    }
+    return new Promise<Release>((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        const index = this.waiting.indexOf(waiter);
+        if (index !== -1) this.waiting.splice(index, 1);
+      };
+      const waiter: Waiter = {
+        admit: () => { if (!settled) { cleanup(); resolve(this.reserve()); } },
+        cancel: (error) => { if (!settled) { cleanup(); reject(error); } },
+      };
+      const onAbort = () => waiter.cancel(signal?.reason instanceof Error ? signal.reason : new Error('Database read aborted'));
+      const timer = setTimeout(() => waiter.cancel(new DbReadUnavailableError(
+        'Database read exceeded the time limit while waiting for capacity'
+      )), Math.max(1, deadline - performance.now()));
+      this.waiting.push(waiter);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  }
+
+  private reserve(): Release {
+    this.active++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.active--;
+      this.waiting[0]?.admit();
+    };
+  }
+}

package/agent/db/readOperations.ts

@@ -0,0 +1,27 @@
+import { dbExportCsv } from './csvExport';
+import { dbQuery } from './query';
+import { dbInfo, dbSchema } from './schema';
+import { dbCell, dbRows, dbTables } from './tables';
+import { workflowExecution } from '../workflow/detail';
+import { workflowExecutions } from '../workflow/list';
+import { workflowStats } from '../workflow/stats';
+
+/** Fixed allowlist shared by the typed caller and isolated SQLite process. */
+export const READ_OPERATIONS = {
+  dbQuery, dbExportCsv, dbInfo, dbSchema, dbCell, dbRows, dbTables,
+  workflowExecution, workflowExecutions, workflowStats,
+};
+
+export type ReadOperation = keyof typeof READ_OPERATIONS;
+export type ReadArguments<K extends ReadOperation> = Parameters<(typeof READ_OPERATIONS)[K]>;
+export type ReadResult<K extends ReadOperation> = ReturnType<(typeof READ_OPERATIONS)[K]>;
+
+export function dispatchRead(request: unknown): unknown {
+  if (!request || typeof request !== 'object') throw new Error('Invalid database read request');
+  const { operation, args } = request as { operation: string; args: unknown[] };
+  if (!Object.hasOwn(READ_OPERATIONS, operation) || !Array.isArray(args)) {
+    throw new Error('Unknown database read operation');
+  }
+  const execute = READ_OPERATIONS[operation as ReadOperation] as (...args: unknown[]) => unknown;
+  return execute(...args);
+}

package/agent/db/readProcessMain.ts

@@ -0,0 +1,64 @@
+import { deserialize, serialize } from 'node:v8';
+import { compiledWorkerUrl } from '../compiledRuntime';
+
+/** One request, one readonly connection, one process. Also bundled into the standalone server. */
+export async function runDatabaseReadProcess(): Promise<void> {
+  let response: unknown;
+  let worker: Worker | undefined;
+  const trace = (phase: string, details: Record<string, unknown> = {}): void => {
+    if (process.env.BQ_DB_PROCESS_TRACE === '1') console.error(JSON.stringify({ component: 'db-supervisor', phase, ...details }));
+  };
+  try {
+    trace('started', { module: import.meta.url, ipc: Boolean(process.send), connected: process.connected });
+    if (!process.send || !process.connected) throw new Error('Database process requires an IPC parent');
+    // Keep request delivery and parent liveness separate from standard streams.
+    // Disconnect also covers abrupt parent death.
+    process.once('disconnect', () => process.exit(1));
+    const pending = new Promise<unknown>((resolve) => process.once('message', resolve));
+    process.send('ready');
+    const message = await pending;
+    trace('request-received');
+    if (!(message instanceof Uint8Array) || message.byteLength > 128 * 1024) {
+      throw new Error('Invalid database request or request exceeds 128 KiB');
+    }
+    let input: unknown = deserialize(message);
+    let workerUrl = compiledWorkerUrl(import.meta.url, 'agent/dbReadWorker.js')
+      ?? new URL('../dbReadWorker.ts', import.meta.url).href;
+    let customWorker = false;
+    if (input && typeof input === 'object' && 'customWorkerUrl' in input) {
+      if (typeof input.customWorkerUrl !== 'string' || !input.customWorkerUrl || !('request' in input)) {
+        throw new Error('Invalid database worker override');
+      }
+      workerUrl = input.customWorkerUrl;
+      input = input.request;
+      customWorker = true;
+    }
+    trace('creating-worker', customWorker ? { customWorker: true } : { workerUrl });
+    worker = new Worker(workerUrl, { type: 'module' });
+    trace('worker-created');
+    response = await new Promise<unknown>((resolve, reject) => {
+      worker!.addEventListener('message', (event: MessageEvent) => { trace('worker-result'); resolve(event.data); });
+      worker!.addEventListener('error', (event: ErrorEvent) => {
+        event.preventDefault?.();
+        reject(new Error(event.message || 'Database worker failed'));
+      });
+      worker!.postMessage(input);
+    });
+  } catch (error) {
+    trace('failed');
+    response = {
+      ok: false,
+      error: error instanceof Error ? error.message : 'Database read failed',
+    };
+  }
+  const output = serialize(response);
+  await Bun.write(Bun.stdout, output.byteLength <= 32 * 1024 * 1024
+    ? output
+    : serialize({ ok: false, error: 'Database result exceeded 32 MiB' }));
+  trace('output-written', { bytes: output.byteLength });
+  // Exit the whole process, including its SQLite thread and IPC channel.
+  worker?.terminate();
+  process.exit(0);
+}
+
+if (import.meta.main) await runDatabaseReadProcess();

package/agent/db/types.ts

@@ -19,6 +19,9 @@ export class MissingDbError extends Error {
   readonly missing = true;
 }
 
+export class DbReadBusyError extends Error {}
+export class DbReadUnavailableError extends Error {}
+
 /** Maps a saturated export worker pool to HTTP 429. */
 export class DbExportBusyError extends Error {}
 

package/agent/db/workerFactory.ts

@@ -1,25 +1,27 @@
-let workerUrl = new URL('../dbQueryWorker.ts', import.meta.url).href;
+import { DatabaseProcessWorker, type DatabaseWorker } from './processWorker';
 
-const spawnWorker = (): Worker => new Worker(workerUrl, { type: 'module' });
-let queryFactory: () => Worker = spawnWorker;
-let exportFactory: () => Worker = spawnWorker;
+let workerUrl: string | undefined;
+const spawnWorker = (): DatabaseWorker => new DatabaseProcessWorker(workerUrl);
+let queryFactory: () => DatabaseWorker = spawnWorker;
+let exportFactory: () => DatabaseWorker = spawnWorker;
 
-export function createQueryWorker(): Worker {
+export function createQueryWorker(): DatabaseWorker {
   return queryFactory();
 }
 
-export function createExportWorker(): Worker {
+export function createExportWorker(): DatabaseWorker {
   return exportFactory();
 }
 
-export function setQueryWorkerUrl(url: string): void {
-  workerUrl = url;
+/** Optional legacy query/export worker override, still hosted in a killable process. */
+export function setQueryWorkerUrl(url: string | null): void {
+  workerUrl = url ?? undefined;
 }
 
-export function setQueryWorkerFactory(factory: (() => Worker) | null): void {
+export function setQueryWorkerFactory(factory: (() => DatabaseWorker) | null): void {
   queryFactory = factory ?? spawnWorker;
 }
 
-export function setExportWorkerFactory(factory: (() => Worker) | null): void {
+export function setExportWorkerFactory(factory: (() => DatabaseWorker) | null): void {
   exportFactory = factory ?? spawnWorker;
 }

package/agent/dbReadWorker.ts

@@ -0,0 +1,21 @@
+import { dispatchRead } from './db/readOperations';
+import { MissingDbError } from './db/types';
+
+declare const self: Worker;
+
+if (process.env.BQ_DB_PROCESS_TRACE === '1') console.error(JSON.stringify({ component: 'db-thread', phase: 'listening' }));
+
+// Runs inside a disposable PROCESS. Its supervisor remains responsive to IPC
+// disconnects when the agent dies, even while this thread is in sqlite3_step.
+self.addEventListener('message', (event: MessageEvent) => {
+  try {
+    const result = dispatchRead(event.data);
+    const content = result && typeof result === 'object' && 'content' in result ? result.content : null;
+    self.postMessage({ ok: true, result }, content instanceof Uint8Array && content.buffer instanceof ArrayBuffer ? [content.buffer] : []);
+  } catch (error) {
+    self.postMessage({ ok: false,
+      error: error instanceof Error ? error.message : 'Database read failed',
+      missing: error instanceof MissingDbError,
+    });
+  }
+});

package/agent/index.ts

@@ -15,6 +15,7 @@
 import { assertRequiredBunVersion } from '../scripts/bunVersion';
 import { logger } from './logger';
 import { ProcessManager } from './manager';
+import { agentConfigStore } from './manager/configStore';
 import {
   createFetchHandler,
   resolveAllowedHosts,
@@ -25,7 +26,7 @@ import { installAgentShutdown } from './shutdown';
 
 assertRequiredBunVersion();
 
-const mgr = new ProcessManager();
+const mgr = new ProcessManager(undefined, agentConfigStore());
 const PORT = Number(process.env.AGENT_PORT) || 6800;
 const allowedOrigins = resolveAllowedOrigins();
 // The agent binds loopback only, so a legitimate Host is always a loopback

package/agent/manager/configStore.ts

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { copyConfig, validateServerConfig } from './config';
+import type { ServerConfig } from './types';
+
+export interface ConfigStore {
+  load(fallback: ServerConfig): ServerConfig;
+  save(config: ServerConfig): void;
+}
+
+const MAX_CONFIG_BYTES = 1024 * 1024;
+
+/** Private atomic snapshots. Errors never include configuration secrets. */
+export class FileConfigStore implements ConfigStore {
+  constructor(readonly path: string) {}
+
+  load(fallback: ServerConfig): ServerConfig {
+    let descriptor: number;
+    try {
+      descriptor = openSync(this.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return copyConfig(fallback);
+      throw new Error('Cannot read saved agent configuration');
+    }
+    try {
+      if (fstatSync(descriptor).size > MAX_CONFIG_BYTES) throw new Error('oversize');
+      const raw = readFileSync(descriptor);
+      if (raw.byteLength > MAX_CONFIG_BYTES) throw new Error('oversize');
+      const saved = JSON.parse(raw.toString()) as { version?: unknown; config?: unknown };
+      if (saved?.version !== 1) throw new Error('unsupported format');
+      return copyConfig(validateServerConfig(saved.config));
+    } catch {
+      throw new Error('Saved agent configuration is invalid; repair or remove AGENT_CONFIG_PATH before restarting');
+    } finally {
+      closeSync(descriptor);
+    }
+  }
+
+  save(config: ServerConfig): void {
+    const content = JSON.stringify({ version: 1, config: validateServerConfig(config) }) + '\n';
+    if (Buffer.byteLength(content) > MAX_CONFIG_BYTES) throw new Error('Agent configuration exceeds 1 MiB');
+    const directory = dirname(this.path);
+    const temporary = `${this.path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    let descriptor: number | undefined;
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      descriptor = openSync(temporary, 'wx', 0o600);
+      writeFileSync(descriptor, content);
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = undefined;
+      renameSync(temporary, this.path);
+    } catch {
+      throw new Error('Cannot persist agent configuration; the change was not applied');
+    } finally {
+      if (descriptor !== undefined) closeSync(descriptor);
+      rmSync(temporary, { force: true });
+    }
+  }
+}
+
+/** Paths resolve against the launch directory, just like the database path. Use one path per agent. */
+export function agentConfigStore(env: NodeJS.ProcessEnv = process.env): FileConfigStore {
+  return new FileConfigStore(resolve(env.AGENT_CONFIG_PATH || '.bunqueue-dashboard/config.json'));
+}

package/agent/manager/process.ts

@@ -1,5 +1,6 @@
 import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
 import { ProcessLogs } from './logs';
+import type { ConfigStore } from './configStore';
 import { databaseStats } from './storage';
 import { removeSqlitePaths, validateManagedStorage } from './storageMode';
 import type {
@@ -40,7 +41,12 @@ export class ProcessManager {
   private maintenance: string | null = null;
   private output = new ProcessLogs();
 
-  constructor(private readonly stopTimeoutMs = STOP_TIMEOUT_MS) {}
+  constructor(
+    private readonly stopTimeoutMs = STOP_TIMEOUT_MS,
+    private readonly configStore?: ConfigStore
+  ) {
+    this.config = configStore?.load(this.config) ?? this.config;
+  }
 
   getConfig(): ServerConfig {
     return copyConfig(this.config);
@@ -63,6 +69,7 @@ export class ProcessManager {
       extraEnv: valid.extraEnv ?? this.config.extraEnv,
     });
     if (!sameConfig(this.config, next)) {
+      this.configStore?.save(next);
       this.config = next;
       this.configRevision = nextConfigRevision(this.configRevision);
     }

package/agent/server/databaseRoutes.ts

@@ -1,10 +1,6 @@
+import { readWithTimeout } from '../db/queryTimeout';
 import {
   type DbFilter,
-  dbCell,
-  dbInfo,
-  dbRows,
-  dbSchema,
-  dbTables,
   exportWithTimeout,
   queryWithTimeout,
 } from '../db';
@@ -105,15 +101,15 @@ export async function routeDatabaseRequest(
   admission?: ManagedDatabaseAdmission
 ): Promise<RouteResponse | Response | null> {
   if (pathname === '/db/info' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...dbInfo(path) },
+      body: { ok: true, ...(await readWithTimeout('dbInfo', [path], request.signal)) },
     }));
   }
   if (pathname === '/db/tables' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, tables: dbTables(path) },
+      body: { ok: true, tables: await readWithTimeout('dbTables', [path], request.signal) },
     }));
   }
   if (pathname.startsWith('/db/tables/') && method === 'GET') {
@@ -126,20 +122,20 @@ export async function routeDatabaseRequest(
       );
     }
     if (segments.length === 2 && subresource === 'schema') {
-      return withDatabase(dataPath, admission, (path) => ({
+      return withDatabase(dataPath, admission, async (path) => ({
         status: 200,
-        body: { ok: true, ...dbSchema(path, table) },
+        body: { ok: true, ...(await readWithTimeout('dbSchema', [path, table], request.signal)) },
       }));
     }
     if (segments.length === 2 && subresource === 'cell') {
       const query = new URL(request.url).searchParams;
       const rowid = query.get('rowid');
       if (rowid === null) throw new Error('rowid is required');
-      return withDatabase(dataPath, admission, (path) => ({
+      return withDatabase(dataPath, admission, async (path) => ({
         status: 200,
         body: {
           ok: true,
-          ...dbCell(path, table, rowid, query.get('column') ?? ''),
+          ...(await readWithTimeout('dbCell', [path, table, rowid, query.get('column') ?? ''], request.signal)),
         },
       }));
     }
@@ -147,11 +143,11 @@ export async function routeDatabaseRequest(
       return { status: 404, body: { ok: false, error: 'Not found' } };
     }
     const query = new URL(request.url).searchParams;
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
       body: {
         ok: true,
-        ...dbRows(
+        ...(await readWithTimeout('dbRows', [
           path,
           table,
           Number(query.get('limit')) || 50,
@@ -159,7 +155,7 @@ export async function routeDatabaseRequest(
           query.get('orderBy') || undefined,
           query.get('dir') === 'desc' ? 'desc' : 'asc',
           browseFilter(query)
-        ),
+        ], request.signal)),
       },
     }));
   }
@@ -171,7 +167,7 @@ export async function routeDatabaseRequest(
     })) as { sql?: string };
     return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...(await queryWithTimeout(path, sql ?? '')) },
+      body: { ok: true, ...(await queryWithTimeout(path, sql ?? '', request.signal)) },
     }));
   }
   return null;

package/agent/server/errors.ts

@@ -3,6 +3,7 @@ import {
   DbExportUnavailableError,
   MissingDbError,
 } from '../db';
+import { DbReadBusyError, DbReadUnavailableError } from '../db/types';
 import { safeErrorMessage } from '../errorMessage';
 import { QueueOperationsUnavailableError } from '../queue/types';
 import { WorkflowRuntimeUnavailableError } from '../workflow/runtime';
@@ -26,6 +27,8 @@ export function errorStatus(error: unknown): number {
   try {
     if (error instanceof AgentLifecycleClosedError) return 503;
     if (error instanceof MissingDbError) return 404;
+    if (error instanceof DbReadBusyError) return 429;
+    if (error instanceof DbReadUnavailableError) return 503;
     if (error instanceof DbExportBusyError) return 429;
     if (error instanceof DbExportUnavailableError) return 503;
     if (error instanceof QueueOperationsUnavailableError) {

package/agent/server/handler.ts

@@ -1,3 +1,4 @@
+import { terminateDatabaseProcesses } from '../db/processWorker';
 import { BunqueueBackupRunner, type BackupRunnerPort } from '../backup/runner';
 import type { ProcessManager } from '../manager';
 import { QueueOperationsRuntime } from '../queue/runtime';
@@ -110,7 +111,7 @@ export function createFetchHandler(
     shuttingDown ??= closeThenShutdown(beginShutdown, manager);
     return shuttingDown;
   };
-  const forceShutdown = () => manager.forceShutdown();
+  const forceShutdown = () => { terminateDatabaseProcesses(); manager.forceShutdown(); };
   return Object.assign(handle, { close, beginShutdown, shutdown, forceShutdown });
 }
 

package/agent/server/workflowReadRoutes.ts

@@ -1,9 +1,7 @@
+import { readWithTimeout } from '../db/queryTimeout';
 import {
   type WorkflowStateFilter,
   type WorkflowStoreKind,
-  workflowExecution,
-  workflowExecutions,
-  workflowStats,
   WORKFLOW_STATES,
 } from '../workflows';
 import type { RouteResponse } from './types';
@@ -32,9 +30,9 @@ export async function routeWorkflowReadRequest(
   admission?: ManagedDatabaseAdmission
 ): Promise<RouteResponse | null> {
   if (pathname === '/workflows/stats' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...workflowStats(path) },
+      body: { ok: true, ...(await readWithTimeout('workflowStats', [path], request.signal)) },
     }));
   }
   if (pathname === '/workflows' && method === 'GET') {
@@ -52,17 +50,17 @@ export async function routeWorkflowReadRequest(
     ) {
       throw new Error('Unknown workflow execution state');
     }
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
       body: {
         ok: true,
-        ...workflowExecutions(path, {
+        ...(await readWithTimeout('workflowExecutions', [path, {
           kind: workflowKind(query),
           workflowName: query.get('workflowName') || undefined,
           state: state as WorkflowStateFilter | undefined,
           limit: integer(query, 'limit', 50),
           offset: integer(query, 'offset', 0),
-        }),
+        }], request.signal)),
       },
     }));
   }
@@ -78,8 +76,8 @@ export async function routeWorkflowReadRequest(
       throw new Error(`Duplicate workflow detail option: ${key}`);
     }
   }
-  return withDatabase(dataPath, admission, (path) => {
-    const execution = workflowExecution(path, decodeURIComponent(rawId), workflowKind(query));
+  return withDatabase(dataPath, admission, async (path) => {
+    const execution = await readWithTimeout('workflowExecution', [path, decodeURIComponent(rawId), workflowKind(query)], request.signal);
     return execution
       ? { status: 200, body: { ok: true, execution } }
       : { status: 404, body: { ok: false, error: 'Workflow execution not found' } };
@@ -89,7 +87,7 @@ export async function routeWorkflowReadRequest(
 function withDatabase<T>(
   dataPath: string,
   admission: ManagedDatabaseAdmission | undefined,
-  operation: (path: string) => T
+  operation: (path: string) => T | Promise<T>
 ): Promise<T> {
   return admission
     ? admission((snapshot) => operation(snapshot.dataPath))

package/agent/workflow/sqlite.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { Database } from 'bun:sqlite';
-import { MissingDbError } from '../db';
+import { MissingDbError } from '../db/types';
 import type { WorkflowStoreKind } from './types';
 
 export interface WorkflowSchema {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-dashboard",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "type": "module",
   "description": "Web dashboard for a bunqueue server (queues, jobs, DLQ, cron, metrics, workers, live activity). Run with `bunx bunqueue-dashboard` (requires Bun 1.4.2).",
   "packageManager": "bun@1.4.2",
@@ -66,7 +66,7 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "bun run scripts/build-docs.ts",
     "docs:preview": "vitepress preview docs",
-    "build:bin": "bun run build && bun run scripts/gen-embed.ts && bun build scripts/serve.ts agent/dbQueryWorker.ts agent/backup/standaloneWorker.ts --compile --minify --outfile bunqueue-dashboard",
+    "build:bin": "bun run build && bun run scripts/gen-embed.ts && bun build scripts/serve.ts agent/dbReadWorker.ts agent/backup/standaloneWorker.ts --compile --minify --outfile bunqueue-dashboard",
     "preview": "vite preview",
     "test": "bun test",
     "test:e2e:flow": "bun run scripts/validate-flow-runtime.ts",
@@ -80,8 +80,11 @@
     "test:e2e:browser:serve": "bun e2e/runtime.ts",
     "test:e2e:browser:postgres-fleet": "bun run scripts/validate-postgres-fleet-dashboard-runtime.ts",
     "test:e2e:browser": "bun run build && bun scripts/gen-embed.ts && playwright test",
+    "test:binary": "bun scripts/validate-standalone-runtime.ts ./bunqueue-dashboard",
+    "test:runtime": "bun scripts/validate-standalone-runtime.ts --source",
+    "test:soak": "bun scripts/validate-resilience.ts",
     "test:package": "bun run scripts/validate-package-runtime.ts",
-    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage && bun scripts/check-coverage.ts && bun scripts/check-test-inventory.ts",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage && bun scripts/check-coverage.ts && bun scripts/check-critical-coverage.ts && bun scripts/check-test-inventory.ts",
     "lint": "oxlint . && bun run scripts/check-implicit-any-let.ts",
     "lint:fix": "oxlint --fix . && bun run scripts/check-implicit-any-let.ts",
     "format": "oxfmt .",
@@ -89,7 +92,7 @@
     "check": "bun run lint && bun run format:check",
     "check:fix": "bun run lint:fix && bun run format",
     "audit:high": "bun audit --audit-level=high --ignore=GHSA-qwww-vcr4-c8h2",
-    "quality": "bun run version:check && bun run architecture && bun run check && bun run build && bun run size && bun run docs:build && bun run test:coverage && bun run test:e2e && bun run test:package && bun run audit:high",
+    "quality": "bun run version:check && bun run architecture && bun run check && bun run build && bun run size && bun run docs:build && bun run test:coverage && bun run test:e2e && bun run test:package && bun run test:runtime && bun run test:soak && bun run audit:high",
     "typecheck:e2e": "tsc -p tsconfig.e2e.json",
     "test:e2e:browser:managed": "bun run build && bun scripts/gen-embed.ts && playwright test -c playwright.managed.config.ts",
     "test:e2e:docs": "bun run docs:build && playwright test -c playwright.docs.config.ts"

package/scripts/serve.ts

@@ -4,9 +4,10 @@
  * local control agent through a same-origin /agent bridge.
  */
 import { logger } from '../agent/logger';
+import { compiledWorkerUrl } from '../agent/compiledRuntime';
+import { agentConfigStore } from '../agent/manager/configStore';
 import { BunqueueBackupRunner } from '../agent/backup/runner';
 import { setBackupWorkerUrl } from '../agent/backup/workerFactory';
-import { setQueryWorkerUrl } from '../agent/db';
 import { QueueOperationsRuntime } from '../agent/queue/runtime';
 import {
   AgentLifecycleGate,
@@ -50,18 +51,7 @@ export {
 } from './servePolicy';
 
 async function main(): Promise<void> {
-  // Compiled Bun entrypoints load the query worker from the embedded bundle.
-  const compiled = import.meta.url.includes('/$bunfs/');
-  setQueryWorkerUrl(
-    compiled
-      ? new URL('/$bunfs/root/agent/dbQueryWorker.js', 'file:///').href
-      : new URL('../agent/dbQueryWorker.ts', import.meta.url).href
-  );
-  setBackupWorkerUrl(
-    compiled
-      ? new URL('/$bunfs/root/agent/backup/standaloneWorker.js', 'file:///').href
-      : null
-  );
+  setBackupWorkerUrl(compiledWorkerUrl(import.meta.url, 'agent/backup/standaloneWorker.js'));
 
   const port = Number(process.env.PORT) || 8080;
   const host = process.env.BIND_ADDR || '127.0.0.1';
@@ -109,7 +99,7 @@ async function main(): Promise<void> {
 
   // Keep ProcessManager out of policy-only test imports.
   const { ProcessManager } = await import('../agent/manager');
-  const mgr = new ProcessManager();
+  const mgr = new ProcessManager(undefined, agentConfigStore());
   const workflowRuntime = new WorkflowRuntime();
   const backupRunner = new BunqueueBackupRunner();
   const queueRuntime = new QueueOperationsRuntime();
@@ -198,4 +188,9 @@ async function main(): Promise<void> {
   );
 }
 
-if (import.meta.main) await main();
+if (import.meta.main) {
+  if (process.argv.includes('--bq-db-read')) {
+    const { runDatabaseReadProcess } = await import('../agent/db/readProcessMain');
+    await runDatabaseReadProcess();
+  } else await main();
+}