@agent-native/core 0.119.5 → 0.119.6

package/src/integrations/pending-tasks-retry-job.ts

@@ -1,8 +1,13 @@
 import { getDbExec } from "../db/client.js";
-import { withConfiguredAppBasePath } from "../server/app-base-path.js";
-import { FRAMEWORK_ROUTE_PREFIX } from "../server/core-routes-plugin.js";
-import { signInternalToken } from "./internal-token.js";
-import { MAX_PENDING_TASK_ATTEMPTS } from "./pending-tasks-store.js";
+import {
+  configuredIntegrationDurableDispatchScopes,
+  dispatchPendingIntegrationTask,
+  isIntegrationDurableDispatchEnabledForTask,
+} from "./integration-durable-dispatch.js";
+import {
+  ensurePendingTasksTable,
+  MAX_PENDING_TASK_ATTEMPTS,
+} from "./pending-tasks-store.js";
 
 /**
  * Retries stuck integration webhook tasks.
@@ -10,12 +15,16 @@ import { MAX_PENDING_TASK_ATTEMPTS } from "./pending-tasks-store.js";
  * The integration webhook flow enqueues work into `integration_pending_tasks`
  * (see `pending-tasks-store.ts`) and then fires a self-webhook to the
  * `/_agent-native/integrations/process-task` endpoint to drain the queue.
- * If that fire-and-forget dispatch fails (e.g. transient network blip), the
+ * If that initial dispatch is lost (e.g. transient network blip), the
  * row stays in `pending` forever. Likewise, if the processor is killed mid-
  * processing (function timeout, container shutdown), a row can remain in
  * `processing` forever.
  *
- * This job runs every 60s and re-fires the processor endpoint for tasks that
+ * The in-process fallback runs every 60s. Durable deployments also invoke the
+ * same bounded sweep from an external scheduler so recovery does not depend on
+ * a serverless process remaining alive.
+ *
+ * Each sweep re-fires the processor endpoint for tasks that
  * look stuck:
  *   - status='pending' AND created_at older than 90s (initial dispatch lost)
  *   - status='processing' AND updated_at older than the host-specific
@@ -35,8 +44,9 @@ const PENDING_STUCK_AFTER_MS = 90_000;
 /** Tasks "processing" longer than this are considered killed mid-flight. */
 const DEFAULT_PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const SERVERLESS_PROCESSING_STUCK_AFTER_MS = 75_000;
+const DURABLE_BACKGROUND_PROCESSING_STUCK_AFTER_MS = 16 * 60 * 1000;
 /** After this many attempts we give up and mark the task failed */
-const PROCESSOR_PATH = `${FRAMEWORK_ROUTE_PREFIX}/integrations/process-task`;
+const DEFAULT_SWEEP_LIMIT = 100;
 
 let retryInterval: ReturnType<typeof setInterval> | null = null;
 let initialTimer: ReturnType<typeof setTimeout> | null = null;
