@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/db-adapter.ts

@@ -2,13 +2,15 @@
  * Database Adapter — supports SQLite and PostgreSQL
  *
  * SQLite adapter: wraps bun:sqlite (sync)
- * PostgreSQL adapter: wraps pg Pool (async, bridged to sync interface via blocking)
+ * PostgreSQL adapter: one Bun.SQL connection in a worker thread, bridged to the
+ *   sync interface with Atomics.wait (pg-worker.ts)
  *
  * Key design: callers write SQLite-style SQL. PgAdapter auto-translates:
  *   - ?1, ?2  →  $1, $2
- *   - datetime('now')  →  NOW()
- *   - datetime('now', '+N seconds')  →  NOW() + INTERVAL 'N seconds'
- *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  SERIAL PRIMARY KEY
+ *   - datetime('now'[, offset])  →  to_char(... AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')
+ *     (timestamps stay TEXT on both backends, RFC-039 §4.1)
+ *   - BLOB  →  BYTEA
+ *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  BIGSERIAL PRIMARY KEY; INTEGER  →  BIGINT
  *   - ON CONFLICT(col) DO UPDATE SET  →  ON CONFLICT(col) DO UPDATE SET  (same syntax)
  */
 
@@ -39,14 +41,32 @@ export interface DbAdapter {
 
   /** Dialect identifier */
   readonly dialect: "sqlite" | "postgres";
+
+  /** True when transaction() is all-or-nothing on one connection. */
+  readonly atomicTransactions: boolean;
+
+  /**
+   * Why features that need atomic transactions (scheduler, runtime evidence,
+   * side-thread command outbox) must stay off on this adapter, or null when
+   * they may run. Gates refuse on anything but null, so an adapter that does
+   * not implement this also refuses.
+   */
+  readonly transactionalFeaturesRefusal: string | null;
 }
 
+/** RFC-039: opt-in for PostgreSQL features whose PG tests do not exist yet (S4). */
+export const PG_EXPERIMENTAL_ENV = "COMMHUB_PG_EXPERIMENTAL";
+
 // ════════════════════════════════════════════
 //  SQLite Adapter (bun:sqlite, sync)
 // ════════════════════════════════════════════
 
 export class SQLiteAdapter implements DbAdapter {
   readonly dialect = "sqlite" as const;
+  readonly atomicTransactions = true;
+  get transactionalFeaturesRefusal(): string | null {
+    return this.atomicTransactions ? null : "transactions on this adapter are not atomic";
+  }
   constructor(private readonly rawDb: Database) {}
 
   run(sql: string, params?: any[]): QueryResult {
@@ -70,6 +90,17 @@ export class SQLiteAdapter implements DbAdapter {
   }
 
   close(): void {
+    // #2151: once more than 20 distinct SQL strings have gone through query(),
+    // bun:sqlite's close() can no longer really close the connection (measured:
+    // close(true) reports "database is locked"), so SQLite never checkpoints and
+    // a cleanly stopped Hub left its latest writes in -wal. Checkpoint first,
+    // so the .db file alone is complete after a clean stop.
+    try {
+      const r = this.rawDb.query<{ busy: number; log: number; checkpointed: number }, []>("PRAGMA wal_checkpoint(TRUNCATE)").get();
+      if (r && r.busy !== 0) console.warn(`[commhub] WAL checkpoint on close was busy: ${JSON.stringify(r)}`);
+    } catch (e) {
+      console.warn(`[commhub] WAL checkpoint on close failed: ${(e as Error)?.message ?? e}`);
+    }
     this.rawDb.close();
   }
 }
@@ -78,6 +109,15 @@ export class SQLiteAdapter implements DbAdapter {
 //  PostgreSQL Adapter (pg Pool, sync bridge)
 // ════════════════════════════════════════════
 
+/**
+ * PostgreSQL expression for SQLite's `datetime(...)` text: UTC, `YYYY-MM-DD HH:MM:SS`.
+ * Timestamps stay TEXT on both backends (RFC-039 §4.1), so a column written by
+ * `datetime('now')` compares, sorts and serialises the same way on each.
+ */
+function pgUtcText(expr: string): string {
+  return `to_char((${expr}) AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')`;
+}
+
 /**
  * Translate SQLite-style SQL to PostgreSQL.
  * Called on every query — must be fast (simple regex, no parsing).
@@ -85,18 +125,20 @@ export class SQLiteAdapter implements DbAdapter {
 export function sqliteToPostgres(sql: string): string {
   let s = sql;
   // ── datetime translations (before ?N→$N to handle datetime('now', ?N)) ──
-  // datetime('now', ?N) → NOW() + $N::INTERVAL  (param contains "+3600 seconds")
+  // datetime('now', ?N) → UTC text of NOW() + $N  (param contains "+3600 seconds").
+  // The CAST gives PG a type for a parameter it could not otherwise infer.
   s = s.replace(/datetime\s*\(\s*'now'\s*,\s*\?(\d+)\s*\)/gi, (_, n) => {
-    return `NOW() + $${n}::INTERVAL`;
+    return pgUtcText(`NOW() + CAST($${n} AS TEXT)::INTERVAL`);
   });
-  // datetime('now', '+N seconds') → NOW() + INTERVAL 'N seconds'
+  // datetime('now', '+N seconds') → UTC text of NOW() + INTERVAL 'N seconds'
   s = s.replace(/datetime\s*\(\s*'now'\s*,\s*'([^']+)'\s*\)/gi, (_, offset) => {
-    return `NOW() + INTERVAL '${offset.replace(/^\+/, "")}'`;
+    return pgUtcText(`NOW() + INTERVAL '${offset.replace(/^\+/, "")}'`);
   });
-  // datetime('now') → NOW()
-  s = s.replace(/datetime\s*\(\s*'now'\s*\)/gi, "NOW()");
-  // TEXT NOT NULL DEFAULT (datetime('now')) → TIMESTAMP NOT NULL DEFAULT NOW()
-  s = s.replace(/TEXT\s+NOT\s+NULL\s+DEFAULT\s+\(NOW\(\)\)/gi, "TIMESTAMP NOT NULL DEFAULT NOW()");
+  // datetime('now') → UTC text of NOW()
+  s = s.replace(/datetime\s*\(\s*'now'\s*\)/gi, pgUtcText("NOW()"));
+  // strftime('%Y-%m-%d %H:%M:%f', 'now') → the same text with milliseconds
+  s = s.replace(/strftime\s*\(\s*'%Y-%m-%d %H:%M:%f'\s*,\s*'now'\s*\)/gi,
+    "to_char(NOW() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.MS')");
   // ── Parameter placeholders ──
   // ?1, ?2 → $1, $2  (positional params)
   s = s.replace(/\?(\d+)/g, (_, n) => `$${n}`);
@@ -104,78 +146,171 @@ export function sqliteToPostgres(sql: string): string {
   let idx = 0;
   s = s.replace(/\?(?!\d)/g, () => `$${++idx}`);
   // ── DDL translations ──
-  // INTEGER PRIMARY KEY AUTOINCREMENT → SERIAL PRIMARY KEY
-  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "SERIAL PRIMARY KEY");
+  // INTEGER PRIMARY KEY AUTOINCREMENT → BIGSERIAL PRIMARY KEY
+  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "BIGSERIAL PRIMARY KEY");
+  // INTEGER → BIGINT: SQLite integers are 64-bit, and the Hub stores epoch
+  // milliseconds in INTEGER columns (a 32-bit PG integer overflows).
+  s = s.replace(/\bINTEGER\b/gi, "BIGINT");
+  // REAL → DOUBLE PRECISION: SQLite REAL is 8-byte; PostgreSQL REAL is 4-byte
+  // and would silently round telemetry and scores.
+  s = s.replace(/\bREAL\b/gi, "DOUBLE PRECISION");
+  // BLOB → BYTEA
+  s = s.replace(/\bBLOB\b/gi, "BYTEA");
   return s;
 }
 
 /**
- * PostgreSQL adapter using a synchronous subprocess bridge.
+ * Split a multi-statement script on top-level `;`.
+ *
+ * A bare `split(";")` cut through SQL comments (db.ts has `;` inside `--`
+ * comments) and through plpgsql `$$ … $$` bodies, so the Hub died on its
+ * first schema block on PostgreSQL. This skips `--` and `/* *\/` comments
+ * (dropping them) and keeps quoted strings, quoted identifiers and
+ * dollar-quoted bodies intact.
+ */
+export function splitSqlStatements(sql: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const c = sql[i];
+    if (c === "-" && sql[i + 1] === "-") {
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && sql[i + 1] === "*") {
+      const close = sql.indexOf("*/", i + 2);
+      i = close < 0 ? n : close + 2;
+      cur += " ";
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      while (j < n) {
+        if (sql[j] === c) {
+          if (sql[j + 1] === c) { j += 2; continue; }
+          break;
+        }
+        j++;
+      }
+      cur += sql.slice(i, j + 1);
+      i = j + 1;
+      continue;
+    }
+    if (c === "$") {
+      const tag = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+      if (tag) {
+        const close = sql.indexOf(tag[0], i + tag[0].length);
+        const stop = close < 0 ? n : close + tag[0].length;
+        cur += sql.slice(i, stop);
+        i = stop;
+        continue;
+      }
+    }
+    if (c === ";") {
+      if (cur.trim()) out.push(cur.trim());
+      cur = "";
+      i++;
+      continue;
+    }
+    cur += c;
+    i++;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/**
+ * PostgreSQL adapter: synchronous facade over one long-lived worker thread
+ * (RFC-039 S2b).
  *
- * TODO(P0-4): this is not transaction-safe. querySync currently starts a
- * fresh `node -e` process for every statement, so BEGIN/COMMIT/ROLLBACK do
- * not share one backend connection. PostgreSQL support is demoted behind
- * SQLite for now; before advertising it as production-ready, replace this
- * bridge with a long-lived worker or make DbAdapter async and use pg directly.
+ * The worker (pg-worker.ts) holds a single reserved Bun.SQL connection. Each
+ * call posts one request and blocks on Atomics.wait until the worker answers,
+ * so the DbAdapter interface stays synchronous — the same contract bun:sqlite
+ * gives the rest of the Hub, including "nothing else runs while a transaction
+ * is open". Because every statement uses the same backend connection,
+ * BEGIN/COMMIT/ROLLBACK are real transactions.
+ *
+ * SQLite semantics kept on purpose:
+ *   - a failed statement inside a transaction does not poison the transaction
+ *     (each statement inside one runs under a savepoint);
+ *   - nested transaction() calls become savepoints;
+ *   - booleans bind as 1/0 and undefined as NULL.
  */
 export class PgAdapter implements DbAdapter {
   readonly dialect = "postgres" as const;
-  private connString: string;
+  readonly atomicTransactions = true;
+  /** Closed by default on PG even with real transactions: explicit opt-in only. */
+  get transactionalFeaturesRefusal(): string | null {
+    if (!this.atomicTransactions) return "transactions on this adapter are not atomic";
+    if (process.env[PG_EXPERIMENTAL_ENV] === "1") return null;
+    return `PostgreSQL support is experimental; set ${PG_EXPERIMENTAL_ENV}=1 to enable this feature on it (RFC-039)`;
+  }
+  private readonly port: MessagePort;
+  private readonly flag: Int32Array;
+  private readonly worker: import("node:worker_threads").Worker;
+  private readonly waitMs: number;
+  private txDepth = 0;
 
   constructor(connectionString: string) {
-    this.connString = connectionString;
-    // Validate pg is available
-    try { require("pg"); } catch (e) {
-      throw new Error(
-        "PostgreSQL support requires 'pg' package. Install with: bun add pg\n" +
-        `  Original error: ${(e as Error).message}`
-      );
-    }
+    const { Worker, MessageChannel } = require("node:worker_threads") as typeof import("node:worker_threads");
+    const statementTimeoutMs = Number(process.env.COMMHUB_PG_STATEMENT_TIMEOUT_MS || 30_000);
+    // The main thread waits a little longer than PG itself will run a statement.
+    this.waitMs = statementTimeoutMs > 0 ? statementTimeoutMs + 5_000 : 300_000;
+    const { port1, port2 } = new MessageChannel();
+    this.port = port1 as unknown as MessagePort;
+    this.flag = new Int32Array(new SharedArrayBuffer(4));
+    this.worker = new Worker(new URL("./pg-worker.ts", import.meta.url), {
+      workerData: { port: port2, flag: this.flag, url: connectionString, statementTimeoutMs },
+      transferList: [port2 as any],
+    });
+    this.worker.unref();
+    (port1 as any).unref?.();
     // Test connection on startup
-    const test = this.querySync("SELECT 1 as ok");
+    const test = this.request("SELECT 1 as ok");
     if (!test.rows?.[0]?.ok) throw new Error("PostgreSQL connection test failed");
     console.log("[commhub] PostgreSQL connection verified");
   }
 
-  private querySync(sql: string, params?: any[]): { rows: any[]; rowCount: number } {
-    const pgSql = sqliteToPostgres(sql);
-    // Single-query subprocess with pg Pool (connection string from env)
-    const script = `
-      const{Pool}=require('pg');
-      const p=new Pool({connectionString:${JSON.stringify(this.connString)},max:1});
-      const q=${JSON.stringify(pgSql)};
-      const v=${JSON.stringify(params || [])};
-      p.query(q,v).then(r=>{
-        process.stdout.write(JSON.stringify({rows:r.rows,rowCount:r.rowCount||0}));
-        p.end();
-      }).catch(e=>{
-        process.stderr.write(e.message);
-        p.end();
-        process.exit(1);
-      });
-    `;
-    const proc = Bun.spawnSync(["node", "--no-warnings", "-e", script], {
-      stdout: "pipe", stderr: "pipe",
-    });
-    if (proc.exitCode !== 0) {
-      throw new Error(`PG: ${proc.stderr.toString().trim() || "query failed"}`);
+  /** Send one already-translated statement to the worker and block for the answer. */
+  private request(pgSql: string, params?: any[]): { rows: any[]; count: number } {
+    const { receiveMessageOnPort } = require("node:worker_threads") as typeof import("node:worker_threads");
+    const bound = (params ?? []).map(v => v === undefined ? null : typeof v === "boolean" ? (v ? 1 : 0) : v);
+    Atomics.store(this.flag, 0, 0);
+    (this.port as any).postMessage({ sql: pgSql, params: bound, guard: this.txDepth > 0 });
+    if (Atomics.wait(this.flag, 0, 0, this.waitMs) === "timed-out") {
+      throw new Error(`PG: no answer from the database worker within ${this.waitMs}ms`);
     }
-    return JSON.parse(proc.stdout.toString().trim());
+    const reply = receiveMessageOnPort(this.port as any)?.message as any;
+    if (!reply) throw new Error("PG: database worker signalled without a reply");
+    if (!reply.ok) throw new Error(`PG: ${reply.error}`);
+    return reply;
+  }
+
+  private querySync(sql: string, params?: any[]): { rows: any[]; count: number } {
+    return this.request(sqliteToPostgres(sql), params);
   }
 
   run(sql: string, params?: any[]): QueryResult {
     if (sql.trim().toUpperCase().startsWith("PRAGMA")) return { changes: 0 };
     const result = this.querySync(sql, params);
-    return { changes: result.rowCount };
+    return { changes: result.count };
+  }
+
+  /** bun:sqlite also accepts get(sql, [a, b]); a lone array argument is the parameter list. */
+  private static bindArgs(params: any[]): any[] | undefined {
+    if (params.length === 1 && Array.isArray(params[0])) return params[0];
+    return params.length > 0 ? params : undefined;
   }
 
   get<T = any>(sql: string, ...params: any[]): T | null {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows?.[0] as T) ?? null;
   }
 
   all<T = any>(sql: string, ...params: any[]): T[] {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows as T[]) ?? [];
   }
 
@@ -183,9 +318,9 @@ export class PgAdapter implements DbAdapter {
     if (sql.trim().toUpperCase().startsWith("PRAGMA")) return;
     const pgSql = sqliteToPostgres(sql);
     // Split multi-statement DDL (CREATE TABLE; CREATE INDEX; ...)
-    const stmts = pgSql.split(";").map(s => s.trim()).filter(s => s.length > 0);
+    const stmts = splitSqlStatements(pgSql);
     for (const stmt of stmts) {
-      try { this.querySync(stmt); } catch (e: any) {
+      try { this.request(stmt); } catch (e: any) {
         // Ignore "already exists" errors for CREATE TABLE/INDEX IF NOT EXISTS
         if (!/already exists/.test(e.message)) throw e;
       }
@@ -193,29 +328,60 @@ export class PgAdapter implements DbAdapter {
   }
 
   transaction<T>(fn: () => T): T {
-    // Not atomic for PostgreSQL until P0-4 is implemented; see class TODO.
-    this.querySync("BEGIN");
+    const depth = this.txDepth;
+    const savepoint = `anet_tx_${depth}`;
+    // Control statements run unguarded: they are what the guard is made of.
+    this.txDepth = 0;
+    try { this.request(depth === 0 ? "BEGIN" : `SAVEPOINT ${savepoint}`); } finally { this.txDepth = depth; }
+    this.txDepth = depth + 1;
+    let result: T;
     try {
-      const result = fn();
-      this.querySync("COMMIT");
-      return result;
+      result = fn();
     } catch (e) {
-      try { this.querySync("ROLLBACK"); } catch {}
+      this.txDepth = 0;
+      try {
+        if (depth === 0) this.request("ROLLBACK");
+        else { this.request(`ROLLBACK TO SAVEPOINT ${savepoint}`); this.request(`RELEASE SAVEPOINT ${savepoint}`); }
+      } catch {}
+      this.txDepth = depth;
       throw e;
     }
+    this.txDepth = 0;
+    try { this.request(depth === 0 ? "COMMIT" : `RELEASE SAVEPOINT ${savepoint}`); } finally { this.txDepth = depth; }
+    return result;
   }
 
-  close(): void {}
+  close(): void {
+    this.worker.terminate();
+  }
 }
 
 // ════════════════════════════════════════════
 //  Factory
 // ════════════════════════════════════════════
 
+export type DbTarget =
+  | { kind: "postgres"; url: string }
+  | { kind: "sqlite"; path: string };
+
 /**
- * Create the appropriate adapter based on environment.
- * - DATABASE_URL starts with "postgres://" → PgAdapter
- * - Otherwise → SQLiteAdapter with COMMHUB_DB or default path
+ * Refuse every inherited DATABASE_URL under the Bun test environment before
+ * adapter selection, logging, DNS, or construction. A test that intentionally
+ * exercises PostgreSQL needs a separately reviewed isolated harness; accepting
+ * a shell/CI DATABASE_URL here could connect a unit test to production.
+ */
+export function assertSafeTestDatabaseEnv(env: NodeJS.ProcessEnv = process.env): void {
+  if (env.NODE_ENV === "test" && env.DATABASE_URL) {
+    throw new Error(
+      "[commhub] REFUSING to honor inherited DATABASE_URL under NODE_ENV=test.\n" +
+      "  Tests must unset DATABASE_URL and set COMMHUB_DB to an isolated path.\n" +
+      "  This guard is fail-closed and has no opt-in bypass."
+    );
+  }
+}
+
+/**
+ * Pure target selection after the inherited-DATABASE_URL safety gate.
  *
  * Test-default-prod GUARD: when `NODE_ENV === "test"` (set automatically by
  * `bun test`) AND `COMMHUB_DB` is unset, we REFUSE to fall through to the
@@ -227,27 +393,67 @@ export class PgAdapter implements DbAdapter {
  * pre-existing history of test pollution in the same DB). The guard makes
  * the failure mode loud + actionable instead of silent + destructive.
  *
- * The guard does NOT fire when:
- *   - COMMHUB_DB is set (the test runner's documented contract); or
- *   - NODE_ENV is unset (production server) or any non-"test" value.
+ * The production default path is a capability, not a generic fallback:
+ * only canonical server entrypoints set COMMHUB_SERVER=1 before importing
+ * the database graph. Tests, scripts, and `bun -e` probes must name an
+ * explicit COMMHUB_DB (or a reviewed PostgreSQL DATABASE_URL), so forgetting
+ * one fails before mkdir/open/write instead of touching the live Hub.
+ */
+/**
+ * RFC-039 §9 — the one reviewed way a `bun test` process may use PostgreSQL.
  *
- * Operators who run `bun -e` snippets that touch the DB are expected to
- * `COMMHUB_DB=/tmp/...` themselves — `bun -e` doesn't set NODE_ENV, so the
- * guard can't catch that case. The rule (never read or write the
- * production hub database) is documented in CLAUDE.md.
+ * The inherited-DATABASE_URL guard stays absolute. A test that means to run
+ * on PostgreSQL names a *different* variable, COMMHUB_TEST_PG_URL, which is
+ * honoured only under NODE_ENV=test and only for a literal loopback host and
+ * a database called `anet_…_test`, so it cannot reach a real Hub database by
+ * accident. Error messages never carry credentials.
  */
-export function createAdapter(): DbAdapter {
-  const dbUrl = process.env.DATABASE_URL;
+export const TEST_PG_URL_ENV = "COMMHUB_TEST_PG_URL";
+const TEST_PG_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const TEST_PG_DB_RE = /^anet_[a-z0-9_]*_test$/;
+const TEST_PG_QUERY_KEYS = new Set(["connect_timeout", "sslmode", "application_name"]);
+
+/** A PostgreSQL URL with user and password replaced, safe to print. */
+export function redactPgUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    if (u.username || u.password) { u.username = "***"; u.password = ""; }
+    return u.toString();
+  } catch {
+    return "<unparseable URL>";
+  }
+}
+
+export function validateTestPgUrl(raw: string): string {
+  const refuse = (why: string) => new Error(
+    `[commhub] REFUSING ${TEST_PG_URL_ENV}=${redactPgUrl(raw)}: ${why}.\n` +
+    "  It is test-only: postgres(ql)://<user>:<password>@127.0.0.1|localhost|[::1][:port]/anet_<name>_test",
+  );
+  let u: URL;
+  try { u = new URL(raw); } catch { throw refuse("not a URL"); }
+  if (u.protocol !== "postgres:" && u.protocol !== "postgresql:") throw refuse("scheme must be postgres:// or postgresql://");
+  if (!TEST_PG_HOSTS.has(u.hostname)) throw refuse("host must be literally 127.0.0.1, localhost or ::1");
+  const dbName = decodeURIComponent(u.pathname.replace(/^\//, ""));
+  if (!TEST_PG_DB_RE.test(dbName)) throw refuse("database name must match /^anet_[a-z0-9_]*_test$/");
+  for (const key of u.searchParams.keys()) {
+    if (!TEST_PG_QUERY_KEYS.has(key)) throw refuse(`query parameter "${key}" is not allowed`);
+  }
+  return raw;
+}
+
+function resolveDatabaseTargetAfterGuard(env: NodeJS.ProcessEnv): DbTarget {
+  const testPgUrl = env[TEST_PG_URL_ENV];
+  if (env.NODE_ENV === "test" && testPgUrl) {
+    return { kind: "postgres", url: validateTestPgUrl(testPgUrl) };
+  }
+
+  const dbUrl = env.DATABASE_URL;
   if (dbUrl && (dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://"))) {
-    console.log("[commhub] database: PostgreSQL");
-    return new PgAdapter(dbUrl);
+    return { kind: "postgres", url: dbUrl };
   }
-  // Default: SQLite
-  const { mkdirSync } = require("fs");
-  const { dirname } = require("path");
 
   // Test-default-prod GUARD (see docblock above).
-  if (process.env.NODE_ENV === "test" && !process.env.COMMHUB_DB) {
+  if (env.NODE_ENV === "test" && !env.COMMHUB_DB) {
     throw new Error(
       "[commhub] REFUSING to open the default SQLite database under NODE_ENV=test.\n" +
       "  Tests must explicitly set COMMHUB_DB to a throwaway path so they don't\n" +
@@ -257,10 +463,40 @@ export function createAdapter(): DbAdapter {
     );
   }
 
-  const dbPath = process.env.COMMHUB_DB || `${process.env.HOME}/.commhub/commhub.db`;
-  mkdirSync(dirname(dbPath), { recursive: true });
-  console.log(`[commhub] database: ${dbPath}`);
-  const rawDb = new Database(dbPath);
+  if (!env.COMMHUB_DB && env.COMMHUB_SERVER !== "1") {
+    throw new Error(
+      "[commhub] REFUSING to open the default production SQLite database from a non-server entrypoint.\n" +
+      "  Scripts and probes must set an explicit COMMHUB_DB path. The canonical\n" +
+      "  Hub entrypoints set COMMHUB_SERVER=1 before loading the database."
+    );
+  }
+
+  return { kind: "sqlite", path: env.COMMHUB_DB || `${env.HOME}/.commhub/commhub.db` };
+}
+
+/** Pure public resolver used by tests without constructing an adapter. */
+export function resolveDatabaseTarget(env: NodeJS.ProcessEnv = process.env): DbTarget {
+  assertSafeTestDatabaseEnv(env);
+  return resolveDatabaseTargetAfterGuard(env);
+}
+
+/**
+ * Create the appropriate adapter based on environment.
+ * The inherited-DATABASE_URL guard is deliberately the first executable line.
+ */
+export function createAdapter(): DbAdapter {
+  assertSafeTestDatabaseEnv(process.env);
+  const target = resolveDatabaseTargetAfterGuard(process.env);
+  if (target.kind === "postgres") {
+    console.log("[commhub] database: PostgreSQL");
+    return new PgAdapter(target.url);
+  }
+
+  const { mkdirSync } = require("fs");
+  const { dirname } = require("path");
+  mkdirSync(dirname(target.path), { recursive: true });
+  console.log(`[commhub] database: ${target.path}`);
+  const rawDb = new Database(target.path);
   rawDb.exec("PRAGMA journal_mode=WAL");
   rawDb.exec("PRAGMA busy_timeout=5000");
   return new SQLiteAdapter(rawDb);

package/src/db-timestamp.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+
+const NAIVE = "2026-08-27 11:23:54";
+const EXPECTED = Date.UTC(2026, 7, 27, 11, 23, 54);
+
+describe("parseDbTimestampMs", () => {
+  // ⚠ 这条在 **TZ=UTC 的环境**下没有分辨力：裸 Date.parse 在 UTC 下恰好正确。
+  // CI runner 与容器默认就是 UTC（本仓 Docker 套件亦然），所以缺陷在常规跑法里
+  // 恒绿。（更正：Bun 是尊重 TZ 的，不存在"bun test 固定 UTC"——通信评审牛 #1279
+  // 独审③ 独立复跑证伪了我最初的说法。）真正稳定见红的门是下面那条强制子进程。
+  it("treats a naive SQLite timestamp as UTC", () => {
+    expect(parseDbTimestampMs(NAIVE)).toBe(EXPECTED);
+  });
+
+  // 分辨力关键：宿主是 UTC 时,裸 Date.parse 与正确写法结果相同,断言恒绿。
+  // 强制子进程 TZ=Asia/Shanghai,让缺陷在任何 CI 时区下都显形。
+  it("is unaffected by a non-UTC host timezone (child process TZ=Asia/Shanghai)", () => {
+    const r = Bun.spawnSync({
+      cmd: ["bun", "-e",
+        `const {parseDbTimestampMs} = await import("${import.meta.dir}/db-timestamp.ts");` +
+        `console.log(parseDbTimestampMs("${NAIVE}"));`],
+      env: { ...process.env, TZ: "Asia/Shanghai" },
+    });
+    expect(Number(r.stdout.toString().trim())).toBe(EXPECTED);
+  });
+
+  it("keeps explicit-offset timestamps intact", () => {
+    expect(parseDbTimestampMs("2026-08-27T11:23:54Z")).toBe(EXPECTED);
+    expect(parseDbTimestampMs("2026-08-27T19:23:54+08:00")).toBe(EXPECTED);
+  });
+
+  it("an online window of 5min holds for a heartbeat written 1s ago", () => {
+    const now = Date.now();
+    const iso = new Date(now - 1000).toISOString().slice(0, 19).replace("T", " ");
+    expect(now - parseDbTimestampMs(iso)).toBeLessThanOrEqual(5 * 60_000);
+  });
+});

package/src/db-timestamp.ts

@@ -0,0 +1,15 @@
+/**
+ * SQLite 里的时间戳列（sessions.last_seen_at、tasks.created_at 等）存的是
+ * **无时区标记的 UTC 串**（`YYYY-MM-DD HH:MM:SS`，由 SQLite `datetime('now')` 写入）。
+ *
+ * 裸 `Date.parse("2026-08-27 11:23:54")` 会按**宿主机本地时区**解释这个串。
+ * 生产机 TZ=CST+0800 时，它比真实 UTC 时刻早 8 小时——所以 `now - parsed`
+ * 恒为 +480 分钟，任何「最近 N 秒内算在线」的判据都会恒判离线。
+ * 在 TZ=UTC 的机器上两种写法结果相同，缺陷不会显形。
+ */
+export function parseDbTimestampMs(value: string): number {
+  const s = String(value).trim();
+  // 已带时区标记（ISO 的 Z / ±HH:MM）就原样交给 Date
+  if (/[Zz]$|[+-]\d{2}:?\d{2}$/.test(s)) return Date.parse(s);
+  return Date.parse(s.replace(" ", "T") + "Z");
+}