@agent-native/core 0.77.8 → 0.77.10

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1933
-- template files: 4289
+- template files: 4293

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @agent-native/core
 
+## 0.77.10
+
+### Patch Changes
+
+- 12545bc: Keep standalone scaffold installs stable when fresh Sentry transitive packages are published.
+
+## 0.77.9
+
+### Patch Changes
+
+- 3eeec7f: Generalize the `ensureTable()` DDL guard to ALL on-demand schema-init paths
+  (~36 stores: agent run-store, application-state, chat-threads, usage,
+  oauth-tokens, resources, observability, integrations, provider-api, mcp,
+  workspace-connections, extensions, audit, harness, a2a, notifications,
+  browser-sessions, auth/sessions, agent-teams run-queue, better-auth, and more).
+
+  Every `ensureTable` now probes `information_schema`/`pg_indexes` before issuing
+  `CREATE TABLE`/`ALTER TABLE ADD COLUMN`/`CREATE INDEX`, so the already-migrated
+  hot path takes NO `ACCESS EXCLUSIVE` lock on Postgres. Any DDL that must run is
+  wrapped in a transaction-scoped `SET LOCAL lock_timeout` (never leaks onto the
+  pooled connection), and a swallowed lock-timeout triggers a RE-PROBE: if the
+  schema is still missing it throws (so the per-store init memo rejects and retries)
+  rather than memoizing init success against absent schema. This fixes
+  background-function (durable agent-chat) workers hanging indefinitely on the
+  first-touch DDL lock of any table on shared Neon. Shared helpers live in
+  `db/ddl-guard.ts` (`ensureSchemaObject`/`ensureTableExists`/`ensureColumnExists`/
+  `ensureIndexExists`). SQLite (local dev) behavior is unchanged. CREATE SQL that
+  references `intType()` is built at runtime, not module scope.
+
 ## 0.77.8
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.77.8",
+  "version": "0.77.10",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/a2a/task-store.ts

@@ -1,6 +1,7 @@
 import crypto from "crypto";
 
-import { getDbExec, intType } from "../db/client.js";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureTableExists, ensureColumnExists } from "../db/ddl-guard.js";
 import type { Task, Message, TaskState, Artifact } from "./types.js";
 
 let _initPromise: Promise<void> | undefined;
