The Admin Toolbox: Force-Complete, Impersonation, Stuck-Flow Fixes
Buttons with audit, reasons, and tight blast radius for stuck escrows, force-completers, stranded signups, and read-only impersonation.
The Admin Toolbox is the controlled escape path for tenant issues the regular UI cannot resolve: one tenant, one row, one stuck flow, with audit, a required reason, and the smallest possible blast radius.
Force-complete endpoints
Specific operational flows have a force-complete escape-hatch surfaced in the platform admin UI: a receiving session that won’t close because of a stale lock, a workflow stage that needs to advance even though one criterion is missing, a settlement run that aborted halfway. Each force-complete writes its own audit event with the reason, the actor, and the affected rows. The endpoints don’t exist for general use; they’re the “somebody needs to break the glass” path.
Three escape-hatches for stuck escrows
Escrows can wedge in three specific ways: deposit confirmed but funds didn’t arrive (payment-side mismatch), goods received but ship-guard didn’t lift (ship-event-side mismatch), release ready but settlement row failed to write (settlement-side mismatch). Each gets its own admin button under /admin/escrow with a confirmation prompt that spells out exactly what will be flipped — no compound actions hiding behind one click.
Manual Blancco sync trigger
Per-tenant Blancco sync runs on a cron, but if a tenant just configured the integration or just had a bulk-import that needs immediate attention, an admin button triggers the sync on demand. The trigger respects the same rate-limit and batching that the cron does — it’s the same code path, ahead of the next scheduled run.
Email-verification + stranded-signup recovery
When a tenant admin signs up but never receives the verification email, /admin/users surfaces the verification status and offers a re-send. Stranded signups (started but never completed) surface in /admin/onboarding with the option to manually clear or to re-send the welcome flow.
Subscription-status override
When a tenant’s subscription_status drifts from the billing provider’s reported status (rare, but it happens — webhook missed, manual cancel), /admin/billing has a direct override field with a required reason note; the override is audit-logged and the billing provider is reconciled on next webhook.
Impersonation with write-block
The biggest tool. /admin/impersonate lets platform staff sign in as a tenant user (read-only) to investigate what they’re seeing without bouncing emails. Middleware intercepts mutating HTTP methods (POST, PUT, PATCH, DELETE) on impersonated sessions and returns a 403 with a “impersonation is read-only” error. Session tracking writes every page the impersonator visits to the activity log — so a tenant asking “did somebody from the platform look at our data” gets a row, not a guess.
audit_events append-only at the trigger level
The audit_events table has database triggers that reject UPDATE and DELETE. Even an admin with elevated database access can’t silently rewrite the history. New rows can be inserted (a correction with a reference to the original event), but the original row stays. The Admin Toolbox can fix what’s broken; it cannot tidy up what was recorded.