@agent-native/core 0.77.8 → 0.77.11

package/corpus/core/src/integrations/a2a-continuations-store.ts

@@ -4,6 +4,11 @@ import {
   intType,
   retryOnDdlRace,
 } from "../db/client.js";
+import {
+  ensureTableExists,
+  ensureColumnExists,
+  ensureIndexExists,
+} from "../db/ddl-guard.js";
 import { isDuplicateColumnError } from "../db/migrations.js";
 import type { IncomingMessage } from "./types.js";
 
@@ -11,36 +16,74 @@ let _initPromise: Promise<void> | undefined;
 const PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const PROCESSING_NEXT_CHECK_STALE_AFTER_MS = 60 * 1000;
 
+// Build the CREATE SQL lazily (not at module scope) so intType() runs at
+// RUNTIME, not import time — a module-scope call breaks any consumer whose
+// db/client mock doesn't stub intType (e.g. db-admin specs).
+function buildCreateSql(): string {
+  return `
+  CREATE TABLE IF NOT EXISTS integration_a2a_continuations (
+    id TEXT PRIMARY KEY,
+    integration_task_id TEXT NOT NULL,
+    platform TEXT NOT NULL,
+    external_thread_id TEXT NOT NULL,
+    incoming_payload TEXT NOT NULL,
+    placeholder_ref TEXT,
+    owner_email TEXT NOT NULL,
+    org_id TEXT,
+    agent_name TEXT NOT NULL,
+    agent_url TEXT NOT NULL,
+    dedupe_key TEXT,
+    a2a_task_id TEXT NOT NULL,
+    a2a_auth_token TEXT,
+    status TEXT NOT NULL,
+    attempts ${intType()} NOT NULL DEFAULT 0,
+    next_check_at ${intType()} NOT NULL,
+    error_message TEXT,
+    created_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL,
+    completed_at ${intType()}
+  )
+`;
+}
+
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-        CREATE TABLE IF NOT EXISTS integration_a2a_continuations (
-          id TEXT PRIMARY KEY,
-          integration_task_id TEXT NOT NULL,
-          platform TEXT NOT NULL,
-          external_thread_id TEXT NOT NULL,
-          incoming_payload TEXT NOT NULL,
-          placeholder_ref TEXT,
-          owner_email TEXT NOT NULL,
-          org_id TEXT,
-          agent_name TEXT NOT NULL,
-          agent_url TEXT NOT NULL,
-          dedupe_key TEXT,
-          a2a_task_id TEXT NOT NULL,
-          a2a_auth_token TEXT,
-          status TEXT NOT NULL,
-          attempts ${intType()} NOT NULL DEFAULT 0,
-          next_check_at ${intType()} NOT NULL,
-          error_message TEXT,
-          created_at ${intType()} NOT NULL,
-          updated_at ${intType()} NOT NULL,
-          completed_at ${intType()}
-        )
-      `),
-      );
+      const createSql = buildCreateSql();
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_a2a_continuations", createSql);
+        await ensureIndexExists(
+          "idx_a2a_continuations_status_next",
+          `CREATE INDEX IF NOT EXISTS idx_a2a_continuations_status_next ON integration_a2a_continuations(status, next_check_at)`,
+        );
+        await ensureIndexExists(
+          "idx_a2a_continuations_integration_task",
+          `CREATE INDEX IF NOT EXISTS idx_a2a_continuations_integration_task ON integration_a2a_continuations(integration_task_id)`,
+        );
+        await ensureIndexExists(
+          "idx_a2a_continuations_remote_task",
+          `CREATE UNIQUE INDEX IF NOT EXISTS idx_a2a_continuations_remote_task ON integration_a2a_continuations(integration_task_id, agent_url, a2a_task_id)`,
+        );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "a2a_auth_token",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS a2a_auth_token TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "dedupe_key",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS dedupe_key TEXT`,
+        );
+        await ensureIndexExists(
+          "idx_a2a_continuations_dedupe_key",
+          `CREATE INDEX IF NOT EXISTS idx_a2a_continuations_dedupe_key ON integration_a2a_continuations(integration_task_id, agent_url, dedupe_key)`,
+        );
+        return;
+      }
+      // SQLite (local dev): keep existing behavior
+      await retryOnDdlRace(() => client.execute(createSql));
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE INDEX IF NOT EXISTS idx_a2a_continuations_status_next ON integration_a2a_continuations(status, next_check_at)`,

package/corpus/core/src/integrations/config-store.ts

@@ -1,9 +1,5 @@
-import {
-  getDbExec,
-  isPostgres,
-  intType,
-  retryOnDdlRace,
-} from "../db/client.js";
+import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -11,18 +7,23 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_configs (
-            platform TEXT NOT NULL,
-            config_key TEXT NOT NULL,
-            config_data TEXT NOT NULL,
-            owner TEXT,
-            updated_at ${intType()} NOT NULL,
-            PRIMARY KEY (platform, config_key)
-          )
-        `),
-      );
+      const createSql = `CREATE TABLE IF NOT EXISTS integration_configs (
+  platform TEXT NOT NULL,
+  config_key TEXT NOT NULL,
+  config_data TEXT NOT NULL,
+  owner TEXT,
+  updated_at ${intType()} NOT NULL,
+  PRIMARY KEY (platform, config_key)
+)`;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_configs", createSql);
+        return;
+      }
+
+      // SQLite (local dev): keep existing behavior
+      await client.execute(createSql);
     })().catch((err) => {
       // Don't cache the rejection — let the next caller retry a fresh init.
       _initPromise = undefined;

package/corpus/core/src/integrations/pending-tasks-store.ts

@@ -11,6 +11,11 @@
  * invocation gets its own fresh function timeout budget.
  */
 import { getDbExec, isPostgres, intType } from "../db/client.js";
+import {
+  ensureTableExists,
+  ensureColumnExists,
+  ensureIndexExists,
+} from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -18,22 +23,41 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
-        CREATE TABLE IF NOT EXISTS integration_pending_tasks (
-          id TEXT PRIMARY KEY,
-          platform TEXT NOT NULL,
-          external_thread_id TEXT NOT NULL,
-          payload TEXT NOT NULL,
-          owner_email TEXT NOT NULL,
-          org_id TEXT,
-          status TEXT NOT NULL,
-          attempts ${intType()} NOT NULL DEFAULT 0,
-          error_message TEXT,
-          created_at ${intType()} NOT NULL,
-          updated_at ${intType()} NOT NULL,
-          completed_at ${intType()}
-        )
-      `);
+      const createSql = `CREATE TABLE IF NOT EXISTS integration_pending_tasks (
+  id TEXT PRIMARY KEY,
+  platform TEXT NOT NULL,
+  external_thread_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  status TEXT NOT NULL,
+  attempts ${intType()} NOT NULL DEFAULT 0,
+  error_message TEXT,
+  created_at ${intType()} NOT NULL,
+  updated_at ${intType()} NOT NULL,
+  completed_at ${intType()}
+)`;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_pending_tasks", createSql);
+        await ensureColumnExists(
+          "integration_pending_tasks",
+          "external_event_key",
+          `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS external_event_key TEXT`,
+        );
+        await ensureIndexExists(
+          "idx_pending_tasks_status_created",
+          `CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created ON integration_pending_tasks(status, created_at)`,
+        );
+        await ensureIndexExists(
+          "idx_pending_tasks_event_key",
+          `CREATE UNIQUE INDEX IF NOT EXISTS idx_pending_tasks_event_key ON integration_pending_tasks(platform, external_event_key)`,
+        );
+        return;
+      }
+
+      await client.execute(createSql);
       await client.execute(
         `CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created ON integration_pending_tasks(status, created_at)`,
       );

package/corpus/core/src/integrations/remote-commands-store.ts

@@ -4,6 +4,7 @@ import {
   isPostgres,
   retryOnDdlRace,
 } from "../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
 import type {
   RemoteCommand,
   RemoteCommandKind,
@@ -29,29 +30,42 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_remote_commands (
-            id TEXT PRIMARY KEY,
-            device_id TEXT NOT NULL,
-            owner_email TEXT NOT NULL,
-            org_id TEXT,
-            kind TEXT NOT NULL,
-            params_json TEXT NOT NULL,
-            status TEXT NOT NULL,
-            result_json TEXT,
-            platform TEXT,
-            external_thread_id TEXT,
-            attempts ${intType()} NOT NULL DEFAULT 0,
-            next_check_at ${intType()} NOT NULL,
-            claimed_at ${intType()},
-            completed_at ${intType()},
-            error_message TEXT,
-            created_at ${intType()} NOT NULL,
-            updated_at ${intType()} NOT NULL
-          )
-        `),
-      );
+      const createSql = `CREATE TABLE IF NOT EXISTS integration_remote_commands (
+  id TEXT PRIMARY KEY,
+  device_id TEXT NOT NULL,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  kind TEXT NOT NULL,
+  params_json TEXT NOT NULL,
+  status TEXT NOT NULL,
+  result_json TEXT,
+  platform TEXT,
+  external_thread_id TEXT,
+  attempts ${intType()} NOT NULL DEFAULT 0,
+  next_check_at ${intType()} NOT NULL,
+  claimed_at ${intType()},
+  completed_at ${intType()},
+  error_message TEXT,
+  created_at ${intType()} NOT NULL,
+  updated_at ${intType()} NOT NULL
+)`;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_remote_commands", createSql);
+        await ensureIndexExists(
+          "idx_remote_commands_device_status_next",
+          `CREATE INDEX IF NOT EXISTS idx_remote_commands_device_status_next ON integration_remote_commands(device_id, status, next_check_at)`,
+        );
+        await ensureIndexExists(
+          "idx_remote_commands_owner",
+          `CREATE INDEX IF NOT EXISTS idx_remote_commands_owner ON integration_remote_commands(owner_email, org_id)`,
+        );
+        return;
+      }
+
+      // SQLite: keep existing behavior
+      await retryOnDdlRace(() => client.execute(createSql));
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE INDEX IF NOT EXISTS idx_remote_commands_device_status_next ON integration_remote_commands(device_id, status, next_check_at)`,

package/corpus/core/src/integrations/remote-devices-store.ts

@@ -4,6 +4,11 @@ import {
   isPostgres,
   retryOnDdlRace,
 } from "../db/client.js";
+import {
+  ensureColumnExists,
+  ensureIndexExists,
+  ensureTableExists,
+} from "../db/ddl-guard.js";
 import type { PublicRemoteDevice, RemoteDevice } from "./remote-types.js";
 
 let _initPromise: Promise<void> | undefined;
@@ -12,26 +17,65 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_remote_devices (
-            id TEXT PRIMARY KEY,
-            owner_email TEXT NOT NULL,
-            org_id TEXT,
-            label TEXT NOT NULL,
-            platform TEXT,
-            app_version TEXT,
-            host_name TEXT,
-            metadata_json TEXT,
-            device_token_hash TEXT NOT NULL,
-            last_seen_at ${intType()},
-            status TEXT NOT NULL,
-            revoked_at ${intType()},
-            created_at ${intType()} NOT NULL,
-            updated_at ${intType()} NOT NULL
-          )
-        `),
-      );
+      const createSql = `
+        CREATE TABLE IF NOT EXISTS integration_remote_devices (
+          id TEXT PRIMARY KEY,
+          owner_email TEXT NOT NULL,
+          org_id TEXT,
+          label TEXT NOT NULL,
+          platform TEXT,
+          app_version TEXT,
+          host_name TEXT,
+          metadata_json TEXT,
+          device_token_hash TEXT NOT NULL,
+          last_seen_at ${intType()},
+          status TEXT NOT NULL,
+          revoked_at ${intType()},
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL
+        )
+      `;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_remote_devices", createSql);
+        await ensureColumnExists(
+          "integration_remote_devices",
+          "platform",
+          `ALTER TABLE integration_remote_devices ADD COLUMN IF NOT EXISTS platform TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_remote_devices",
+          "app_version",
+          `ALTER TABLE integration_remote_devices ADD COLUMN IF NOT EXISTS app_version TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_remote_devices",
+          "host_name",
+          `ALTER TABLE integration_remote_devices ADD COLUMN IF NOT EXISTS host_name TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_remote_devices",
+          "metadata_json",
+          `ALTER TABLE integration_remote_devices ADD COLUMN IF NOT EXISTS metadata_json TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_remote_devices",
+          "revoked_at",
+          `ALTER TABLE integration_remote_devices ADD COLUMN IF NOT EXISTS revoked_at ${intType()}`,
+        );
+        await ensureIndexExists(
+          "idx_remote_devices_token_hash",
+          `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_devices_token_hash ON integration_remote_devices(device_token_hash)`,
+        );
+        await ensureIndexExists(
+          "idx_remote_devices_owner",
+          `CREATE INDEX IF NOT EXISTS idx_remote_devices_owner ON integration_remote_devices(owner_email, org_id)`,
+        );
+        return;
+      }
+      // SQLite (local dev): keep existing behavior verbatim
+      await retryOnDdlRace(() => client.execute(createSql));
       await addColumnIfMissing("platform", "TEXT");
       await addColumnIfMissing("app_version", "TEXT");
       await addColumnIfMissing("host_name", "TEXT");