@@ -49,8 +59,74 @@ let tableExists: boolean | null = null;
 
 interface StuckTaskRow {
   id: string;
+  platform: string;
+  externalThreadId: string;
   status: string;
   attempts: number;
+  updatedAt: number;
+  dispatchScope: string | null;
+}
+
+export interface PendingTasksSweepResult {
+  selected: number;
+  dispatched: number;
+  markedFailed: number;
+  skipped: number;
+  dispatchFailed: number;
+}
+
+export interface PendingTasksSweepOptions {
+  webhookBaseUrl?: string;
+  limit?: number;
+  durableOnly?: boolean;
+}
+
+function affectedRows(result: unknown): number {
+  return Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+}
+
+function isMissingPendingTasksTableError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /no such table|relation .* does not exist|undefined_table/i.test(
+    message,
+  );
+}
+
+function durableScopeSql(): { clause: string; args: string[] } {
+  const scopes = configuredIntegrationDurableDispatchScopes();
+  if (scopes === null) return { clause: "", args: [] };
+  if (scopes.length === 0) return { clause: " AND 1 = 0", args: [] };
+
+  const clauses: string[] = [];
+  const args: string[] = [];
+  for (const scope of scopes) {
+    if (scope.value === "*") {
+      clauses.push("platform = ?");
+      args.push(scope.platform);
+      continue;
+    }
+    if (scope.platform === "slack" && /^[A-Za-z0-9]+$/.test(scope.value)) {
+      clauses.push(
+        "(platform = ? AND (external_thread_id = ? OR dispatch_scope = ? OR external_thread_id LIKE ?))",
+      );
+      args.push(
+        scope.platform,
+        scope.value,
+        scope.value,
+        `%:%:${scope.value}:%`,
+      );
+      continue;
+    }
+    clauses.push(
+      "(platform = ? AND (external_thread_id = ? OR dispatch_scope = ?))",
+    );
+    args.push(scope.platform, scope.value, scope.value);
+  }
+  return { clause: ` AND (${clauses.join(" OR ")})`, args };
 }
 
 /**
@@ -58,39 +134,76 @@ interface StuckTaskRow {
  * Exported for tests and for manual triggers.
  */
 export async function retryStuckPendingTasks(
-  webhookBaseUrl?: string,
-): Promise<void> {
-  const baseUrl = webhookBaseUrl ?? activeWebhookBaseUrl;
+  input?: string | PendingTasksSweepOptions,
+): Promise<PendingTasksSweepResult> {
+  const options: PendingTasksSweepOptions =
+    typeof input === "string" ? { webhookBaseUrl: input } : (input ?? {});
+  const baseUrl = options.webhookBaseUrl ?? activeWebhookBaseUrl;
+  const limit = Math.max(
+    1,
+    Math.min(500, Math.floor(options.limit ?? DEFAULT_SWEEP_LIMIT)),
+  );
+  const scopeSql = options.durableOnly
+    ? durableScopeSql()
+    : { clause: "", args: [] as string[] };
+  const result: PendingTasksSweepResult = {
+    selected: 0,
+    dispatched: 0,
+    markedFailed: 0,
+    skipped: 0,
+    dispatchFailed: 0,
+  };
+  await ensurePendingTasksTable();
   const client = getDbExec();
   const now = Date.now();
   const pendingCutoff = now - PENDING_STUCK_AFTER_MS;
   const processingCutoff = now - getProcessingStuckAfterMs();
+  const durableProcessingCutoff =
+    now - DURABLE_BACKGROUND_PROCESSING_STUCK_AFTER_MS;
 
   let stuckRows: StuckTaskRow[];
   try {
     const { rows } = await client.execute({
       sql: `
-        SELECT id, status, attempts
+        SELECT id, platform, external_thread_id, dispatch_scope, status, attempts, updated_at
           FROM integration_pending_tasks
-         WHERE (status = 'pending' AND created_at <= ? AND updated_at <= ?)
-            OR (status = 'processing' AND updated_at <= ?)
+         WHERE ((status = 'pending' AND created_at <= ? AND updated_at <= ?)
+            OR (status = 'processing' AND (
+              (last_dispatch_outcome = 'background-acknowledged'
+                AND updated_at <= ?)
+              OR ((last_dispatch_outcome IS NULL
+                    OR last_dispatch_outcome <> 'background-acknowledged')
+                AND updated_at <= ?)
+            )))
+         ${scopeSql.clause}
+         ORDER BY updated_at ASC
+         LIMIT ?
       `,
       // `updated_at` is initialized to `created_at` on insert, so a genuinely
       // stuck pending row still matches on the first sweep. The retry path
       // below touches `updated_at`, which (with this predicate) keeps the row
       // from being re-selected — and re-firing the processor — on every tick.
-      args: [pendingCutoff, pendingCutoff, processingCutoff],
+      args: [
+        pendingCutoff,
+        pendingCutoff,
+        durableProcessingCutoff,
+        processingCutoff,
+        ...scopeSql.args,
+        limit,
+      ],
     });
     stuckRows = rows.map((r) => ({
       id: r.id as string,
+      platform: r.platform as string,
+      externalThreadId: r.external_thread_id as string,
       status: r.status as string,
       attempts: Number(r.attempts ?? 0),
+      updatedAt: Number(r.updated_at ?? 0),
+      dispatchScope: (r.dispatch_scope as string | null) ?? null,
     }));
     tableExists = true;
   } catch (err) {
-    // Most common case: the table hasn't been created yet because no inbound
-    // integration webhook has been processed on this deployment. Silently
-    // no-op until the table appears.
+    if (!isMissingPendingTasksTableError(err)) throw err;
     if (tableExists !== false) {
       tableExists = false;
       if (process.env.DEBUG) {
@@ -99,17 +212,29 @@ export async function retryStuckPendingTasks(
         );
       }
     }
-    return;
+    return result;
   }
 
-  if (stuckRows.length === 0) return;
+  stuckRows = stuckRows.filter((row) => {
+    const durable = isIntegrationDurableDispatchEnabledForTask({
+      platform: row.platform,
+      externalThreadId: row.externalThreadId,
+      platformContext: row.dispatchScope
+        ? { channelId: row.dispatchScope }
+        : undefined,
+    });
+    if (options.durableOnly && !durable) return false;
+    return true;
+  });
+  result.selected = stuckRows.length;
+  if (stuckRows.length === 0) return result;
 
   for (const row of stuckRows) {
     try {
       // Cap retries — mark failed and move on so the row stops bouncing
       // between pending and processing forever.
       if (row.attempts >= MAX_PENDING_TASK_ATTEMPTS) {
-        await client.execute({
+        const update = await client.execute({
           sql: `
             UPDATE integration_pending_tasks
                SET status = 'failed',
@@ -119,14 +244,21 @@ export async function retryStuckPendingTasks(
                    external_event_key = NULL
              WHERE id = ?
                AND status = ?
+               AND updated_at = ?
           `,
           args: [
             Date.now(),
             `Retry job: exceeded ${MAX_PENDING_TASK_ATTEMPTS} attempts`,
             row.id,
             row.status,
+            row.updatedAt,
           ],
         });
+        if (affectedRows(update) === 0) {
+          result.skipped += 1;
+          continue;
+        }
+        result.markedFailed += 1;
         console.warn(
           `[integrations] Pending task ${row.id} exceeded ${MAX_PENDING_TASK_ATTEMPTS} attempts — marking failed`,
         );
@@ -138,24 +270,44 @@ export async function retryStuckPendingTasks(
       // Without this, processing rows stay stuck forever.
       // For pending rows, just touch updated_at to avoid re-firing every tick.
       const newStatus = row.status === "processing" ? "pending" : row.status;
-      await client.execute({
+      const update = await client.execute({
         sql: `
           UPDATE integration_pending_tasks
              SET status = ?, updated_at = ?
            WHERE id = ?
              AND status = ?
+             AND updated_at = ?
         `,
-        args: [newStatus, Date.now(), row.id, row.status],
+        args: [newStatus, Date.now(), row.id, row.status, row.updatedAt],
       });
+      if (affectedRows(update) === 0) {
+        result.skipped += 1;
+        continue;
+      }
 
-      await refireProcessor(row.id, baseUrl);
+      const outcome = await dispatchPendingIntegrationTask({
+        taskId: row.id,
+        task: {
+          platform: row.platform,
+          externalThreadId: row.externalThreadId,
+          platformContext: row.dispatchScope
+            ? { channelId: row.dispatchScope }
+            : undefined,
+        },
+        baseUrl,
+        portableSettleMs: 1_000,
+      });
+      if (outcome === "failed") result.dispatchFailed += 1;
+      else result.dispatched += 1;
     } catch (err) {
+      result.dispatchFailed += 1;
       console.error(
         `[integrations] Failed to retry pending task ${row.id}:`,
         err,
       );
     }
   }
+  return result;
 }
 
 function getProcessingStuckAfterMs(): number {
@@ -170,70 +322,6 @@ function getProcessingStuckAfterMs(): number {
   return DEFAULT_PROCESSING_STUCK_AFTER_MS;
 }
 
-/**
- * Fire-and-forget POST to the processor endpoint for a single task id.
- * Mirrors the original dispatch from the webhook handler, including the
- * short-lived HMAC bearer token bound to this taskId.
- */
-async function refireProcessor(
-  taskId: string,
-  webhookBaseUrl: string | undefined,
-): Promise<void> {
-  const baseUrl =
-    webhookBaseUrl ||
-    process.env.WEBHOOK_BASE_URL ||
-    process.env.APP_URL ||
-    process.env.URL ||
-    process.env.DEPLOY_URL ||
-    `http://localhost:${process.env.PORT || 3000}`;
-
-  const url = `${withConfiguredAppBasePath(baseUrl)}${PROCESSOR_PATH}`;
-
-  // Sign with HMAC if A2A_SECRET is configured. In production we MUST sign —
-  // an unsigned dispatch in production lets attackers re-trigger any queued
-  // task with a guessable id (C3 in the webhook security audit). In dev we
-  // fall back to unsigned so contributors can iterate without configuring
-  // A2A_SECRET locally.
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-  };
-  try {
-    headers["Authorization"] = `Bearer ${signInternalToken(taskId)}`;
-  } catch (err) {
-    if (process.env.NODE_ENV === "production") {
-      console.error(
-        `[integrations] Refusing to dispatch task ${taskId} — A2A_SECRET not configured. ` +
-          "Set A2A_SECRET to enable signed retry dispatches.",
-      );
-      return;
-    }
-    // Dev: proceed unsigned. Log the underlying error path so a malformed
-    // secret (different from "not set") doesn't fail silently (L5 in the audit).
-    if (err instanceof Error && !/A2A_SECRET/i.test(err.message)) {
-      console.error(
-        `[integrations] signInternalToken failed unexpectedly for ${taskId}:`,
-        err,
-      );
-    }
-  }
-
-  // Don't await the body — we just want the request to leave the box.
-  // A short timeout avoids tying up the retry loop on a hung processor.
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5_000);
-
-  try {
-    await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ taskId }),
-      signal: controller.signal,
-    });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 /**
  * Start the periodic retry loop. Safe to call multiple times — second call
  * is a no-op.

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

@@ -33,6 +33,10 @@ async function ensureTable(): Promise<void> {
   org_id TEXT,
   status TEXT NOT NULL,
   attempts ${intType()} NOT NULL DEFAULT 0,
+  dispatch_attempts ${intType()} NOT NULL DEFAULT 0,
+  last_dispatch_at ${intType()},
+  last_dispatch_outcome TEXT,
+  dispatch_scope TEXT,
   error_message TEXT,
   created_at ${intType()} NOT NULL,
   updated_at ${intType()} NOT NULL,
@@ -47,6 +51,26 @@ async function ensureTable(): Promise<void> {
           "external_event_key",
           `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS external_event_key TEXT`,
         );
+        await ensureColumnExists(
+          "integration_pending_tasks",
+          "dispatch_attempts",
+          `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS dispatch_attempts ${intType()} NOT NULL DEFAULT 0`,
+        );
+        await ensureColumnExists(
+          "integration_pending_tasks",
+          "last_dispatch_at",
+          `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS last_dispatch_at ${intType()}`,
+        );
+        await ensureColumnExists(
+          "integration_pending_tasks",
+          "last_dispatch_outcome",
+          `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS last_dispatch_outcome TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_pending_tasks",
+          "dispatch_scope",
+          `ALTER TABLE integration_pending_tasks ADD COLUMN IF NOT EXISTS dispatch_scope 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)`,
@@ -55,6 +79,10 @@ async function ensureTable(): Promise<void> {
           "idx_pending_tasks_event_key",
           `CREATE UNIQUE INDEX IF NOT EXISTS idx_pending_tasks_event_key ON integration_pending_tasks(platform, external_event_key)`,
         );
+        await ensureIndexExists(
+          "idx_pending_tasks_dispatch_scope",
+          `CREATE INDEX IF NOT EXISTS idx_pending_tasks_dispatch_scope ON integration_pending_tasks(platform, dispatch_scope)`,
+        );
         return;
       }
 
@@ -69,6 +97,10 @@ async function ensureTable(): Promise<void> {
       // unique index ensures a duplicate INSERT raises an error we can
       // catch as "already-enqueued".
       await ensureExternalEventKey(client);
+      await ensureDispatchColumns(client);
+      await client.execute(
+        `CREATE INDEX IF NOT EXISTS idx_pending_tasks_dispatch_scope ON integration_pending_tasks(platform, dispatch_scope)`,
+      );
       await client.execute(
         `CREATE UNIQUE INDEX IF NOT EXISTS idx_pending_tasks_event_key ON integration_pending_tasks(platform, external_event_key)`,
       );
@@ -81,6 +113,10 @@ async function ensureTable(): Promise<void> {
   return _initPromise;
 }
 
+export async function ensurePendingTasksTable(): Promise<void> {
+  await ensureTable();
+}
+
 async function ensureExternalEventKey(
   client: ReturnType<typeof getDbExec>,
 ): Promise<void> {
@@ -107,6 +143,32 @@ async function ensureExternalEventKey(
   }
 }
 
+async function ensureDispatchColumns(
+  client: ReturnType<typeof getDbExec>,
+): Promise<void> {
+  const columns = [
+    `dispatch_attempts ${intType()} NOT NULL DEFAULT 0`,
+    `last_dispatch_at ${intType()}`,
+    "last_dispatch_outcome TEXT",
+    "dispatch_scope TEXT",
+  ];
+  for (const column of columns) {
+    try {
+      await client.execute(
+        `ALTER TABLE integration_pending_tasks ADD COLUMN ${column}`,
+      );
+    } catch (err: any) {
+      if (
+        !String(err?.message ?? err)
+          .toLowerCase()
+          .includes("duplicate")
+      ) {
+        throw err;
+      }
+    }
+  }
+}
+
 /** Status values for an integration pending task. */
 export type PendingTaskStatus =
   | "pending"
@@ -123,6 +185,10 @@ export interface PendingTask {
   orgId: string | null;
   status: PendingTaskStatus;
   attempts: number;
+  dispatchAttempts: number;
+  lastDispatchAt: number | null;
+  lastDispatchOutcome: string | null;
+  dispatchScope: string | null;
   errorMessage: string | null;
   createdAt: number;
   updatedAt: number;
@@ -164,6 +230,13 @@ function rowToTask(row: Record<string, unknown>): PendingTask {
     orgId: (row.org_id as string | null) ?? null,
     status: row.status as PendingTaskStatus,
     attempts: Number(row.attempts ?? 0),
+    dispatchAttempts: Number(row.dispatch_attempts ?? 0),
+    lastDispatchAt:
+      row.last_dispatch_at == null
+        ? null
+        : Number(row.last_dispatch_at as number),
+    lastDispatchOutcome: (row.last_dispatch_outcome as string | null) ?? null,
+    dispatchScope: (row.dispatch_scope as string | null) ?? null,
     errorMessage: (row.error_message as string | null) ?? null,
     createdAt: Number(row.created_at ?? 0),
     updatedAt: Number(row.updated_at ?? 0),
@@ -189,14 +262,15 @@ export async function insertPendingTask(input: {
   ownerEmail: string;
   orgId?: string | null;
   externalEventKey?: string | null;
+  dispatchScope?: string | null;
 }): Promise<void> {
   await ensureTable();
   const client = getDbExec();
   const now = Date.now();
   await client.execute({
     sql: `INSERT INTO integration_pending_tasks
-      (id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, created_at, updated_at, external_event_key)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      (id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, created_at, updated_at, external_event_key, dispatch_scope)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     args: [
       input.id,
       input.platform,
@@ -209,6 +283,7 @@ export async function insertPendingTask(input: {
       now,
       now,
       input.externalEventKey ?? null,
+      input.dispatchScope ?? null,
     ],
   });
 }
@@ -238,7 +313,7 @@ export async function getPendingTask(id: string): Promise<PendingTask | null> {
   await ensureTable();
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, error_message, created_at, updated_at, completed_at
+    sql: `SELECT id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, dispatch_attempts, last_dispatch_at, last_dispatch_outcome, dispatch_scope, error_message, created_at, updated_at, completed_at
           FROM integration_pending_tasks WHERE id = ? LIMIT 1`,
     args: [id],
   });
@@ -342,6 +417,7 @@ export async function resolveIntegrationSourceContext(
  */
 export async function claimPendingTask(
   id: string,
+  options?: { dispatchOutcome?: string },
 ): Promise<PendingTask | null> {
   await ensureTable();
   const client = getDbExec();
@@ -352,7 +428,8 @@ export async function claimPendingTask(
   const result = await client.execute({
     sql: isPostgres()
       ? `UPDATE integration_pending_tasks
-         SET status = ?, attempts = attempts + 1, updated_at = ?
+         SET status = ?, attempts = attempts + 1, updated_at = ?,
+             last_dispatch_outcome = COALESCE(?, last_dispatch_outcome)
          WHERE id = ? AND status = 'pending'
            AND NOT EXISTS (
              SELECT 1 FROM integration_pending_tasks active
@@ -374,9 +451,10 @@ export async function claimPendingTask(
                  )
                )
            )
-         RETURNING id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, error_message, created_at, updated_at, completed_at`
+         RETURNING id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, dispatch_attempts, last_dispatch_at, last_dispatch_outcome, dispatch_scope, error_message, created_at, updated_at, completed_at`
       : `UPDATE integration_pending_tasks
-         SET status = ?, attempts = attempts + 1, updated_at = ?
+         SET status = ?, attempts = attempts + 1, updated_at = ?,
+             last_dispatch_outcome = COALESCE(?, last_dispatch_outcome)
          WHERE id = ? AND status = 'pending'
            AND NOT EXISTS (
              SELECT 1 FROM integration_pending_tasks active
@@ -398,7 +476,7 @@ export async function claimPendingTask(
                  )
                )
            )`,
-    args: ["processing", now, id],
+    args: ["processing", now, options?.dispatchOutcome ?? null, id],
   });
   const rows = result.rows ?? [];
 
@@ -418,19 +496,44 @@ export async function claimPendingTask(
   return fetched;
 }
 
+export async function recordPendingTaskDispatchAttempt(
+  id: string,
+  outcome: string,
+): Promise<void> {
+  await ensureTable();
+  await getDbExec().execute({
+    sql: `UPDATE integration_pending_tasks
+          SET dispatch_attempts = dispatch_attempts + 1,
+              last_dispatch_at = ?,
+              last_dispatch_outcome = CASE
+                WHEN status = 'processing'
+                  AND last_dispatch_outcome = 'background-acknowledged'
+                THEN last_dispatch_outcome
+                ELSE ?
+              END
+          WHERE id = ?`,
+    args: [Date.now(), outcome.slice(0, 80), id],
+  });
+}
+
 /** Next queued turn for a provider thread after its current task completes. */
-export async function getNextPendingTaskIdForThread(
+export async function getNextPendingTaskForThread(
   platform: string,
   externalThreadId: string,
-): Promise<string | null> {
+): Promise<{ id: string; dispatchScope: string | null } | null> {
   await ensureTable();
   const { rows } = await getDbExec().execute({
-    sql: `SELECT id FROM integration_pending_tasks
+    sql: `SELECT id, dispatch_scope FROM integration_pending_tasks
       WHERE platform = ? AND external_thread_id = ? AND status = 'pending'
       ORDER BY created_at ASC, id ASC LIMIT 1`,
     args: [platform, externalThreadId],
   });
-  return rows[0]?.id ? String(rows[0].id) : null;
+  return rows[0]?.id
+    ? {
+        id: String(rows[0].id),
+        dispatchScope: (rows[0].dispatch_scope as string | null) ?? null,
+      }
+    : null;
 }
 
 /** Mark a task as completed. */