@@ -9,7 +10,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS a2a_tasks (
           id TEXT PRIMARY KEY,
           context_id TEXT,
@@ -22,7 +23,28 @@ async function ensureTable(): Promise<void> {
           created_at ${intType()} NOT NULL,
           updated_at ${intType()} NOT NULL
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema before issuing DDL to avoid ACCESS
+        // EXCLUSIVE lock contention in fresh background-worker processes.
+        await ensureTableExists("a2a_tasks", createSql);
+        // Additive migration: owner_email column. Bound to the JWT-verified
+        // caller at task-creation time so handleGet / handleCancel can reject
+        // mismatched callers (the IDOR class fixed in PR #369). Existing rows
+        // have NULL owner_email and remain accessible to legacy callers via
+        // the legacy-token apiKeyEnv path; new rows are scoped from this point
+        // forward.
+        await ensureColumnExists(
+          "a2a_tasks",
+          "owner_email",
+          `ALTER TABLE a2a_tasks ADD COLUMN IF NOT EXISTS owner_email TEXT`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       // Additive migration: owner_email column. Bound to the JWT-verified
       // caller at task-creation time so handleGet / handleCancel can reject
       // mismatched callers (the IDOR class fixed in PR #369). Existing rows

package/corpus/core/src/agent/harness/store.ts

@@ -1,9 +1,9 @@
+import { getDbExec, intType, isPostgres } from "../../db/client.js";
 import {
-  getDbExec,
-  intType,
-  isPostgres,
-  retryOnDdlRace,
-} from "../../db/client.js";
+  ensureColumnExists,
+  ensureIndexExists,
+  ensureTableExists,
+} from "../../db/ddl-guard.js";
 
 export type AgentHarnessSessionStatus =
   | "running"
@@ -50,26 +50,66 @@ export async function ensureAgentHarnessSessionTables(): Promise<void> {
   if (!initPromise) {
     initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS agent_harness_sessions (
-            id TEXT PRIMARY KEY,
-            harness_name TEXT NOT NULL,
-            thread_id TEXT NOT NULL,
-            run_id TEXT,
-            provider_session_id TEXT,
-            status TEXT NOT NULL DEFAULT 'idle',
-            resume_state TEXT,
-            workspace_ref TEXT,
-            pending_approval TEXT,
-            owner_email TEXT,
-            org_id TEXT,
-            created_at ${intType()} NOT NULL,
-            updated_at ${intType()} NOT NULL,
-            stopped_at ${intType()}
-          )
-        `),
-      );
+      const createSql = `
+        CREATE TABLE IF NOT EXISTS agent_harness_sessions (
+          id TEXT PRIMARY KEY,
+          harness_name TEXT NOT NULL,
+          thread_id TEXT NOT NULL,
+          run_id TEXT,
+          provider_session_id TEXT,
+          status TEXT NOT NULL DEFAULT 'idle',
+          resume_state TEXT,
+          workspace_ref TEXT,
+          pending_approval TEXT,
+          owner_email TEXT,
+          org_id TEXT,
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL,
+          stopped_at ${intType()}
+        )
+      `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema / pg_indexes before issuing DDL to
+        // avoid ACCESS EXCLUSIVE lock contention in fresh background-worker processes.
+        await ensureTableExists("agent_harness_sessions", createSql);
+        for (const col of [
+          "run_id",
+          "provider_session_id",
+          "resume_state",
+          "workspace_ref",
+          "pending_approval",
+          "owner_email",
+          "org_id",
+        ] as const) {
+          await ensureColumnExists(
+            "agent_harness_sessions",
+            col,
+            `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS ${col} TEXT`,
+          );
+        }
+        await ensureColumnExists(
+          "agent_harness_sessions",
+          "stopped_at",
+          `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS stopped_at ${intType()}`,
+        );
+        await ensureIndexExists(
+          "idx_agent_harness_sessions_thread",
+          `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_thread ON agent_harness_sessions(thread_id, updated_at)`,
+        );
+        await ensureIndexExists(
+          "idx_agent_harness_sessions_status",
+          `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_status ON agent_harness_sessions(status, updated_at)`,
+        );
+        await ensureIndexExists(
+          "idx_agent_harness_sessions_owner",
+          `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_owner ON agent_harness_sessions(owner_email, updated_at)`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       for (const col of [
         "run_id",
         "provider_session_id",
@@ -80,47 +120,41 @@ export async function ensureAgentHarnessSessionTables(): Promise<void> {
         "org_id",
       ] as const) {
         try {
-          if (isPostgres()) {
-            await client.execute(
-              `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS ${col} TEXT`,
-            );
-          } else {
-            await client.execute(
-              `ALTER TABLE agent_harness_sessions ADD COLUMN ${col} TEXT`,
-            );
-          }
+          await client.execute(
+            `ALTER TABLE agent_harness_sessions ADD COLUMN ${col} TEXT`,
+          );
         } catch {
           // Column already exists.
         }
       }
       try {
-        if (isPostgres()) {
-          await client.execute(
-            `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS stopped_at ${intType()}`,
-          );
-        } else {
-          await client.execute(
-            `ALTER TABLE agent_harness_sessions ADD COLUMN stopped_at ${intType()}`,
-          );
-        }
+        await client.execute(
+          `ALTER TABLE agent_harness_sessions ADD COLUMN stopped_at ${intType()}`,
+        );
       } catch {
         // Column already exists.
       }
-      await retryOnDdlRace(() =>
-        client.execute(
+      try {
+        await client.execute(
           `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_thread ON agent_harness_sessions(thread_id, updated_at)`,
-        ),
-      );
-      await retryOnDdlRace(() =>
-        client.execute(
+        );
+      } catch {
+        // Index already exists.
+      }
+      try {
+        await client.execute(
           `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_status ON agent_harness_sessions(status, updated_at)`,
-        ),
-      );
-      await retryOnDdlRace(() =>
-        client.execute(
+        );
+      } catch {
+        // Index already exists.
+      }
+      try {
+        await client.execute(
           `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_owner ON agent_harness_sessions(owner_email, updated_at)`,
-        ),
-      );
+        );
+      } catch {
+        // Index already exists.
+      }
     })().catch((err) => {
       initPromise = undefined;
       throw err;

package/corpus/core/src/agent/observational-memory/store.ts

@@ -12,8 +12,8 @@
  * runtime even before the migration plugin is registered.
  */
 
-import { getDbExec } from "../../db/client.js";
-import { isPostgres } from "../../db/client.js";
+import { getDbExec, isPostgres } from "../../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../../db/ddl-guard.js";
 import type {
   ObservationalMemoryEntry,
   ObservationalMemoryOwner,
@@ -27,8 +27,7 @@ async function ensureTable(): Promise<void> {
   tableReady = (async () => {
     const client = getDbExec();
     const intType = isPostgres() ? "BIGINT" : "INTEGER";
-    await client.execute(
-      `CREATE TABLE IF NOT EXISTS observational_memory (
+    const createSql = `CREATE TABLE IF NOT EXISTS observational_memory (
         id TEXT PRIMARY KEY,
         thread_id TEXT NOT NULL,
         tier TEXT NOT NULL,
@@ -42,16 +41,43 @@ async function ensureTable(): Promise<void> {
         owner_email TEXT NOT NULL,
         org_id TEXT,
         visibility TEXT NOT NULL DEFAULT 'private'
-      )`,
-    );
-    await client.execute(
-      `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx
-        ON observational_memory(thread_id, tier, created_at)`,
-    );
-    await client.execute(
-      `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx
-        ON observational_memory(thread_id, owner_email)`,
-    );
+      )`;
+
+    if (isPostgres()) {
+      // PG-guard: probe information_schema / pg_indexes before issuing DDL to
+      // avoid ACCESS EXCLUSIVE lock contention in fresh background-worker processes.
+      await ensureTableExists("observational_memory", createSql);
+      await ensureIndexExists(
+        "observational_memory_thread_tier_idx",
+        `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx
+          ON observational_memory(thread_id, tier, created_at)`,
+      );
+      await ensureIndexExists(
+        "observational_memory_thread_owner_idx",
+        `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx
+          ON observational_memory(thread_id, owner_email)`,
+      );
+      return;
+    }
+
+    // SQLite (local dev): no lock problem — keep the original behaviour.
+    await client.execute(createSql);
+    try {
+      await client.execute(
+        `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx
+          ON observational_memory(thread_id, tier, created_at)`,
+      );
+    } catch {
+      // Index already exists.
+    }
+    try {
+      await client.execute(
+        `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx
+          ON observational_memory(thread_id, owner_email)`,
+      );
+    } catch {
+      // Index already exists.
+    }
   })().catch((err) => {
     // Reset so a transient failure (e.g. SQLITE_BUSY on HMR) can retry.
     tableReady = null;

package/corpus/core/src/agent/run-store.ts

@@ -4,6 +4,7 @@
  * reliable reconnection after page refreshes.
  */
 import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { captureError } from "../server/capture-error.js";
 import type { AgentChatEvent } from "./types.js";
@@ -82,7 +83,10 @@ async function ensureRunTables(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+
+      // Shared CREATE SQL strings — referenced by both the Postgres and SQLite
+      // branches so the column definitions stay in one place.
+      const agentRunsCreateSql = `
         CREATE TABLE IF NOT EXISTS agent_runs (
           id TEXT PRIMARY KEY,
           thread_id TEXT NOT NULL,
@@ -98,30 +102,117 @@ async function ensureRunTables(): Promise<void> {
           dispatch_mode TEXT,
           diag_stage TEXT
         )
-      `);
-      // Backfill heartbeat_at on older deployments.
-      try {
-        if (isPostgres()) {
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN IF NOT EXISTS heartbeat_at ${intType()}`,
-          );
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN IF NOT EXISTS abort_reason TEXT`,
-          );
-        } else {
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN heartbeat_at ${intType()}`,
+      `;
+      const agentRunEventsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_run_events (
+          run_id TEXT NOT NULL,
+          seq ${intType()} NOT NULL,
+          event_data TEXT NOT NULL,
+          PRIMARY KEY (run_id, seq)
+        )
+      `;
+      // Tool-call result ledger: persists the outcome of write tool calls that
+      // completed AFTER their chunk was abandoned (zombie completions). A
+      // resumed continuation can recover the real result by matching
+      // thread_id + tool_key (name:stableInputHash) instead of re-executing
+      // the side effect. Entries are scoped to the thread and expire with it.
+      const agentToolLedgerCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_tool_ledger (
+          thread_id TEXT NOT NULL,
+          tool_key TEXT NOT NULL,
+          result_summary TEXT NOT NULL,
+          completed_at ${intType()} NOT NULL,
+          PRIMARY KEY (thread_id, tool_key)
+        )
+      `;
+
+      if (isPostgres()) {
+        // Hot path: in production the tables and all additive columns are
+        // virtually always already present. Issuing `CREATE TABLE`/`ALTER TABLE
+        // ADD COLUMN` still takes an ACCESS EXCLUSIVE lock — which, in a fresh
+        // background-worker process behind a concurrent connection on the shared
+        // Neon DB, can block ~indefinitely. So check `information_schema` first
+        // (plain reads, no lock) and run DDL ONLY for what is actually missing.
+        // The `ensureTableExists` / `ensureColumnExists` wrappers probe →
+        // guarded-DDL (bounded `lock_timeout`) → re-probe, and THROW if the
+        // schema is still missing after a swallowed lock-timeout so a poisoned
+        // init never memoizes success against absent schema (the `_initPromise`
+        // rejects and the next call retries).
+        await ensureTableExists("agent_runs", agentRunsCreateSql);
+        // Additive columns — all listed in the CREATE TABLE above, so on a
+        // fresh DB they already exist after the CREATE and these checks are
+        // instant short-circuits. On an older deployment that predates a
+        // column, the wrapper issues one bounded ALTER.
+        //
+        // Backfill heartbeat_at on older deployments.
+        // heartbeat_at = "the producer process is alive" (bumped on a timer).
+        // last_progress_at = "the agent is actually emitting events" (bumped on
+        // each emit). The gap between them is the stuck-detector signal.
+        for (const [col, colType] of [
+          ["heartbeat_at", intType()],
+          ["abort_reason", "TEXT"],
+          ["last_progress_at", intType()],
+          // Backfill turn_id / error_code / error_detail.
+          //   turn_id    = stable identity for one logical assistant turn that may
+          //                span several continuation runs, so the durable record
+          //                can be folded across runs instead of dropped per-run.
+          //   error_code / error_detail = terminal failure classification captured
+          //                at completion so errored/cut-off runs are queryable for
+          //                pattern analysis (see listErroredRuns).
+          // dispatch_mode marks how a run was started: NULL/"foreground" for the
+          // normal synchronous path, "background" for a run dispatched into a
+          // Netlify background function. The reaper/claim widen the stale window
+          // for background rows so a slow cold-start isn't falsely reaped.
+          // diag_stage records the last reached pipeline stage (+ any error) for a
+          // background-dispatched run so a silent worker death is DIAGNOSABLE from
+          // the client (/runs/active surfaces it) without reading the unreadable
+          // Netlify background-function logs. See recordRunDiagnostic.
+          ["turn_id", "TEXT"],
+          ["error_code", "TEXT"],
+          ["error_detail", "TEXT"],
+          ["dispatch_mode", "TEXT"],
+          ["diag_stage", "TEXT"],
+        ] as const) {
+          await ensureColumnExists(
+            "agent_runs",
+            col,
+            `ALTER TABLE agent_runs ADD COLUMN IF NOT EXISTS ${col} ${colType}`,
           );
         }
+        await ensureTableExists("agent_run_events", agentRunEventsCreateSql);
+        await ensureTableExists("agent_tool_ledger", agentToolLedgerCreateSql);
+        // Widen millisecond-timestamp columns that older deployments created as
+        // 32-bit `INTEGER`. `insertRun()` writes `Date.now()` into `started_at`
+        // on every turn, so an int4 column makes every agent prompt fail on
+        // Postgres with "value … is out of range for type integer". No-op once
+        // widened (and on fresh DBs that already use BIGINT). See
+        // widenIntColumnsToBigInt.
+        await widenIntColumnsToBigInt("agent_runs", [
+          "started_at",
+          "completed_at",
+          "heartbeat_at",
+          "last_progress_at",
+        ]);
+        await widenIntColumnsToBigInt("agent_tool_ledger", ["completed_at"]);
+        return;
+      }
+
+      // SQLite (local dev): no ACCESS EXCLUSIVE lock problem — keep the
+      // original create-then-additive-alter behaviour. SQLite has no
+      // `ADD COLUMN IF NOT EXISTS`, so the ALTERs stay wrapped in try/catch.
+      await client.execute(agentRunsCreateSql);
+      // Backfill heartbeat_at on older deployments.
+      try {
+        await client.execute(
+          `ALTER TABLE agent_runs ADD COLUMN heartbeat_at ${intType()}`,
+        );
       } catch {
         // Column already exists — ignore
       }
       try {
-        if (!isPostgres()) {
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN abort_reason TEXT`,
-          );
-        }
+        await client.execute(
+          `ALTER TABLE agent_runs ADD COLUMN abort_reason TEXT`,
+        );
       } catch {
         // Column already exists — ignore
       }
@@ -130,15 +221,9 @@ async function ensureRunTables(): Promise<void> {
       // last_progress_at = "the agent is actually emitting events" (bumped on
       // each emit). The gap between them is the stuck-detector signal.
       try {
-        if (isPostgres()) {
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN IF NOT EXISTS last_progress_at ${intType()}`,
-          );
-        } else {
-          await client.execute(
-            `ALTER TABLE agent_runs ADD COLUMN last_progress_at ${intType()}`,
-          );
-        }
+        await client.execute(
+          `ALTER TABLE agent_runs ADD COLUMN last_progress_at ${intType()}`,
+        );
       } catch {
         // Column already exists — ignore
       }
@@ -165,41 +250,13 @@ async function ensureRunTables(): Promise<void> {
         "diag_stage",
       ] as const) {
         try {
-          if (isPostgres()) {
-            await client.execute(
-              `ALTER TABLE agent_runs ADD COLUMN IF NOT EXISTS ${col} TEXT`,
-            );
-          } else {
-            await client.execute(
-              `ALTER TABLE agent_runs ADD COLUMN ${col} TEXT`,
-            );
-          }
+          await client.execute(`ALTER TABLE agent_runs ADD COLUMN ${col} TEXT`);
         } catch {
           // Column already exists — ignore
         }
       }
