feat(background-checks): admin cancel/delete/retry (CS-475)

[Marfuen]

CS-475 — Admin cancel / delete / retry for background checks

Relates to: https://linear.app/compai/issue/CS-475

Problem

Customers get blocked when a background check errors. BackgroundCheckRequest has @@unique([organizationId, memberId]) (one row per member), so requestForMember() silently returns the stuck/errored row — there's currently no way to clear, cancel, or re-run it.

What this adds

Three admin actions on a member's background check, surfaced in the employee Background Check tab and gated by RBAC:

• Retry (member:update) — resubmit a failed/cancelled check. Free (reuses the original payment, no new charge), resets the record in place, keeps webhook history. Varies the Identity idempotency key by attempt (comp-background-check:{memberId}:{attempt}) so a genuinely fresh vendor check is created instead of the deduped old one.
• Cancel (member:update) — stop an invited/in_progress/in_review check Comp-side (writes the existing-but-unused cancelled status). handleWebhook now ignores events for cancelled rows so a late Identity webhook can't resurrect it.
• Delete (member:delete) — hard-delete the record (cascades webhook events), freeing the unique constraint so a fresh request can be made.

A state-machine guard rejects invalid transitions (e.g. retrying a completed check). Auditors are excluded automatically (no update/delete).

Changes

• DB: rerunCount column + migration.
• API: POST /v1/people/:id/background-check/retry, …/cancel, DELETE /v1/people/:id/background-check; new cancelForMember/retryForMember/deleteForMember service methods; attempt-aware Identity client; webhook terminal-guard for cancelled rows.
• Frontend: BackgroundCheckAdminActions component (status + permission gated, two-step delete confirm) wired into the employee Background Check tab.

Testing

• API: jest src/background-checks → 41/41 passing (8 suites), incl. new controller + service tests.
• Frontend: new BackgroundCheckAdminActions 5/5; EmployeeBackgroundCheck 17/17.
• 1 pre-existing vitest failure in an exemption test (Radix Select / jsdom) — exists verbatim on main, untouched here.

Decisions / scope

• Retry billing: free (reuses original payment).
• Cancel is Comp-side only — the Identity (Convex) vendor has no confirmed cancel/delete endpoint; confirming + wiring server-side cancellation is a follow-up.
• Data: cancel/retry reset in place & keep history; delete is the explicit hard-delete.

Notes for reviewers

• Repo-wide turbo typecheck is not fully green due to pre-existing issues unrelated to this PR (@trycompai/billing dist/ not built in fresh worktrees; errors in risks/training/timelines/offboarding-checklist/etc.). No typecheck errors in any file changed here.
• Design spec + implementation plan live under docs/superpowers/ (gitignored / local only).

Draft until manual click-through verification of retry/cancel/delete in the running app.

🤖 Generated with Claude Code

---

Summary by cubic

Adds admin actions to retry, cancel, or delete a member’s background check so stuck requests can be cleared and resubmitted (CS-475). Ensures fresh vendor checks on both new requests and retries via record-scoped idempotency, and blocks late webhooks from changing cancelled checks.

• New Features

  • Retry (free): resubmits failed/cancelled, increments rerunCount, uses Identity Idempotency-Key comp-background-check:{backgroundCheckRequestId} (create) and comp-background-check:{backgroundCheckRequestId}:{attempt} (retries), resets statuses/report in place, and on retry failure restores the prior status to preserve the cancelled terminal guard.
  • Cancel: allows invited/in_progress/in_review → cancelled; webhook records the event but ignores status changes for cancelled rows.
  • Delete: hard-deletes to free the org+member unique slot for a fresh request.
  • API: POST /v1/people/:id/background-check/retry, POST /v1/people/:id/background-check/cancel, DELETE /v1/people/:id/background-check; retry passes requester email; state guards block invalid transitions.
  • UI: BackgroundCheckAdminActions in the employee Background Check tab, permission-gated with confirm-before-delete; clears a pending delete confirm on Retry/Cancel.

• Migration

  • Add rerunCount to background_check_requests (default 0). Run Prisma migrations.

^{Written for commit a149fa4. Summary will update on new commits.}

[linear]

CS-475

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 2, 2026 8:05pm
comp-framework-editor	Ready	Preview, Comment	Jun 2, 2026 8:05pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
portal	Skipped		Jun 2, 2026 8:05pm

[Marfuen]

@cubic-dev-ai ultrareview this

[cubic-dev-ai]

@cubic-dev-ai ultrareview this

@Marfuen Starting ultrareview - a deeper analysis than a regular review. I'll post findings when complete.

[cubic-dev-ai]

Ultrareview completed in 11m 18s

4 issues found across 20 files

Confidence score: 3/5

• There is some meaningful regression risk here: apps/api/src/background-checks/background-checks.service.ts forcing initial requests to attempt: 0 can reuse the first idempotency key after delete/re-request, which may block creating a truly fresh vendor check in CS-475 resubmissions.
• The most severe backend behavior concern is in apps/api/src/background-checks/background-check-retry.ts, where retry failure can overwrite cancelled checks to failed, potentially allowing late webhook status resurrection on records that should stay cancelled.
• apps/api/src/background-checks/background-check-retry.ts also appears to allow delete across any background-check status instead of limiting to error-recovery states, and apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckAdminActions.tsx can leave delete pre-confirmed after Retry/Cancel, creating avoidable user-action risk.
• Pay close attention to apps/api/src/background-checks/background-checks.service.ts, apps/api/src/background-checks/background-check-retry.ts, and apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckAdminActions.tsx - idempotency, cancellation integrity, delete guardrails, and UI confirmation state need validation.

