@shipfox/api-integration-sentry 5.0.0 → 7.1.0

package/src/db/installations.ts

@@ -1,16 +1,20 @@
-import {and, eq, isNull, lt, sql} from 'drizzle-orm';
+import {and, eq, inArray, isNull, lt, ne, sql} from 'drizzle-orm';
 import {SentryInstallationAlreadyLinkedError} from '#core/errors.js';
 import {db} from './db.js';
 import {sentryInstallations, toSentryInstallation} from './schema/installations.js';
 
 export type SentryInstallationStatus = 'installed' | 'deleted';
+export type SentryInstallationRowStatus =
+  | 'pending'
+  | 'exchange-succeeded'
+  | SentryInstallationStatus;
 
 export interface SentryInstallation {
   id: string;
   connectionId: string | null;
   installationUuid: string;
   orgSlug: string;
-  status: string;
+  status: SentryInstallationRowStatus;
   codeHash: string | null;
   installerUserId: string | null;
   createdAt: Date;
@@ -32,6 +36,12 @@ export interface PersistVerifiedUnclaimedInstallationParams {
   codeHash: string;
 }
 
+export interface ClaimSentryInstallationVerificationParams {
+  installationUuid: string;
+  orgSlug: string;
+  codeHash: string;
+}
+
 type SentryDb = ReturnType<typeof db>;
 type SentryTx = Parameters<Parameters<SentryDb['transaction']>[0]>[0];
 
@@ -53,15 +63,10 @@ export async function upsertSentryInstallation(
     })
     .onConflictDoUpdate({
       target: sentryInstallations.installationUuid,
-      // TOCTOU guard: allow the update only when this installation is unclaimed
-      // (connection_id IS NULL, the first claim of a verified-unclaimed row) or
-      // already owned by this same connection (idempotent reconnect). A concurrent
-      // claim of the same installation to a different workspace commits its own
-      // connection_id first; this losing transaction then sees a different non-null
-      // connection_id, the predicate is false, Postgres updates nothing, and the
-      // empty RETURNING below rolls it back instead of silently repointing the
-      // installation (cross-tenant event misroute).
-      setWhere: sql`${sentryInstallations.connectionId} is null or ${sentryInstallations.connectionId} = ${params.connectionId}`,
+      // A deleted UUID is terminal. Otherwise, allow the first claim of an
+      // unclaimed row or an idempotent reconnect by its current connection. This
+      // blocks both a concurrent cross-workspace claim and a claim racing deletion.
+      setWhere: sql`${sentryInstallations.status} <> 'deleted' and (${sentryInstallations.connectionId} is null or ${sentryInstallations.connectionId} = ${params.connectionId})`,
       set: {
         connectionId: params.connectionId,
         orgSlug: params.orgSlug,
@@ -80,9 +85,8 @@ export async function upsertSentryInstallation(
 /**
  * Inserts the verified-but-unclaimed install half (`connection_id = NULL`,
  * `status = 'installed'`) after a successful code exchange. Idempotent on the
- * installation uuid: a conflicting row refreshes only `code_hash`/`org_slug`/
- * `updated_at`, so a webhook that lands after a claim never clobbers the
- * `connection_id` it set nor downgrades a `deleted` tombstone back to installed.
+ * installation uuid: a pending row becomes installed, a claimed row keeps its
+ * `connection_id`, and a deleted tombstone never becomes installed again.
  */
 export async function persistVerifiedUnclaimedInstallation(
   params: PersistVerifiedUnclaimedInstallationParams,
@@ -101,23 +105,97 @@ export async function persistVerifiedUnclaimedInstallation(
     })
     .onConflictDoUpdate({
       target: sentryInstallations.installationUuid,
+      setWhere: ne(sentryInstallations.status, 'deleted'),
       set: {
         orgSlug: params.orgSlug,
+        status: 'installed',
         codeHash: params.codeHash,
         updatedAt: now,
       },
     })
     .returning();
 
-  if (!row) throw new Error('Sentry installation persist returned no rows');
+  if (!row) {
+    const existing = await getSentryInstallationByInstallationUuid(params.installationUuid, {
+      tx: executor,
+    });
+    if (existing) return existing;
+    throw new Error('Sentry installation persist returned no rows');
+  }
+  return toSentryInstallation(row);
+}
+
+export async function claimSentryInstallationVerification(
+  params: ClaimSentryInstallationVerificationParams,
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const [inserted] = await executor
+    .insert(sentryInstallations)
+    .values({
+      connectionId: null,
+      installationUuid: params.installationUuid,
+      orgSlug: params.orgSlug,
+      status: 'pending',
+      codeHash: params.codeHash,
+    })
+    .onConflictDoNothing({target: sentryInstallations.installationUuid})
+    .returning();
+
+  if (inserted) return toSentryInstallation(inserted);
+
+  const existing = await getSentryInstallationByInstallationUuid(params.installationUuid, {
+    tx: executor,
+  });
+  if (!existing) throw new Error('Sentry installation verification claim returned no rows');
+  return existing;
+}
+
+export async function completeSentryInstallationVerification(
+  params: {installationUuid: string; codeHash: string},
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const [row] = await executor
+    .update(sentryInstallations)
+    .set({status: 'installed', updatedAt: new Date()})
+    .where(
+      and(
+        eq(sentryInstallations.installationUuid, params.installationUuid),
+        eq(sentryInstallations.status, 'exchange-succeeded'),
+        eq(sentryInstallations.codeHash, params.codeHash),
+      ),
+    )
+    .returning();
+  if (!row) return undefined;
+  return toSentryInstallation(row);
+}
+
+export async function markSentryInstallationExchangeSucceeded(
+  params: {installationUuid: string; codeHash: string},
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const [row] = await executor
+    .update(sentryInstallations)
+    .set({status: 'exchange-succeeded', updatedAt: new Date()})
+    .where(
+      and(
+        eq(sentryInstallations.installationUuid, params.installationUuid),
+        eq(sentryInstallations.status, 'pending'),
+        eq(sentryInstallations.codeHash, params.codeHash),
+      ),
+    )
+    .returning();
+  if (!row) return undefined;
   return toSentryInstallation(row);
 }
 
 /**
- * Verified installs no user has claimed yet (`connection_id IS NULL`,
- * `status='installed'`). Tombstoned rows are excluded so the TTL cron stays
- * idempotent and the unclaimed metric stays accurate. Pass `olderThan` to scope
- * to stale rows for the cron.
+ * Install claims no user has bound to a connection yet. This includes pending
+ * and exchanged claims so abandoned verification work remains observable.
+ * Tombstoned rows are excluded. Pass `olderThan` to scope by the most recent
+ * state transition for retention work.
  */
 export async function listUnclaimedSentryInstallations(
   params: {olderThan?: Date} = {},
@@ -126,10 +204,10 @@ export async function listUnclaimedSentryInstallations(
   const executor = (options.tx ?? db()) as SentryDb | SentryTx;
   const conditions = [
     isNull(sentryInstallations.connectionId),
-    eq(sentryInstallations.status, 'installed'),
+    inArray(sentryInstallations.status, ['pending', 'exchange-succeeded', 'installed']),
   ];
   if (params.olderThan) {
-    conditions.push(lt(sentryInstallations.createdAt, params.olderThan));
+    conditions.push(lt(sentryInstallations.updatedAt, params.olderThan));
   }
   const rows = await executor
     .select()
@@ -169,39 +247,62 @@ export async function getSentryInstallationByConnectionId(
 }
 
 /**
- * Tombstones verified-unclaimed installs older than `olderThan` (the TTL cleanup
- * cron). Bounds a never-claimed install rather than leaving it pending forever.
- * Returns how many rows were tombstoned. We hold no Sentry token for these rows
- * (tokens are never persisted), so the Sentry-side uninstall is out of scope here.
+ * Releases abandoned pending claims and tombstones verified-unclaimed installs
+ * older than `olderThan`. Pending claims have not durably completed an exchange,
+ * so deleting them allows a later signed creation to try again. Exchanged and
+ * installed rows stay terminal after expiry. We hold no Sentry token for these
+ * rows, so the Sentry-side uninstall is out of scope here.
  */
 export async function pruneUnclaimedSentryInstallations(
   params: {olderThan: Date},
   options: {tx?: unknown} = {},
-): Promise<{tombstoned: number}> {
+): Promise<{releasedPending: number; tombstoned: number}> {
   const executor = (options.tx ?? db()) as SentryDb | SentryTx;
-  const result = await executor
+  const releasedPending = await executor
+    .delete(sentryInstallations)
+    .where(
+      and(
+        isNull(sentryInstallations.connectionId),
+        eq(sentryInstallations.status, 'pending'),
+        lt(sentryInstallations.updatedAt, params.olderThan),
+      ),
+    );
+  const tombstoned = await executor
     .update(sentryInstallations)
     .set({status: 'deleted', updatedAt: new Date()})
     .where(
       and(
         isNull(sentryInstallations.connectionId),
-        eq(sentryInstallations.status, 'installed'),
-        lt(sentryInstallations.createdAt, params.olderThan),
+        inArray(sentryInstallations.status, ['exchange-succeeded', 'installed']),
+        lt(sentryInstallations.updatedAt, params.olderThan),
       ),
     );
-  return {tombstoned: result.rowCount ?? 0};
+  return {
+    releasedPending: releasedPending.rowCount ?? 0,
+    tombstoned: tombstoned.rowCount ?? 0,
+  };
 }
 
 export async function markSentryInstallationDeleted(
   params: {installationUuid: string},
   options: {tx?: unknown} = {},
-): Promise<SentryInstallation | undefined> {
+): Promise<SentryInstallation> {
   const executor = (options.tx ?? db()) as SentryDb | SentryTx;
   const [row] = await executor
-    .update(sentryInstallations)
-    .set({status: 'deleted', updatedAt: new Date()})
-    .where(eq(sentryInstallations.installationUuid, params.installationUuid))
+    .insert(sentryInstallations)
+    .values({
+      connectionId: null,
+      installationUuid: params.installationUuid,
+      // A reordered delete can arrive without organization data. Deleted rows never expose an organization URL.
+      orgSlug: '',
+      status: 'deleted',
+      codeHash: null,
+    })
+    .onConflictDoUpdate({
+      target: sentryInstallations.installationUuid,
+      set: {status: 'deleted', updatedAt: new Date()},
+    })
     .returning();
-  if (!row) return undefined;
+  if (!row) throw new Error('Sentry installation deletion returned no rows');
   return toSentryInstallation(row);
 }

package/src/db/schema/installations.ts

@@ -1,6 +1,6 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
 import {text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
-import type {SentryInstallation} from '#db/installations.js';
+import type {SentryInstallation, SentryInstallationRowStatus} from '#db/installations.js';
 import {pgTable} from './common.js';
 
 export const sentryInstallations = pgTable(
@@ -8,15 +8,15 @@ export const sentryInstallations = pgTable(
   {
     id: uuidv7PrimaryKey(),
     // Null until a logged-in user claims the verified install into a workspace.
-    // An unclaimed install (`connection_id IS NULL`, `status='installed'`) is
-    // persisted by the authoritative webhook before any browser claim arrives.
+    // Pending and verified installs remain unclaimed until the browser binds a
+    // connection. Deleted rows are terminal tombstones.
     connectionId: uuid('connection_id'),
     installationUuid: text('installation_uuid').notNull(),
     orgSlug: text('org_slug').notNull(),
-    status: text('status').notNull(),
-    // sha256(authorization code) of the exchange that verified this install.
-    // The claim presents the code and we match the hash, so a bare uuid alone
-    // cannot bind the install (IDOR guard) without storing a live credential.
+    status: text('status').notNull().$type<SentryInstallationRowStatus>(),
+    // sha256(authorization code) claimed for this install. The hash identifies
+    // which pending exchange reached the durable success checkpoint and keeps a
+    // bare uuid from binding an install (IDOR guard) without storing a credential.
     codeHash: text('code_hash'),
     installerUserId: uuid('installer_user_id'),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),

package/src/index.test.ts

@@ -1,3 +1,4 @@
+import {createOutboxRegistry} from '@shipfox/node-module';
 import {createSentryMaintenanceWorker} from './index.js';
 
 describe('createSentryMaintenanceWorker', () => {
@@ -6,7 +7,9 @@ describe('createSentryMaintenanceWorker', () => {
 
     expect(worker.taskQueue).toBe('integrations-sentry-maintenance');
     expect(worker.workflowsPath.endsWith('dist/temporal/workflows/index.js')).toBe(true);
-    expect(Object.keys(worker.activities())).toContain('pruneUnclaimedSentryInstallationsActivity');
+    expect(Object.keys(worker.activities({outboxRegistry: createOutboxRegistry()}))).toContain(
+      'pruneUnclaimedSentryInstallationsActivity',
+    );
     expect(worker.workflows).toEqual([
       {
         name: 'pruneUnclaimedSentryInstallationsCron',

package/src/index.ts

@@ -9,6 +9,7 @@ import type {
 import type {ModuleWorker} from '@shipfox/node-module';
 import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
 import {createSentryApiClient, type SentryApiClient} from '#api/client.js';
+import {createSentryWebhookProcessor} from '#core/webhook-processor.js';
 import {closeDb, db} from '#db/db.js';
 import {
   getSentryInstallationByConnectionId,
@@ -45,6 +46,11 @@ export {
   handleSentryInstallationDeleted,
   handleSentryIssueEvent,
 } from '#core/webhook.js';
+export type {
+  CreateSentryWebhookProcessorOptions,
+  SentryWebhookProcessor,
+} from '#core/webhook-processor.js';
+export {createSentryWebhookProcessor} from '#core/webhook-processor.js';
 export type {
   PersistVerifiedUnclaimedInstallationParams,
   SentryInstallation,
@@ -79,6 +85,14 @@ export function createSentryIntegrationProvider(options: CreateSentryIntegration
     options.getSentryInstallationByConnectionId ?? getSentryInstallationByConnectionId;
   const persistUnclaimed =
     options.persistVerifiedUnclaimedInstallation ?? persistVerifiedUnclaimedInstallation;
+  const webhookProcessor = createSentryWebhookProcessor({
+    sentry,
+    coreDb: options.coreDb,
+    publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+    recordDeliveryOnly: options.recordDeliveryOnly,
+    getIntegrationConnectionById: options.getIntegrationConnectionById,
+    updateConnectionLifecycleStatus: options.updateConnectionLifecycleStatus,
+  });
 
   return {
     provider: 'sentry' as const,
@@ -103,8 +117,10 @@ export function createSentryIntegrationProvider(options: CreateSentryIntegration
         recordDeliveryOnly: options.recordDeliveryOnly,
         getIntegrationConnectionById: options.getIntegrationConnectionById,
         updateConnectionLifecycleStatus: options.updateConnectionLifecycleStatus,
+        processor: webhookProcessor,
       }),
     ],
+    webhookProcessors: [{routeIds: ['sentry'] as const, processor: webhookProcessor}],
   };
 }
 

package/src/presentation/routes/webhooks.test.ts

@@ -617,7 +617,7 @@ describe('Sentry webhook route', () => {
     expect(recordDeliveryOnly).toHaveBeenCalledTimes(1);
   });
 
-  test('installation/deleted with no matching row records the delivery and does not disable', async () => {
+  test('installation/deleted with no matching row writes a tombstone and does not disable', async () => {
     const {app, recordDeliveryOnly, updateConnectionLifecycleStatus} = await createTestApp();
     const deliveryId = randomUUID();
     const body = JSON.stringify(
@@ -635,6 +635,7 @@ describe('Sentry webhook route', () => {
     });
 
     expect(res.statusCode).toBe(204);
+    expect((await readInstallation('never-installed'))?.status).toBe('deleted');
     expect(updateConnectionLifecycleStatus).not.toHaveBeenCalled();
     expect(recordDeliveryOnly).toHaveBeenCalledTimes(1);
   });
@@ -719,7 +720,7 @@ describe('Sentry webhook route', () => {
     expect(recordDeliveryOnly).toHaveBeenCalledTimes(1);
   });
 
-  test('installation/created records-and-drops when the code exchange fails', async () => {
+  test('installation/created stays pending when access denied has no success checkpoint', async () => {
     const installationUuid = 'install-created-exchangefail';
     const {app, recordDeliveryOnly} = await createTestApp({
       sentry: sentryClient({
@@ -745,9 +746,9 @@ describe('Sentry webhook route', () => {
       payload: body,
     });
 
-    expect(res.statusCode).toBe(204);
-    expect(await readInstallation(installationUuid)).toBeUndefined();
-    expect(recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(res.statusCode).toBe(500);
+    expect((await readInstallation(installationUuid))?.status).toBe('pending');
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
   });
 
   test('records the delivery only for a malformed installation payload', async () => {

package/src/presentation/routes/webhooks.ts

@@ -1,3 +1,8 @@
+import {randomUUID} from 'node:crypto';
+import {
+  createStoredWebhookRequest,
+  WEBHOOK_MAX_RAW_BODY_BYTES,
+} from '@shipfox/api-integration-core-dto';
 import {
   ClientError,
   defineRoute,
@@ -5,48 +10,41 @@ import {
   rawBodyPlugin,
   WEBHOOK_BODY_LIMIT,
 } from '@shipfox/node-fastify';
-import {logger} from '@shipfox/node-opentelemetry';
-import {config} from '#config.js';
-import {verifySentrySignature} from '#core/signature.js';
-import {handleInstallationResource} from './installation-handler.js';
-import {handleIssueResource} from './issue-handler.js';
+import {
+  createSentryWebhookProcessor,
+  type SentryWebhookProcessor,
+} from '#core/webhook-processor.js';
 import type {SentryWebhookContext} from './webhook-context.js';
-import {recordAndDrop} from './webhook-delivery.js';
-import {parseSentryWebhookRequest} from './webhook-request.js';
-
-const ISSUE_RESOURCE = 'issue';
-const INSTALLATION_RESOURCE = 'installation';
 
 export type {SentryWebhookContext} from './webhook-context.js';
 
-export function createSentryWebhookRoutes(context: SentryWebhookContext): RouteGroup {
+export function createSentryWebhookRoutes(
+  context: SentryWebhookContext & {processor?: SentryWebhookProcessor | undefined},
+): RouteGroup {
+  const processor = context.processor ?? createSentryWebhookProcessor(context);
   const webhookRoute = defineRoute({
     method: 'POST',
     path: '/',
     auth: [],
     description: 'Sentry integration webhook receiver.',
     options: {bodyLimit: WEBHOOK_BODY_LIMIT},
-    handler: (request, reply) => {
-      const {deliveryId, resource, signature, signatureHeaderName, rawBody} =
-        parseSentryWebhookRequest(request);
-
-      if (!verifySentrySignature({rawBody, signature, secret: config.SENTRY_APP_CLIENT_SECRET})) {
-        throw new ClientError('invalid signature', 'invalid-signature', {status: 401});
+    handler: async (request, reply) => {
+      const body = request.body;
+      if (!(body instanceof Uint8Array)) {
+        throw new ClientError('expected raw JSON body', 'invalid-body');
       }
-      logger().debug(
-        {deliveryId, signatureHeader: signatureHeaderName},
-        'sentry webhook: signature verified',
-      );
-
-      if (resource === ISSUE_RESOURCE) {
-        return handleIssueResource({context, reply, deliveryId, rawBody});
-      }
-      if (resource === INSTALLATION_RESOURCE) {
-        return handleInstallationResource({context, reply, deliveryId, rawBody});
+      if (body.byteLength > WEBHOOK_MAX_RAW_BODY_BYTES) {
+        throw new ClientError('Webhook request body is too large', 'body-too-large', {status: 413});
       }
 
-      // Unsupported resources are acknowledged so Sentry does not retry or disable the app.
-      return recordAndDrop({context, reply, deliveryId});
+      const result = await processor.process(
+        createSentryStoredWebhookRequest(
+          body,
+          request.headers,
+          request.raw.url?.split('?')[1] ?? '',
+        ),
+      );
+      return sendSentryWebhookResponse(reply, result, request.headers);
     },
   });
 
@@ -57,3 +55,64 @@ export function createSentryWebhookRoutes(context: SentryWebhookContext): RouteG
     routes: [webhookRoute],
   };
 }
+
+function createSentryStoredWebhookRequest(
+  body: Uint8Array,
+  headers: Record<string, string | string[] | undefined>,
+  rawQueryString: string,
+) {
+  try {
+    return createStoredWebhookRequest({
+      requestId: randomUUID(),
+      routeId: 'sentry',
+      receivedAt: new Date().toISOString(),
+      rawQueryString,
+      headers: sentryWebhookHeaders(headers),
+      body,
+    });
+  } catch (error) {
+    throw new ClientError('Webhook request metadata is invalid', 'invalid-webhook-request', {
+      cause: error,
+    });
+  }
+}
+
+function sentryWebhookHeaders(headers: Record<string, string | string[] | undefined>) {
+  return Object.fromEntries(
+    [
+      'content-type',
+      'request-id',
+      'sentry-hook-resource',
+      'sentry-hook-signature',
+      'sentry-app-signature',
+    ].flatMap((name) => {
+      const value = headers[name];
+      return typeof value === 'string' ? [[name, value]] : [];
+    }),
+  );
+}
+
+function sendSentryWebhookResponse(
+  reply: {code(statusCode: number): void},
+  result: import('@shipfox/api-integration-core-dto').WebhookProcessingResult,
+  headers: Record<string, string | string[] | undefined>,
+) {
+  if (result.outcome === 'discarded' && result.reason === 'invalid_signature') {
+    reply.code(401);
+    return {error: 'invalid signature'};
+  }
+  if (result.outcome === 'discarded' && result.reason === 'missing_required_input') {
+    const hasSignature =
+      typeof headers['sentry-hook-signature'] === 'string' ||
+      typeof headers['sentry-app-signature'] === 'string';
+    if (!hasSignature) {
+      reply.code(401);
+      return {error: 'missing signature'};
+    }
+    reply.code(400);
+    return {error: 'missing required input'};
+  }
+
+  reply.code(204);
+  return null;
+}

package/src/temporal/activities/prune-unclaimed-installations.test.ts

@@ -7,8 +7,7 @@ import {pruneUnclaimedSentryInstallationsActivity} from './prune-unclaimed-insta
 const DAY_MS = 24 * 60 * 60 * 1000;
 
 // The activity derives its cutoff from SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS
-// (default 7), so rows are seeded with an explicit createdAt to straddle it; the
-// persist helpers always stamp createdAt=now and could not exercise the cutoff.
+// (default 7), so rows are seeded with an explicit updatedAt to straddle it.
 describe('pruneUnclaimedSentryInstallationsActivity', () => {
   beforeEach(async () => {
     await db().delete(sentryInstallations);
@@ -30,6 +29,7 @@ describe('pruneUnclaimedSentryInstallationsActivity', () => {
     const result = await pruneUnclaimedSentryInstallationsActivity();
 
     expect(result.tombstoned).toBe(1);
+    expect(result.releasedPending).toBe(0);
     expect((await getSentryInstallationByInstallationUuid(staleUuid))?.status).toBe('deleted');
   });
 
@@ -47,6 +47,28 @@ describe('pruneUnclaimedSentryInstallationsActivity', () => {
     const result = await pruneUnclaimedSentryInstallationsActivity();
 
     expect(result.tombstoned).toBe(0);
+    expect(result.releasedPending).toBe(0);
     expect((await getSentryInstallationByInstallationUuid(freshUuid))?.status).toBe('installed');
   });
+
+  test('releases pending claims older than the retention window', async () => {
+    const staleUuid = randomUUID();
+    await db()
+      .insert(sentryInstallations)
+      .values({
+        connectionId: null,
+        installationUuid: staleUuid,
+        orgSlug: 'acme',
+        status: 'pending',
+        codeHash: 'hash',
+        createdAt: new Date(Date.now() - 8 * DAY_MS),
+        updatedAt: new Date(Date.now() - 8 * DAY_MS),
+      });
+
+    const result = await pruneUnclaimedSentryInstallationsActivity();
+    const installation = await getSentryInstallationByInstallationUuid(staleUuid);
+
+    expect(result).toEqual({releasedPending: 1, tombstoned: 0});
+    expect(installation).toBeUndefined();
+  });
 });

package/src/temporal/activities/prune-unclaimed-installations.ts

@@ -3,7 +3,10 @@ import {pruneUnclaimedSentryInstallations} from '#db/installations.js';
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
-export async function pruneUnclaimedSentryInstallationsActivity(): Promise<{tombstoned: number}> {
+export async function pruneUnclaimedSentryInstallationsActivity(): Promise<{
+  releasedPending: number;
+  tombstoned: number;
+}> {
   const olderThan = new Date(
     Date.now() - config.SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS * MS_PER_DAY,
   );

package/src/temporal/workflows/prune-unclaimed-installations-cron.ts

@@ -8,7 +8,10 @@ const {pruneUnclaimedSentryInstallationsActivity} = proxyActivities<
 });
 
 export async function pruneUnclaimedSentryInstallationsCron(): Promise<void> {
-  const {tombstoned} = await pruneUnclaimedSentryInstallationsActivity();
+  const {releasedPending, tombstoned} = await pruneUnclaimedSentryInstallationsActivity();
+  if (releasedPending > 0) {
+    log.info('Released stale pending Sentry installation claims', {releasedPending});
+  }
   if (tombstoned > 0) {
     log.info('Tombstoned stale unclaimed Sentry installations', {tombstoned});
   }