-      await client.execute(`
-        CREATE TABLE IF NOT EXISTS agent_run_events (
-          run_id TEXT NOT NULL,
-          seq ${intType()} NOT NULL,
-          event_data TEXT NOT NULL,
-          PRIMARY KEY (run_id, seq)
-        )
-      `);
-      // Tool-call result ledger: persists the outcome of write tool calls that
-      // completed AFTER their chunk was abandoned (zombie completions). A
-      // resumed continuation can recover the real result by matching
-      // thread_id + tool_key (name:stableInputHash) instead of re-executing
-      // the side effect. Entries are scoped to the thread and expire with it.
-      await client.execute(`
-        CREATE TABLE IF NOT EXISTS agent_tool_ledger (
-          thread_id TEXT NOT NULL,
-          tool_key TEXT NOT NULL,
-          result_summary TEXT NOT NULL,
-          completed_at ${intType()} NOT NULL,
-          PRIMARY KEY (thread_id, tool_key)
-        )
-      `);
+      await client.execute(agentRunEventsCreateSql);
+      await client.execute(agentToolLedgerCreateSql);
       // Widen millisecond-timestamp columns that older deployments created as
       // 32-bit `INTEGER`. `insertRun()` writes `Date.now()` into `started_at`
       // on every turn, so an int4 column makes every agent prompt fail on