Linked issue analysis

Linked issue: CS-475: [QOL] - Create admin options to allow to cancel/delete background checks

Status	Acceptance criteria	Notes
✅	Add admin actions (Retry / Cancel / Delete) surfaced in the employee Background Check tab and gated by RBAC	Frontend component added and wired into the employee Background Check UI; it checks permissions before rendering and shows the correct buttons per status.
✅	Expose API endpoints to retry, cancel, and delete a member background check	Controller routes and HTTP methods were added with permission decorators and appropriate summaries.
✅	Retry resubmits a failed/cancelled check free of charge, varies idempotency key per attempt, and increments rerunCount	Service logic creates a new Identity check with an attempt-based idempotency key, updates the DB with the new identity id, and increments rerunCount; identity client constructs the idempotency key based on attempt; migration and schema add rerunCount.
✅	Cancel marks in-flight checks cancelled and prevents late vendor webhooks from resurrecting the record	Cancel service updates status to cancelled; webhook handler early-returns when record.status === cancelled so later webhooks don't change state; tests assert no update occurs for cancelled rows.
✅	Delete hard-deletes the background check record (cascading webhook events) and frees the organization+member unique slot	Delete service deletes the DB record; service/controller wrappers added and tests confirm deletion behavior and errors when missing.
✅	Enforce state-machine guards for allowed transitions (e.g., can't retry completed, can't cancel completed)	assertTransitionAllowed enforces allowed statuses for cancel/retry and service tests verify invalid transitions are rejected.
✅	RBAC: actions require appropriate permissions and auditors cannot update/delete	Controller methods are decorated with RequirePermission; frontend checks usePermissions to gate UI; tests mock permissions and assert rendered buttons and controller delegation.

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[Marfuen]

@cubic-dev-ai ultrareview this again

[cubic-dev-ai]

@cubic-dev-ai ultrareview this again

@Marfuen Ultrareview monthly budget exhausted (12/12 used). Budget resets at the start of next month.

[Marfuen]

@cubic-dev-ai review this

[cubic-dev-ai]

@cubic-dev-ai review this

@Marfuen I have started the AI code review. It will take a few minutes to complete.

[Marfuen]

@cubic-dev-ai review this

[cubic-dev-ai]

@cubic-dev-ai review this

@Marfuen I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

cubic analysis

No issues found across 20 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Linked issue analysis

Linked issue: CS-475: [QOL] - Create admin options to allow to cancel/delete background checks

Status	Acceptance criteria	Notes
✅	Add admin Retry action that resubmits a failed/cancelled background check (free), increments a rerun/attempt counter, and uses a per-attempt idempotency key so the vendor creates a fresh check.	retryForMember creates a new Identity request with idempotencyKey `comp-background-check:{existing.id}:{attempt}`, increments rerunCount, and the tests assert no charge and the idempotency key usage.
✅	Add admin Cancel action to mark an in-flight check (invited / in_progress / in_review) cancelled and ensure late vendor webhooks cannot resurrect it.	cancelForMember enforces allowed statuses and updates status to cancelled; webhook handler short-circuits when record.status === cancelled; tests verify cancelled record is not updated by webhooks.
✅	Add admin Delete action to hard-delete the background check record (cascading webhook events) and free the organization+member unique slot for a fresh request.	deleteForMember performs a hard delete; controller exposes DELETE endpoint; tests verify delete called and that it frees the slot (delete invoked).
✅	Expose API endpoints for admin actions: POST /v1/people/:id/background-check/retry, POST .../cancel, and DELETE /v1/people/:id/background-check (RBAC protected).	Controller adds routes with RequirePermission('member','update'/'delete'); controller tests exercise delegation to service methods.
✅	Enforce state-machine guards so invalid transitions are rejected (e.g., cannot retry a completed or in_progress check when not allowed).	assertTransitionAllowed enumerates allowed states for cancel/retry and is used before state changes; tests assert rejected transitions (e.g., retrying in_progress, cancelling completed).
✅	Frontend: Add BackgroundCheckAdminActions component in the employee Background Check tab, permission-gated, with two-step delete confirmation and behavior to clear pending delete when Retry/Cancel is clicked.	New component implements Retry/Cancel/Delete flows, uses permission checks, supports two-step delete and clears confirm on retry; integrated into EmployeeBackgroundCheck component; frontend tests verify UI and behaviors.
✅	DB migration: add rerunCount column to background_check_requests defaulting to 0.	Prisma schema updated and migration SQL added to add rerunCount column with default 0.
✅	Retries are free (do not create a new charge / reuse original payment) as described.	retry path creates an Identity check and updates the record without invoking paymentService.charge; tests confirm charge is not called during retry.
⚠️	Auditors are excluded automatically (no update/delete) per PR description.	Controller routes are permission-gated and frontend checks permissions, but there is no explicit change in this PR showing a named 'auditor' exclusion rule — this likely relies on existing permission system configuration outside these diffs.

_{Re-trigger cubic}

[claudfuen]

🎉 This PR is included in version 3.67.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