bunqueue-dashboard 0.0.46 → 1.0.1

package/README.md

@@ -26,7 +26,7 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-online-db2777)](https://egeominotti.github.io/bunqueue-dashboard/docs/)
 [![Live demo](https://img.shields.io/badge/live%20demo-online-22c55e)](https://egeominotti.github.io/bunqueue-dashboard/)
-![Status: Beta](https://img.shields.io/badge/status-beta-f59e0b)
+![Status: Stable](https://img.shields.io/badge/status-stable-22c55e)
 
 ![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)
 ![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
@@ -58,9 +58,9 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 
 ---
 
-> ⚠️ **Beta.** bunqueue dashboard is under active development, interfaces and
-> behavior may change between releases. Review it before relying on it for
-> unattended production use.
+> ✅ **Stable (1.x).** The dashboard follows [Semantic Versioning](https://semver.org/):
+> breaking changes to its configuration, routes or agent API only ship in a new
+> major version.
 
 ## 📚 Documentation
 
@@ -129,8 +129,8 @@ contracts; it never patches Bunqueue internals.
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
 > closed. Bunqueue 2.9's `Queue.removeDlqJob()` also accepts only queue + job ID, so custom-ID reuse
 > prevents the dashboard from proving that a later deletion still targets the observed generation.
-> DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
-> mutations are Promote, Pause and Resume.
+> DLQ `maxAge`/`maxEntries` are read-only, and auto-retry can only be disabled. The in-app Copilot
+> is switched off in official builds (`VITE_ENABLE_COPILOT=1` opts a custom build back in).
 
 ## Quick start
 

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/managedTarget.ts

@@ -72,7 +72,9 @@ function assertLocalTarget(target: string, config: ServerConfig, label: string):
   } catch {
     throw new Error(`${label} must be an absolute local HTTP URL`);
   }
-  const local = ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+  // URL keeps IPv6 brackets in hostname (`[::1]`), so compare without them.
+  const host = url.hostname.replace(/^\[(.*)\]$/, '$1');
+  const local = ['localhost', '127.0.0.1', '::1'].includes(host);
   const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
   if (!local || port !== config.httpPort || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
     throw new Error(