bunqueue-dashboard 0.0.30 → 0.0.32

package/agent/db.ts

@@ -9,14 +9,21 @@
  *
  * Defense in depth for the arbitrary-query endpoint (dbQuery):
  *  - a positive statement allowlist rejects ATTACH/DETACH/CREATE-TEMP/etc.
- *    BEFORE execution, so store safety never relies on Bun's single-statement
- *    compilation quirk;
+ *    before execution — but it inspects only the FIRST keyword, so it does NOT
+ *    stop a trailing statement smuggled in after a legal one. Everything here
+ *    must therefore compile SQL through db.query() (one statement, the rest
+ *    inert) and never db.run() (executes them all). Do not weaken this comment
+ *    into "the allowlist makes the store safe": believing that is what once
+ *    turned the dup-column recovery path into an arbitrary file write;
  *  - results are streamed with an early break at MAX_ROWS, so a huge or
  *    row-bomb query can't materialize the whole set in agent memory;
  *  - queryWithTimeout() runs it in a disposable Worker raced against a wall
  *    clock, so an O(N^k) scan can't pin the agent's only thread and freeze the
  *    process-control endpoints (falls back to synchronous run if a Worker can't
- *    be spawned, e.g. inside a compiled single-file binary).
+ *    be spawned, e.g. inside a compiled single-file binary). The timeout aborts
+ *    the response, not the query — a synchronous sqlite3_step never yields to
+ *    the terminate() request — so live worker threads are counted and capped by
+ *    MAX_CONCURRENT_QUERIES instead of accumulating one pinned core per request.
  */
 import { existsSync } from 'node:fs';
 import { Database } from 'bun:sqlite';
@@ -144,10 +151,29 @@ function isTruncated(v: unknown): boolean {
 function cell(v: unknown): unknown {
   if (v instanceof Uint8Array) return `<blob ${v.byteLength} B>`;
   if (typeof v === 'string' && v.length > MAX_CELL) return `${v.slice(0, MAX_CELL)}…`;
-  if (typeof v === 'bigint') return v.toString();
+  // Read statements run with safeIntegers, so INTEGERs arrive as bigint: keep the
+  // familiar number shape when it round-trips exactly, and fall back to a string
+  // beyond 2^53 (where a double would silently round the stored value).
+  if (typeof v === 'bigint') return bigintCell(v);
   return v;
 }
 
+/** Exact-value-preserving JSON form of a SQLite INTEGER read with safeIntegers. */
+function bigintCell(v: bigint): number | string {
+  return v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER)
+    ? Number(v)
+    : v.toString();
+}
+
+/**
+ * bun:sqlite exposes Statement.safeIntegers() at runtime but does not type it.
+ * Enabled per statement (never connection-wide) so the COUNT(*) reads that are
+ * consumed as numbers keep returning numbers.
+ */
+function safeIntegers(stmt: unknown): void {
+  (stmt as { safeIntegers?: (on: boolean) => void }).safeIntegers?.(true);
+}
+
 const sanitize = (rows: unknown[][]): unknown[][] => rows.map((r) => r.map(cell));
 
 /** All user tables with row + column counts. */