package/corpus/core/src/application-state/store.ts

@@ -4,6 +4,7 @@ import {
   isPostgres,
   intType,
 } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import type { StoreWriteOptions } from "../settings/store.js";
 import { emitAppStateChange, emitAppStateDelete } from "./emitter.js";
@@ -22,7 +23,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS application_state (
           session_id TEXT NOT NULL,
           key TEXT NOT NULL,
@@ -30,7 +31,40 @@ async function ensureTable(): Promise<void> {
           updated_at ${intType()} NOT NULL,
           PRIMARY KEY (session_id, key)
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // Hot path: the `application_state` table and its poll indexes are
+        // virtually always already present in production. Issuing `CREATE
+        // TABLE`/ `CREATE INDEX` still takes a lock that, in a fresh
+        // background-worker process behind a concurrent connection on the
+        // shared Neon DB, can block ~indefinitely (ACCESS EXCLUSIVE for CREATE
+        // TABLE; a write-blocking SHARE lock for CREATE INDEX). The ensure*
+        // wrappers probe `information_schema`/`pg_indexes` first (plain reads,
+        // no lock) and run DDL ONLY for what is actually missing, bounded by a
+        // transaction-scoped `lock_timeout`. If a swallowed lock-timeout leaves
+        // the schema still missing they RE-PROBE and THROW rather than letting
+        // init memoize success against absent schema.
+        await ensureTableExists("application_state", createSql);
+        // Older deployments created `updated_at` as 32-bit `INTEGER`; on Postgres
+        // the `Date.now()` written by appStatePut() on every turn overflows int4.
+        // Widen it in place (no-op once done / on fresh BIGINT databases).
+        await widenIntColumnsToBigInt("application_state", ["updated_at"]);
+        // Indexes for the two hot poll paths. Probe pg_indexes first (no lock)
+        // and skip the SHARE-locking CREATE INDEX when already present.
+        await ensureIndexExists(
+          "app_state_updated_at_idx",
+          `CREATE INDEX IF NOT EXISTS app_state_updated_at_idx ON application_state (updated_at)`,
+        );
+        await ensureIndexExists(
+          "app_state_key_updated_idx",
+          `CREATE INDEX IF NOT EXISTS app_state_key_updated_idx ON application_state (key, updated_at)`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       // Older deployments created `updated_at` as 32-bit `INTEGER`; on Postgres
       // the `Date.now()` written by appStatePut() on every turn overflows int4.
       // Widen it in place (no-op once done / on fresh BIGINT databases).