package/corpus/core/src/integrations/remote-push-store.ts

@@ -1,4 +1,10 @@
-import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import {
+  getDbExec,
+  isPostgres,
+  intType,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
 import type {
   PublicRemotePushRegistration,
   RemotePushNotification,
@@ -7,29 +13,77 @@ import type {
 
 let _initPromise: Promise<void> | undefined;
 
+// Build the CREATE SQL lazily (not at module scope) so intType() runs at
+// RUNTIME, not import time — a module-scope call breaks any consumer whose
+// db/client mock doesn't stub intType (e.g. db-admin specs).
+function buildCreateRegistrationsSql(): string {
+  return `
+  CREATE TABLE IF NOT EXISTS integration_remote_push_registrations (
+    id TEXT PRIMARY KEY,
+    owner_email TEXT NOT NULL,
+    org_id TEXT,
+    provider TEXT NOT NULL,
+    platform TEXT,
+    client_device_id TEXT,
+    label TEXT,
+    token TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    status TEXT NOT NULL,
+    last_seen_at ${intType()},
+    created_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL
+  )
+`;
+}
+
+function buildCreateNotificationsSql(): string {
+  return `
+  CREATE TABLE IF NOT EXISTS integration_remote_push_notifications (
+    id TEXT PRIMARY KEY,
+    owner_email TEXT NOT NULL,
+    org_id TEXT,
+    registration_id TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    status TEXT NOT NULL,
+    attempts ${intType()} NOT NULL DEFAULT 0,
+    created_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL
+  )
+`;
+}
+
 async function ensureTables(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_remote_push_registrations (
-            id TEXT PRIMARY KEY,
-            owner_email TEXT NOT NULL,
-            org_id TEXT,
-            provider TEXT NOT NULL,
-            platform TEXT,
-            client_device_id TEXT,
-            label TEXT,
-            token TEXT NOT NULL,
-            token_hash TEXT NOT NULL,
-            status TEXT NOT NULL,
-            last_seen_at ${intType()},
-            created_at ${intType()} NOT NULL,
-            updated_at ${intType()} NOT NULL
-          )
-        `),
-      );
+      const createRegistrationsSql = buildCreateRegistrationsSql();
+      const createNotificationsSql = buildCreateNotificationsSql();
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists(
+          "integration_remote_push_registrations",
+          createRegistrationsSql,
+        );
+        await ensureIndexExists(
+          "idx_remote_push_token_hash",
+          `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_push_token_hash ON integration_remote_push_registrations(token_hash)`,
+        );
+        await ensureIndexExists(
+          "idx_remote_push_owner",
+          `CREATE INDEX IF NOT EXISTS idx_remote_push_owner ON integration_remote_push_registrations(owner_email, org_id, status)`,
+        );
+        await ensureTableExists(
+          "integration_remote_push_notifications",
+          createNotificationsSql,
+        );
+        await ensureIndexExists(
+          "idx_remote_push_notifications_owner",
+          `CREATE INDEX IF NOT EXISTS idx_remote_push_notifications_owner ON integration_remote_push_notifications(owner_email, org_id, status, created_at)`,
+        );
+        return;
+      }
+      // SQLite (local dev): keep existing behavior
+      await retryOnDdlRace(() => client.execute(createRegistrationsSql));
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_push_token_hash ON integration_remote_push_registrations(token_hash)`,
@@ -41,21 +95,7 @@ async function ensureTables(): Promise<void> {
         ),
       );
 
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_remote_push_notifications (
-            id TEXT PRIMARY KEY,
-            owner_email TEXT NOT NULL,
-            org_id TEXT,
-            registration_id TEXT NOT NULL,
-            payload_json TEXT NOT NULL,
-            status TEXT NOT NULL,
-            attempts ${intType()} NOT NULL DEFAULT 0,
-            created_at ${intType()} NOT NULL,
-            updated_at ${intType()} NOT NULL
-          )
-        `),
-      );
+      await retryOnDdlRace(() => client.execute(createNotificationsSql));
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE INDEX IF NOT EXISTS idx_remote_push_notifications_owner ON integration_remote_push_notifications(owner_email, org_id, status, created_at)`,

package/corpus/core/src/integrations/remote-run-events-store.ts

@@ -1,23 +1,49 @@
-import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import {
+  getDbExec,
+  isPostgres,
+  intType,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
 import type { RemoteRunEvent } from "./remote-types.js";
 
 let _initPromise: Promise<void> | undefined;
 
+// Build the CREATE SQL lazily (not at module scope) so intType() runs at
+// RUNTIME, not import time — a module-scope call breaks any consumer whose
+// db/client mock doesn't stub intType (e.g. db-admin specs).
+function buildCreateSql(): string {
+  return `
+  CREATE TABLE IF NOT EXISTS integration_remote_run_events (
+    device_id TEXT NOT NULL,
+    remote_run_id TEXT NOT NULL,
+    seq ${intType()} NOT NULL,
+    event_json TEXT NOT NULL,
+    created_at ${intType()} NOT NULL
+  )
+`;
+}
+
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE TABLE IF NOT EXISTS integration_remote_run_events (
-            device_id TEXT NOT NULL,
-            remote_run_id TEXT NOT NULL,
-            seq ${intType()} NOT NULL,
-            event_json TEXT NOT NULL,
-            created_at ${intType()} NOT NULL
-          )
-        `),
-      );
+      const createSql = buildCreateSql();
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_remote_run_events", createSql);
+        await ensureIndexExists(
+          "idx_remote_run_events_unique",
+          `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_run_events_unique ON integration_remote_run_events(device_id, remote_run_id, seq)`,
+        );
+        await ensureIndexExists(
+          "idx_remote_run_events_run",
+          `CREATE INDEX IF NOT EXISTS idx_remote_run_events_run ON integration_remote_run_events(device_id, remote_run_id, seq)`,
+        );
+        return;
+      }
+      // SQLite (local dev): keep existing behavior
+      await retryOnDdlRace(() => client.execute(createSql));
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_run_events_unique ON integration_remote_run_events(device_id, remote_run_id, seq)`,

package/corpus/core/src/integrations/thread-mapping-store.ts

@@ -1,4 +1,5 @@
 import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -6,7 +7,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS integration_thread_mappings (
           platform TEXT NOT NULL,
           external_thread_id TEXT NOT NULL,
@@ -16,7 +17,15 @@ async function ensureTable(): Promise<void> {
           updated_at ${intType()} NOT NULL,
           PRIMARY KEY (platform, external_thread_id)
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_thread_mappings", createSql);
+        return;
+      }
+      // SQLite (local dev): keep existing behavior
+      await client.execute(createSql);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;