@@ -189,8 +215,14 @@ function buildFilter(
   const q = ident(col);
   if (filter.op === 'eq') return { clause: ` WHERE ${q} = ?`, params: [filter.value], applied: filter };
   if (filter.op === 'ne') return { clause: ` WHERE ${q} <> ?`, params: [filter.value], applied: filter };
-  // contains (default)
-  return { clause: ` WHERE ${q} LIKE ?`, params: [`%${filter.value}%`], applied: { ...filter, op: 'contains' } };
+  // contains (default) — escape LIKE metacharacters so a value containing % or _
+  // matches literally instead of turning into a wildcard pattern.
+  const needle = filter.value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+  return {
+    clause: ` WHERE ${q} LIKE ? ESCAPE '\\'`,
+    params: [`%${needle}%`],
+    applied: { ...filter, op: 'contains' },
+  };
 }
 
 /**
@@ -208,7 +240,11 @@ export function dbRows(
   filter?: DbFilter
 ): DbRowsPage {
   const lim = Math.max(1, Math.min(MAX_ROWS, Math.floor(limit) || 50));
-  const off = Math.max(0, Math.floor(offset) || 0);
+  // Non-finite / out-of-range offsets must be clamped here: SQLite rejects a
+  // bound non-safe-integer double with a raw "datatype mismatch".
+  const off = Number.isFinite(offset)
+    ? Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(offset) || 0))
+    : 0;
   const db = open(path);
   try {
     const name = knownTable(db, table);
@@ -235,15 +271,19 @@ export function dbRows(
     let rowids: (number | null)[] = [];
     let rawRows: unknown[][];
     try {
-      const withRowid = db
-        .query(`SELECT rowid AS __rid, * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`)
-        .values(...(params as []), lim, off) as unknown[][];
-      rowids = withRowid.map((r) => (typeof r[0] === 'number' ? r[0] : null));
+      const stmt = db.query(
+        `SELECT rowid AS __rid, * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`
+      );
+      safeIntegers(stmt);
+      const withRowid = stmt.values(...(params as []), lim, off) as unknown[][];
+      rowids = withRowid.map((r) =>
+        typeof r[0] === 'bigint' ? Number(r[0]) : typeof r[0] === 'number' ? r[0] : null
+      );
       rawRows = withRowid.map((r) => r.slice(1));
     } catch {
-      rawRows = db
-        .query(`SELECT * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`)
-        .values(...(params as []), lim, off) as unknown[][];
+      const stmt = db.query(`SELECT * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`);
+      safeIntegers(stmt);
+      rawRows = stmt.values(...(params as []), lim, off) as unknown[][];
       rowids = rawRows.map(() => null);
     }
 
@@ -276,13 +316,13 @@ export function dbCell(path: string, table: string, rowid: number, column: strin
     );
     const col = columns.find((c) => c === column);
     if (!col) throw new Error(`No such column: ${column}`);
-    const row = db
-      .query(`SELECT ${ident(col)} AS v FROM ${ident(name)} WHERE rowid = ?`)
-      .get(rowid) as { v: unknown } | null;
+    const stmt = db.query(`SELECT ${ident(col)} AS v FROM ${ident(name)} WHERE rowid = ?`);
+    safeIntegers(stmt);
+    const row = stmt.get(rowid) as { v: unknown } | null;
     if (!row) throw new Error('Row not found');
     let v = row.v;
     if (v instanceof Uint8Array) v = `<blob ${v.byteLength} B — binary, not shown>`;
-    else if (typeof v === 'bigint') v = v.toString();
+    else if (typeof v === 'bigint') v = bigintCell(v);
     else if (typeof v === 'string' && v.length > MAX_FULL_CELL) v = `${v.slice(0, MAX_FULL_CELL)}…`;
     return { value: v };
   } finally {
@@ -375,6 +415,38 @@ function leadingKeyword(sql: string): string {
 
 const READ_ONLY_LEAD = /^(?:SELECT|WITH|EXPLAIN|VALUES|PRAGMA)\b/;
 
+/** Temp-view name used to recover colliding output column names (see dbQuery). */
+const DUP_VIEW = '__bq_query_columns';
+
+/**
+ * Re-prepare a statement whose output column names collide through a TEMP VIEW,
+ * so SQLite disambiguates them itself ("id", "id:1") and every column survives
+ * the by-name row rebuild. The view lives in the private temp schema (nothing is
+ * written to the readonly store) and dies with the connection. Returns null when
+ * the statement can't be a view (PRAGMA / EXPLAIN — neither can collide anyway).
+ */
+function disambiguateColumns(
+  db: Database,
+  sql: string
+): { stmt: ReturnType<Database['query']>; cols: string[] } | null {
+  try {
+    // MUST be query().run() (single prepared statement), never db.run(): db.run
+    // executes EVERY statement in the string, and the front-door allowlist only
+    // inspects the FIRST keyword. `SELECT 1 a, 2 a; VACUUM INTO '/tmp/x'` would
+    // otherwise reach a readonly connection as an arbitrary-file WRITE, and
+    // `…; ATTACH '/any.db' AS l; DROP VIEW …; CREATE TEMP VIEW … AS SELECT * FROM l.x`
+    // as an arbitrary-SQLite-file READ. query() compiles only the first
+    // statement, so the trailing payload is inert.
+    db.query(`CREATE TEMP VIEW ${ident(DUP_VIEW)} AS ${sql.replace(/;\s*$/, '')}`).run();
+    const cols = (
+      db.query(`PRAGMA table_info(${ident(DUP_VIEW)})`).all() as { name: string }[]
+    ).map((c) => c.name);
+    return { stmt: db.query(`SELECT * FROM ${ident(DUP_VIEW)}`), cols };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Run an arbitrary read-only query. Rejects non-read statements up front,
  * streams rows with an early break at MAX_ROWS, and translates the raw SQLite
@@ -396,7 +468,18 @@ export function dbQuery(path: string, sql: string): DbQueryResult {
     } catch (e) {
       throw translateError(e);
     }
-    const cols = stmt.columnNames;
+    let cols = stmt.columnNames;
+    // Bun de-duplicates columnNames while columnTypes keeps the true arity, and
+    // rows are rebuilt BY NAME below — so without this, a statement with colliding
+    // output names (`SELECT a.id, b.id`, any self-join) silently loses columns.
+    if (stmt.columnTypes.length > cols.length) {
+      const wide = disambiguateColumns(db, trimmed);
+      if (wide) {
+        stmt = wide.stmt;
+        cols = wide.cols;
+      }
+    }
+    safeIntegers(stmt);
     const rows: unknown[][] = [];
     let truncated = false;
     try {
@@ -436,52 +519,107 @@ function translateError(e: unknown): Error {
 /**
  * Time-boxed, off-thread execution of an arbitrary query. Spawns a disposable
  * readonly Worker and races it against QUERY_TIMEOUT_MS so a runaway scan can't
- * freeze the agent's control endpoints. Falls back to a synchronous run when a
- * Worker cannot be created (e.g. a compiled single-file binary) — still bounded
- * in memory and statement type, just not interruptible.
+ * freeze the agent's control endpoints.
+ *
+ * The timeout aborts the RESPONSE, not the query: terminate() is delivered to
+ * the worker's event loop, which a synchronous sqlite3_step never yields back
+ * to, so a runaway scan keeps burning its own thread until SQLite finishes it.
+ * That thread is therefore accounted for (a slot is held until the worker really
+ * exits) and capped by MAX_CONCURRENT_QUERIES, so N timed-out queries can pin at
+ * most MAX_CONCURRENT_QUERIES cores instead of one core per request, forever.
  */
+let queryWorkerUrl = new URL('./dbQueryWorker.ts', import.meta.url).href;
+
+/** Hard cap on query worker threads alive at once (see queryWithTimeout). */
+export const MAX_CONCURRENT_QUERIES = 2;
+let liveQueryWorkers = 0;
+
+/** Query worker threads currently alive — includes timed-out, still-running ones. */
+export const queryWorkerLoad = (): number => liveQueryWorkers;
+
+/**
+ * The standalone executable's bundle root is scripts/serve.ts, so it supplies
+ * the embedded worker URL relative to that entrypoint. Source-mode agent runs
+ * keep the module-relative default above.
+ */
+export function setQueryWorkerUrl(url: string): void {
+  queryWorkerUrl = url;
+}
+
+const spawnRealWorker = (): Worker => new Worker(queryWorkerUrl, { type: 'module' });
+let queryWorkerFactory: () => Worker = spawnRealWorker;
+
+/**
+ * Swap how a query worker is constructed. Tests only: spawning a real Bun
+ * Worker in a process where happy-dom's globals are installed panics the
+ * runtime (allocator abort), so the timeout/accounting behaviour below is
+ * exercised through a stand-in worker instead of a real thread. Pass null to
+ * restore the real one.
+ */
+export function setQueryWorkerFactory(factory: (() => Worker) | null): void {
+  queryWorkerFactory = factory ?? spawnRealWorker;
+}
+
 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;
   try {
-    worker = new Worker(new URL('./dbQueryWorker.ts', import.meta.url).href, { type: 'module' });
-  } catch {
-    return dbQuery(path, sql); // no Worker available — degrade to synchronous
+    worker = queryWorkerFactory();
+  } catch (e) {
+    throw new Error(`Query worker unavailable: ${(e as Error).message ?? String(e)}`);
   }
+  liveQueryWorkers++;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    liveQueryWorkers--;
+  };
+  // A worker that never answers still holds its slot until the thread really
+  // exits ('close' fires when SQLite finally returns) — that is the whole point.
+  worker.addEventListener('close', release);
   try {
     return await new Promise<DbQueryResult>((resolve, reject) => {
-      // The Worker module is not always available at runtime — notably a
-      // `bun build --compile` single-file binary does not embed it, and there
-      // `new Worker(...)` does NOT throw synchronously: it resolves and then
-      // fails asynchronously via the `error` event (ModuleNotFound). Guard both
-      // paths and degrade to a synchronous run rather than failing the request.
       let settled = false;
       const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
         worker.terminate();
-        reject(new Error(`Query exceeded the ${QUERY_TIMEOUT_MS / 1000}s time limit and was aborted.`));
+        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', (ev: MessageEvent) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
-        const d = ev.data as { ok: boolean; result?: DbQueryResult; error?: string };
+        // The query is done — its thread is idle, so free the slot immediately.
+        release();
+        const d = ev.data as {
+          ok: boolean;
+          result?: DbQueryResult;
+          error?: string;
+          missing?: boolean;
+        };
         if (d.ok && d.result) resolve(d.result);
+        // The worker boundary is a string channel, so the error CLASS is carried
+        // as a flag — server.ts maps MissingDbError to 404, everything else 400.
+        else if (d.missing) reject(new MissingDbError(d.error ?? 'Database not found'));
         else reject(new Error(d.error ?? 'Query failed'));
       });
       worker.addEventListener('error', (ev: ErrorEvent) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
-        // Worker infra itself failed to load/run (e.g. not embedded in the
-        // compiled binary). Fall back to the synchronous path — still readonly,
-        // allowlisted and row-capped, just not interruptible by the wall clock.
+        release();
         ev.preventDefault?.();
-        try {
-          resolve(dbQuery(path, sql));
-        } catch (e) {
-          reject(translateError(e));
-        }
+        reject(new Error(`Query worker failed: ${ev.message || 'unknown worker error'}`));
       });
       worker.postMessage({ path, sql });
     });

package/agent/dbQueryWorker.ts

@@ -2,12 +2,14 @@
  * Disposable worker that runs ONE read-only query and posts the result back.
  *
  * queryWithTimeout() (agent/db.ts) spawns one of these per /db/query request and
- * races it against a wall clock; on timeout the parent terminate()s this worker,
- * so a runaway O(N^k) scan is killed instead of pinning the agent's only thread
- * and freezing the process-control endpoints. The connection is opened readonly
- * inside dbQuery, so nothing here can mutate the store.
+ * races it against a wall clock, so a runaway O(N^k) scan can't freeze the
+ * agent's process-control endpoints. terminate() does NOT preempt a synchronous
+ * sqlite3_step, though — it abandons the response, and this thread keeps running
+ * until SQLite finishes, which is why db.ts caps how many can be alive at once.
+ * The connection is opened readonly inside dbQuery, so nothing here can mutate
+ * the store.
  */
-import { dbQuery } from './db';
+import { dbQuery, MissingDbError } from './db';
 
 declare const self: Worker;
 
@@ -16,6 +18,12 @@ self.addEventListener('message', (ev: MessageEvent) => {
   try {
     self.postMessage({ ok: true, result: dbQuery(path, sql) });
   } catch (e) {
-    self.postMessage({ ok: false, error: (e as Error).message ?? String(e) });
+    // postMessage can't carry the error class, so flag the one the route branches
+    // on (MissingDbError → 404) and let db.ts rebuild it on the parent side.
+    self.postMessage({
+      ok: false,
+      error: (e as Error).message ?? String(e),
+      missing: e instanceof MissingDbError,
+    });
   }
 });

package/agent/index.ts

@@ -41,7 +41,10 @@ const shutdown = (signal: string) => {
   if (shuttingDown) return;
   shuttingDown = true;
   logger.info({ signal }, 'signal received, stopping managed server');
-  void mgr.stop().finally(() => process.exit(0));
+  // shutdown() (not stop()) latches the manager closed first: a plain stop()
+  // racing an in-flight restart() returns successfully *because* restart's
+  // start() already spawned a replacement — which process.exit() would orphan.
+  void mgr.shutdown().finally(() => process.exit(0));
 };
 process.on('SIGINT', () => shutdown('SIGINT'));
 process.on('SIGTERM', () => shutdown('SIGTERM'));

package/agent/manager.ts

@@ -48,6 +48,13 @@ export interface StatusSnapshot {
 
 const MAX_LOGS = 800;
 const STOP_TIMEOUT_MS = 8000;
+/**
+ * Hard byte cap for a single log line. The ring buffer trims by COUNT, so a
+ * child that dumps a large blob without a newline (binary file, one-line JSON)
+ * would otherwise grow the reader's in-flight buffer — and then one retained
+ * LogLine — without limit.
+ */
+const MAX_LINE = 8192;
 
 function defaultConfig(): ServerConfig {
   return {
@@ -75,6 +82,15 @@ export class ProcessManager {
    * a concurrent start() brought up (and vice-versa).
    */
   private procToken = 0;
+  /**
+   * The stop() currently in flight (null when none). A stop() still owns a live
+   * child until its await resolves, so start() waits on this before spawning —
+   * otherwise a start racing a stop leaves two managed servers alive at once,
+   * fighting over the ports and the SQLite db.
+   */
+  private stopping: Promise<StatusSnapshot> | null = null;
+  /** Latched by shutdown(): once set, start() refuses to spawn a new child. */
+  private shuttingDown = false;
 
   getConfig(): ServerConfig {
     return this.config;
@@ -135,31 +151,52 @@ export class ProcessManager {
   }
 
   private push(stream: LogLine['stream'], line: string): void {
-    this.logs.push({ seq: this.seq++, ts: Date.now(), stream, line });
+    // Backstop byte cap (the reader also splits oversized chunks) so no single
+    // entry can pin an unbounded amount of memory in the ring buffer.
+    const capped = line.length > MAX_LINE ? `${line.slice(0, MAX_LINE)}…[truncated]` : line;
+    this.logs.push({ seq: this.seq++, ts: Date.now(), stream, line: capped });
     // Amortized trim: only splice once the buffer overshoots by a slack margin, so
     // steady-state logging isn't an O(n) array shift on every single line.
     if (this.logs.length > MAX_LOGS + 256) this.logs.splice(0, this.logs.length - MAX_LOGS);
   }
 
   async start(): Promise<StatusSnapshot> {
+    if (this.shuttingDown) return this.getStatus();
     if (this.status === 'running' || this.status === 'starting') return this.getStatus();
+    // Never spawn while a stop() still owns a live child: wait it out, then
+    // re-check the guards (a concurrent start may have won the race meanwhile).
+    if (this.stopping) await this.stopping;
+    if (this.shuttingDown) return this.getStatus();
+    // Read through a local: TS narrowed `this.status` at the guard above and
+    // doesn't widen it across the await, but a concurrent start() can have
+    // moved it in the meantime — that interleaving is exactly what this checks.
+    const statusAfterWait = this.status as Status;
+    if (statusAfterWait === 'running' || statusAfterWait === 'starting') return this.getStatus();
+
+    // Validate BEFORE mutating status / burning a proc token. Doing it after
+    // (as this once did) means a bad command leaves the manager wedged: an
+    // empty command stranded the previous generation's dead pid + runningConfig
+    // (its stop()/onExit finalizers were already token-stale), and a non-string
+    // `command` from PUT /control/config threw out of `.trim()` with status
+    // pinned at 'starting', disabling every UI control until the agent restarts.
+    const command = typeof this.config.command === 'string' ? this.config.command : '';
+    const parts = command.trim().split(/\s+/);
+    const [cmd, ...args] = parts;
+    if (!cmd) throw new Error('Empty command');
+
     this.status = 'starting';
     this.exitCode = null;
     const token = ++this.procToken;
 
-    const parts = this.config.command.trim().split(/\s+/);
-    const [cmd, ...args] = parts;
-    if (!cmd) {
-      this.status = 'stopped';
-      throw new Error('Empty command');
-    }
-
+    // extraEnv is spread FIRST so the explicit port/data-path config always
+    // wins: otherwise a user env var named HTTP_PORT silently moved the child
+    // while runningConfig (and the agent's /health probe) reported the old port.
     const env: Record<string, string> = {
       ...(process.env as Record<string, string>),
+      ...this.config.extraEnv,
       HTTP_PORT: String(this.config.httpPort),
       TCP_PORT: String(this.config.tcpPort),
       BUNQUEUE_DATA_PATH: this.config.dataPath,
-      ...this.config.extraEnv,
     };
 
     try {
@@ -214,6 +251,12 @@ export class ProcessManager {
           buffer = buffer.slice(i + 1);
           if (line.trim()) this.push(name, line);
         }
+        // No newline in sight: flush in MAX_LINE slices instead of letting the
+        // buffer (and the eventual single LogLine) grow to the whole output.
+        while (buffer.length > MAX_LINE) {
+          this.push(name, buffer.slice(0, MAX_LINE));
+          buffer = buffer.slice(MAX_LINE);
+        }
       }
     } catch {
       /* stream closed */
@@ -226,6 +269,29 @@ export class ProcessManager {
   }
 
   async stop(): Promise<StatusSnapshot> {
+    // Publish the in-flight stop so a racing start() can await it (see
+    // `stopping`). stopOnce() runs its synchronous prefix — including
+    // status='stopping' and the SIGTERM — before we return the promise.
+    const p = this.stopOnce();
+    this.stopping = p;
+    try {
+      return await p;
+    } finally {
+      if (this.stopping === p) this.stopping = null;
+    }
+  }
+
+  /**
+   * Stop the managed server and latch the manager closed, so a start() racing
+   * process shutdown (e.g. an in-flight restart() whose stop() resolves after
+   * SIGINT) cannot spawn a child that would be orphaned by process.exit().
+   */
+  async shutdown(): Promise<StatusSnapshot> {
+    this.shuttingDown = true;
+    return this.stop();
+  }
+
+  private async stopOnce(): Promise<StatusSnapshot> {
     if (!this.proc) {
       this.status = 'stopped';
       this.runningConfig = null;
@@ -236,17 +302,36 @@ export class ProcessManager {
     const proc = this.proc;
     const token = this.procToken;
     proc.kill();
+    // Timer cleared either way (this is the COMMON path): a pending one keeps
+    // the event loop alive for the full timeout after the race is decided.
+    let stopTimer: ReturnType<typeof setTimeout> | undefined;
     const timedOut = await Promise.race([
       proc.exited.then(() => false),
-      new Promise<boolean>((r) => setTimeout(() => r(true), STOP_TIMEOUT_MS)),
-    ]);
+      new Promise<boolean>((r) => {
+        stopTimer = setTimeout(() => r(true), STOP_TIMEOUT_MS);
+      }),
+    ]).finally(() => clearTimeout(stopTimer));
     // Always escalate to SIGKILL on the CAPTURED proc (never `this.proc`) so a
     // child that ignores SIGTERM is still reaped even if a concurrent start()
     // has since swapped in a new process — `proc` targets this generation only.
     if (timedOut) {
       this.push('sys', 'SIGTERM timed out, sending SIGKILL');
       proc.kill(9);
-      await proc.exited;
+      // Bounded: a child wedged in uninterruptible sleep never resolves
+      // `exited` even after SIGKILL, and start() now awaits this promise, so an
+      // unbounded wait here would pin the manager at 'stopping' and hang every
+      // later start() forever. Give up on the wait (not on the kill) and let the
+      // state below finalize — the pid is already unusable. The timer is always
+      // cleared: a pending one keeps the event loop alive after the race is
+      // decided, which delays process exit for the whole timeout.
+      let reapTimer: ReturnType<typeof setTimeout> | undefined;
+      const reaped = await Promise.race([
+        proc.exited.then(() => true),
+        new Promise<boolean>((r) => {
+          reapTimer = setTimeout(() => r(false), STOP_TIMEOUT_MS);
+        }),
+      ]).finally(() => clearTimeout(reapTimer));
+      if (!reaped) this.push('sys', `pid ${proc.pid} did not exit after SIGKILL — giving up on it`);
     }
     // Only finalize shared state if no newer start() replaced this generation
     // while we awaited — otherwise we'd null out the wrong (live) process.

package/agent/server.ts

@@ -65,7 +65,13 @@ export function hostnameOf(host: string): string {
   const v6 = s.match(/^\[([^\]]+)\]/); // [::1]:6800 → ::1
   if (v6) return v6[1].toLowerCase();
   const i = s.indexOf(':');
-  return (i === -1 ? s : s.slice(0, i)).toLowerCase();
+  if (i === -1) return s.toLowerCase();
+  // A bare (unbracketed) IPv6 literal has several colons and no port delimiter:
+  // splitting on the first one would both lock the real host out and allowlist a
+  // bogus single label ('2001:db8::5' → '2001'). Keep it whole — that also makes
+  // hostnameOf idempotent over its own bracket-stripped output.
+  if (s.indexOf(':') !== s.lastIndexOf(':')) return s.toLowerCase();
+  return s.slice(0, i).toLowerCase();
 }
 
 /**
@@ -180,10 +186,10 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
     // GETs (including the /db/* inspector, which can expose job payloads) are
     // protected by the Origin allowlist alone — a drive-by cross-origin page
     // can't read the response (no ACAO for its origin), which is the real
-    // threat. Gating reads behind the token would break the dashboard itself:
-    // the browser client sends no agent token (see bq.ts `agent()`), so the
-    // whole point of loopback + allowlisted CORS is to make browser reads work
-    // without one. Non-browser local callers on loopback are trusted for reads.
+    // threat. Reads intentionally remain available without a token for local
+    // dashboards that don't configure AGENT_TOKEN; when a token is configured,
+    // the browser client does send it, but only POST/PUT require it.
+    // Non-browser local callers on loopback are trusted for reads.
     const mutating = method === 'POST' || method === 'PUT';
     if (mutating && !tokenOk(req, token)) {
       return json({ ok: false, error: 'Unauthorized' }, 401, origin);