fix(db): detect WSL2 and adjust pgserve startup timeout

src/lib/db.ts

@@ -13,6 +13,7 @@ import { join } from 'node:path';
 import type postgres from 'postgres';
 import { runMigrations } from './db-migrations.js';
 import { needsSeed, runSeed } from './pg-seed.js';
+import { isWSL2 } from './wsl2-detect.js';
 
 /**
  * Re-export Sql type for callers that need to annotate sql connection parameters.
@@ -327,10 +328,16 @@ function findPgserveBin(): string {
  * Avoids the self-referencing proxy deadlock that occurs when the
  * MultiTenantRouter Bun TCP proxy runs in the same event loop as
  * the daemon that also connects to it.
+ *
+ * On WSL2, uses an extended timeout (30s) due to slower I/O performance.
  */
 async function startPgserveOnPort(port: number): Promise<number> {
   mkdirSync(DATA_DIR, { recursive: true });
 
+  const isWsl = isWSL2();
+  const timeoutMs = isWsl ? 30000 : 15000;
+  const timeoutSec = timeoutMs / 1000;
+
   const child = spawn(
     findPgserveBin(),
     [
@@ -352,7 +359,13 @@ async function startPgserveOnPort(port: number): Promise<number> {
   child.unref();
   pgserveChild = child;
 
-  const deadline = Date.now() + 15000;
+  const initialBootstrapMs = isWsl ? 2000 : 100;
+  await new Promise((r) => setTimeout(r, initialBootstrapMs));
+
+  const deadline = Date.now() + timeoutMs;
+  let retryDelayMs = 100;
+  const maxRetryDelayMs = 1000;
+
   while (Date.now() < deadline) {
     if (await isPostgresHealthy(port)) {
       activePort = port;
@@ -361,15 +374,19 @@ async function startPgserveOnPort(port: number): Promise<number> {
       writeLockfile(port);
       return port;
     }
-    await new Promise((r) => setTimeout(r, 500));
+
+    await new Promise((r) => setTimeout(r, retryDelayMs));
+    retryDelayMs = Math.min(Math.floor(retryDelayMs * 1.5), maxRetryDelayMs);
   }
 
   try {
     child.kill('SIGTERM');
   } catch {
     /* dead */
   }
-  throw new Error(`pgserve failed to start on port ${port} (timeout after 15s)`);
+
+  process.env.GENIE_PG_AVAILABLE = 'false';
+  throw new Error(`pgserve failed to start on port ${port} (timeout after ${timeoutSec}s)`);
 }
 
 /** Register process exit handler to clean up lockfile (once). */

src/lib/mailbox.ts

@@ -1,13 +1,30 @@
 /**
  * Mailbox — Durable message store with unread/read semantics.
  *
+ * ## Migration note (commit 44a153a3)
+ *
+ * Previously messages were written to `.genie/mailbox/<worker>.json` files and
+ * delivered by a polling loop that woke up every few seconds to check for new
+ * entries. This introduced latency proportional to the poll interval and made
+ * cross-process coordination fragile.
+ *
+ * The current implementation replaced file-based polling with PostgreSQL:
+ *  - Messages are persisted to the `mailbox` table (durable, queryable).
+ *  - A `AFTER INSERT` trigger fires `pg_notify('genie_mailbox_delivery', …)`
+ *    with payload `<to_worker>:<message_id>`.
+ *  - `subscribeDelivery()` calls `sql.listen('genie_mailbox_delivery', …)` so
+ *    the scheduler daemon receives the notification instantly — no polling.
+ *  - A 30-second fallback poll catches any notifications missed during
+ *    reconnects or daemon restarts.
+ *
+ * `.genie/mailbox/` JSON files are no longer written or read; references to
+ * that path in older docs are outdated.
+ *
  * Messages persist to PostgreSQL `mailbox` table before any push delivery
  * attempt. This ensures durability (DEC-7).
  *
  * Delivery is state-aware: messages are queued and pushed to tmux
  * panes only when the worker is idle (not mid-turn).
- *
- * PG LISTEN/NOTIFY triggers instant delivery notification on new inserts.
  */
 
 import { v4 as uuidv4 } from 'uuid';

src/lib/wsl2-detect.ts

@@ -0,0 +1,31 @@
+/**
+ * WSL2 environment detection.
+ *
+ * Genie on WSL2 experiences slower pgserve startup due to I/O characteristics.
+ * This utility detects WSL2 and allows callers to adjust timeouts accordingly.
+ */
+
+import { readFileSync } from 'node:fs';
+
+let memoized: boolean | null = null;
+
+/**
+ * Detect if running on WSL2 by checking /proc/version for "microsoft" or "wsl".
+ * Result is memoized for performance.
+ *
+ * @returns true if running on WSL2, false otherwise
+ */
+export function isWSL2(): boolean {
+  // Return memoized result if already computed
+  if (memoized !== null) return memoized;
+
+  try {
+    const procVersion = readFileSync('/proc/version', 'utf-8');
+    memoized = procVersion.toLowerCase().includes('microsoft') || procVersion.toLowerCase().includes('wsl');
+    return memoized;
+  } catch {
+    // /proc/version not readable (non-Linux or permission issue) — assume not WSL2
+    memoized = false;
+    return false;
+  }
+}