@@ -294,6 +294,18 @@ jobs:
           TEST_PG_PORT: "15432"
           TEST_PG_PASSWORD: testpass123
 
+      # Needs a dedicated process: four files in test/altimate install a
+      # top-level mock.module("@altimateai/drivers/duckdb", …), and Bun
+      # evaluates every test file's top level before running any test, so in a
+      # whole-directory run these would silently exercise a fake. With
+      # ALTIMATE_DUCKDB_E2E=1 a missing or mocked driver fails the step rather
+      # than skipping it.
+      - name: Run DuckDB store-open E2E (real store, no mocks)
+        run: bun test test/altimate/duckdb-open-e2e.test.ts test/altimate/warehouse-test-duckdb-e2e.test.ts
+        working-directory: packages/opencode
+        env:
+          ALTIMATE_DUCKDB_E2E: "1"
+
       - name: Run Docker driver E2E (MySQL, SQL Server, Redshift)
         run: bun test test/altimate/drivers-docker-e2e.test.ts
         working-directory: packages/opencode
 
@@ -126,6 +126,7 @@
     "printWidth": 120
   },
   "trustedDependencies": [
+    "duckdb",
     "esbuild",
     "node-pty",
     "protobufjs",
 
@@ -4,6 +4,34 @@
 
 import type { ConnectionConfig, Connector, ConnectorResult, ExecuteOptions, SchemaColumn } from "./types"
 
+// altimate_change start — configurable, generous open budget
+/**
+ * How long to wait for DuckDB to finish opening a store before giving up.
+ *
+ * This is a liveness guard, not a performance budget. Opening a store is
+ * dispatched to the libuv threadpool, so the wait covers queueing behind every
+ * other threadpool user in the process (fs, dns, crypto), not just DuckDB's own
+ * work. A busy agent process can therefore push a healthy open well past a
+ * second, and the previous hard-coded 2s ceiling turned that into an
+ * unrecoverable failure on a store that was fine.
+ */
+const DEFAULT_OPEN_TIMEOUT_MS = 30_000
+
+/** Read a positive, finite millisecond budget, or `undefined` if unusable. */
+function positiveMs(value: unknown): number | undefined {
+  const n = typeof value === "number" ? value : Number(value)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+function resolveOpenTimeoutMs(config: ConnectionConfig): number {
+  return (
+    positiveMs(config.open_timeout_ms) ??
+    positiveMs(globalThis.process?.env?.["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]) ??
+    DEFAULT_OPEN_TIMEOUT_MS
+  )
+}
+// altimate_change end
+
 export async function connect(config: ConnectionConfig): Promise<Connector> {
   let duckdb: any
   try {
@@ -14,6 +42,9 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
   }
 
   const dbPath = (config.path as string) ?? ":memory:"
+  // altimate_change start — configurable open budget
+  const openTimeoutMs = resolveOpenTimeoutMs(config)
+  // altimate_change end
   let db: any
   let connection: any
 
@@ -35,10 +66,13 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
 
   function wrapDuckDBError(err: Error): Error {
     if (isLockError(err)) {
+      // Keep DuckDB's own text: it names the PID and executable holding the
+      // conflicting lock, which is the only way to find the other process.
       return new Error(
         `Database "${dbPath}" is locked by another process. ` +
-        `DuckDB does not support concurrent write access. ` +
-        `Close other connections to this file and try again.`,
+        `DuckDB takes an exclusive file lock, so a store already open ` +
+        `read-write elsewhere cannot be opened again — not even read-only. ` +
+        `Close the other connection and try again.\n${err.message || String(err)}`,
       )
     }
     return err
@@ -72,10 +106,15 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
           let timeout: ReturnType<typeof setTimeout> | undefined
           let instance: any
           // Sentinel for an open callback that fired synchronously (before
-          // `instance` was assigned): `undefined` = not yet fired, `null` =
-          // fired with success, `Error` = fired with failure. Replayed once
-          // `instance` exists.
-          let pendingOpen: Error | null | undefined
+          // `instance` was assigned), replayed once `instance` exists.
+          //
+          // This MUST be a value the callback can never supply. It used to be
+          // `undefined`, which is exactly what a success callback invoked with
+          // no arguments passes — so such a callback was recorded and then
+          // never replayed, the promise never settled, and the open failed on
+          // the deadline below with a timeout message that named nothing.
+          const NOT_FIRED = Symbol("duckdb-open-not-fired")
+          let pendingOpen: Error | null | typeof NOT_FIRED = NOT_FIRED
           const opts = accessMode ? { access_mode: accessMode } : undefined
           const closeQuietly = () => {
             try {
@@ -84,9 +123,12 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
               // best-effort cleanup of a half-open handle
             }
           }
-          const onOpen = (err: Error | null) => {
+          const onOpen = (err?: Error | null) => {
+            // Normalise a zero-argument success callback to `null` so it is
+            // never confused with "has not fired yet".
+            const outcome = err ?? null
             if (!instance) {
-              pendingOpen = err
+              pendingOpen = outcome
               return
             }
             if (resolved) {
@@ -95,32 +137,37 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
             }
             resolved = true
             if (timeout) clearTimeout(timeout)
-            if (err) {
+            if (outcome) {
               // Open failed — release the half-open handle so it doesn't leak.
+              // Reject with DuckDB's own error: callers classify it with
+              // isLockError(), and its text names the conflicting process.
               closeQuietly()
-              const msg = err.message || String(err)
-              if (msg.toLowerCase().includes("locked") || msg.includes("SQLITE_BUSY") || msg.includes("DUCKDB_LOCKED")) {
-                reject(new Error("DUCKDB_LOCKED"))
-              } else {
-                reject(err)
-              }
+              reject(outcome)
             } else {
               resolve(instance)
             }
           }
           instance = opts
             ? new duckdb.Database(dbPath, opts, onOpen)
             : new duckdb.Database(dbPath, onOpen)
-          // Bun: native callback may not fire; fall back after 2s. Arm the timer
-          // BEFORE replaying a synchronous callback so a sync resolve/reject can
-          // actually clear it (otherwise it lingers ~2s and delays process exit).
+          // Liveness guard against an open callback that never fires. Arm the
+          // timer BEFORE replaying a synchronous callback so a sync
+          // resolve/reject can actually clear it (otherwise it lingers and
+          // delays process exit).
           timeout = setTimeout(() => {
             if (!resolved) {
               resolved = true
-              reject(new Error(`Timed out opening DuckDB database "${dbPath}"`))
+              reject(
+                new Error(
+                  `DuckDB store "${dbPath}" did not finish opening within ${openTimeoutMs}ms. ` +
+                  `This is a client-side deadline in the DuckDB driver, not a fault in the store ` +
+                  `— the open may simply be queued behind other work in this process. ` +
+                  `Raise it with ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS if the machine is loaded.`,
+                ),
+              )
             }
-          }, 2000)
-          if (pendingOpen !== undefined) onOpen(pendingOpen)
+          }, openTimeoutMs)
+          if (pendingOpen !== NOT_FIRED) onOpen(pendingOpen)
         })
 
       // altimate_change start — honour an explicit read-only connection.
 
@@ -54,7 +54,10 @@ describe("DuckDB driver", () => {
         expect.unreachable("Should have thrown")
       } catch (e: any) {
         expect(e.message).toContain("locked by another process")
-        expect(e.message).toContain("does not support concurrent write access")
+        expect(e.message).toContain("exclusive file lock")
+        // DuckDB's own text names the PID holding the lock, so it must survive
+        // being wrapped rather than being replaced by the friendly summary.
+        expect(e.message).toContain("SQLITE_BUSY: database is locked")
       }
 
       await connector.close()
 
@@ -282,6 +282,12 @@ export function detectAuthMethod(config: ConnectionConfig | null | undefined): s
 export function categorizeConnectionError(e: unknown): string {
   const msg = String(e).toLowerCase()
   if (msg.includes("not installed") || msg.includes("cannot find module")) return "driver_missing"
+  // altimate_change start — categories for local-client faults
+  // Checked before the generic "timeout"/"not found" rules below, which are
+  // about the remote warehouse and would otherwise swallow these.
+  if (msg.includes("did not finish opening")) return "driver_open_timeout"
+  if (msg.includes("locked by another process")) return "store_locked"
+  // altimate_change end
   if (msg.includes("password") || msg.includes("authentication") || msg.includes("unauthorized") || msg.includes("jwt"))
     return "auth_failed"
   if (msg.includes("timeout") || msg.includes("timed out")) return "timeout"
@@ -290,6 +296,19 @@ export function categorizeConnectionError(e: unknown): string {
   return "other"
 }
 
+// altimate_change start — distinguish infrastructure faults from config faults
+/**
+ * Categories where the local client is broken, not the connection's config and
+ * not the remote warehouse. A caller cannot fix these by correcting
+ * credentials, and a harness must not score them as a task failure.
+ */
+const INFRASTRUCTURE_CATEGORIES = new Set(["driver_missing", "driver_open_timeout", "store_locked"])
+
+export function isInfrastructureFailure(category: string): boolean {
+  return INFRASTRUCTURE_CATEGORIES.has(category)
+}
+// altimate_change end
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -405,7 +424,9 @@ export function list(): { warehouses: WarehouseInfo[] } {
 }
 
 /** Test a connection by running a simple query. */
-export async function test(name: string): Promise<{ connected: boolean; error?: string }> {
+export async function test(
+  name: string,
+): Promise<{ connected: boolean; error?: string; error_category?: string; infrastructure?: boolean }> {
   try {
     const connector = await get(name)
     const config = configs.get(name)
@@ -422,7 +443,15 @@ export async function test(name: string): Promise<{ connected: boolean; error?:
     }
     return { connected: true }
   } catch (e) {
-    return { connected: false, error: String(e) }
+    // altimate_change start — report *why* the test failed, not just that it did
+    const category = categorizeConnectionError(e)
+    return {
+      connected: false,
+      error: String(e),
+      error_category: category,
+      infrastructure: isInfrastructureFailure(category),
+    }
+    // altimate_change end
   }
 }
 
 
@@ -329,6 +329,17 @@ export interface WarehouseTestParams {
 export interface WarehouseTestResult {
   connected: boolean
   error?: string
+  // altimate_change start — distinguish infrastructure faults from config faults
+  /** Coarse cause, from `categorizeConnectionError` (e.g. `driver_missing`, `auth_failed`). */
+  error_category?: string
+  /**
+   * True when the failure is in the local client — a driver that will not load,
+   * an open that never completed — rather than in the connection's
+   * configuration or the remote warehouse. These are not the caller's fault and
+   * are not fixable by editing the connection.
+   */
+  infrastructure?: boolean
+  // altimate_change end
 }
 
 // --- Warehouse Management ---
 
@@ -20,9 +20,35 @@ export const WarehouseTestTool = Tool.define("warehouse_test", {
         }
       }
 
+      // altimate_change start — never let a broken client look like a bad connection
+      // A driver that will not load, or an open that never completed, is a
+      // fault in this machine's install. Reporting it with the same wording as
+      // a wrong password invites both the model and anyone reading the
+      // transcript to treat broken infrastructure as a task or config failure.
+      if (result.infrastructure) {
+        return {
+          title: `Connection '${args.name}': INFRASTRUCTURE FAILURE`,
+          metadata: {
+            connected: false,
+            error: result.error,
+            error_category: result.error_category,
+            infrastructure: true,
+          },
+          output:
+            `INFRASTRUCTURE FAILURE — the warehouse client on this machine is broken. ` +
+            `This is NOT a problem with the connection's configuration, and NOT something ` +
+            `to work around by trying a different query or a different tool.\n` +
+            `Category: ${result.error_category}\n` +
+            `Error: ${result.error ?? "Unknown error"}\n\n` +
+            `Stop and report this rather than continuing — results produced after this ` +
+            `point did not come from warehouse '${args.name}'.`,
+        }
+      }
+      // altimate_change end
+
       return {
         title: `Connection '${args.name}': FAILED`,
-        metadata: { connected: false },
+        metadata: { connected: false, error: result.error, error_category: result.error_category },
         output: `Failed to connect to warehouse '${args.name}'.\nError: ${result.error ?? "Unknown error"}`,
       }
     } catch (e) {