feat(documenso): rejection reason + poll fallback + rollback hardening + recipient UX

Documenso reliability + signer-UX bundle from the 2026-05-26 live UAT.
Each piece detailed in docs/superpowers/audits/active-uat.md with full
file:line + root cause + alternatives.

Webhook + poll convergence
- DocumensoRecipient (webhook payload type) gains rejectionReason +
  declineReason. The DOCUMENT_REJECTED / DOCUMENT_DECLINED handler
  coalesces them at the boundary so downstream code sees one stable
  field. Empty/whitespace normalised to null.
- DocumensoDocument.recipients[] (normalized client output) gains
  rejectionReason. normalizeDocument coalesces v2 + v1 field names the
  same way so poller consumers see identical shape.
- handleDocumentRejected signature gains rejectionReason. Stored on
  document_events.eventData, persisted in audit_logs metadata, quoted
  inline in the in-CRM rep notification (truncated 120 chars; full
  reason still on the audit row). New 'transfer' AuditAction added
  alongside.
- signature-poll job now handles REJECTED / DECLINED. Previously only
  SIGNED / COMPLETED / EXPIRED were reconciled, so a missed rejection
  webhook (stale tunnel URL is the typical dev cause) left documents
  stuck in 'sent' forever. The 5-min poll cycle now closes that gap —
  webhook becomes an optimisation, not a correctness requirement.

placeFields rollback gap
- custom-document-upload.service moved the synchronous field-placement
  map() INSIDE the same try/catch that wraps placeFields(). Previously
  the map's throw bubbled past the catch-and-rollback block, leaving
  Documenso with a live envelope + recipients but no fields, and the
  CRM document row stuck in 'sent' with no signing UI for the signers.
  Logger captures looked-up email + map keys on miss for diagnosis.
- Comment documents Documenso's by-email dedupe semantic so future
  readers don't reintroduce the per-recipient-row map assumption.

UploadForSigningDialog recipient UX
- New RECIPIENT_ROLE_META + RecipientRoleBadge helpers. Placement-step
  sidebar list rebuilt as a two-line layout (name + role badge / email
  on its own line) so duplicate-named recipients are visually
  distinguishable. FieldSidePanel dropdown SelectItem mirrors the same
  stacked shape.
- "Recipient" label renamed to "Assign this field to" with an explainer
  paragraph below.

SigningProgress copy-link parity
- Copy-link button now always renders for pending signers (disabled +
  explainer tooltip when signingUrl not yet issued). Reps can copy
  even when the URL hasn't been distributed via email yet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/services/documenso-client.ts

@@ -178,21 +178,30 @@ function normalizeDocument(raw: unknown): DocumensoDocument {
     (r.recipients as Array<Record<string, unknown>> | undefined) ??
     (r.Recipient as Array<Record<string, unknown>> | undefined) ??
     [];
-  const recipients = recipientsRaw.map((rec) => ({
-    id: String(rec.recipientId ?? rec.id ?? ''),
-    name: String(rec.name ?? ''),
-    email: String(rec.email ?? ''),
-    role: String(rec.role ?? ''),
-    signingOrder: Number(rec.signingOrder ?? 0),
-    status: String(rec.signingStatus ?? rec.status ?? 'PENDING'),
-    signingUrl: typeof rec.signingUrl === 'string' ? rec.signingUrl : undefined,
-    embeddedUrl: typeof rec.embeddedUrl === 'string' ? rec.embeddedUrl : undefined,
-    // Per-recipient signing token - required on the v1 Recipient model,
-    // present on every v2 envelope-distribute response. Documenso uses
-    // it as the URL tail (`/sign/<token>`) so it also matches what we
-    // see on subsequent webhook deliveries.
-    token: typeof rec.token === 'string' ? rec.token : undefined,
-  }));
+  const recipients = recipientsRaw.map((rec) => {
+    // Coalesce the two field names Documenso has used for rejection
+    // reason across versions. Empty string → undefined so consumers
+    // can `?? null`-fallback cleanly without re-checking truthiness.
+    const rawReason = (rec.rejectionReason ?? rec.declineReason) as string | undefined;
+    const rejectionReason =
+      typeof rawReason === 'string' && rawReason.trim().length > 0 ? rawReason.trim() : undefined;
+    return {
+      id: String(rec.recipientId ?? rec.id ?? ''),
+      name: String(rec.name ?? ''),
+      email: String(rec.email ?? ''),
+      role: String(rec.role ?? ''),
+      signingOrder: Number(rec.signingOrder ?? 0),
+      status: String(rec.signingStatus ?? rec.status ?? 'PENDING'),
+      signingUrl: typeof rec.signingUrl === 'string' ? rec.signingUrl : undefined,
+      embeddedUrl: typeof rec.embeddedUrl === 'string' ? rec.embeddedUrl : undefined,
+      // Per-recipient signing token - required on the v1 Recipient model,
+      // present on every v2 envelope-distribute response. Documenso uses
+      // it as the URL tail (`/sign/<token>`) so it also matches what we
+      // see on subsequent webhook deliveries.
+      token: typeof rec.token === 'string' ? rec.token : undefined,
+      rejectionReason,
+    };
+  });
   return { id, numericId, status, recipients };
 }
 
@@ -224,6 +233,10 @@ export interface DocumensoDocument {
      *  match recipients without leaning on email (which may be reused
      *  across roles). */
     token?: string;
+    /** Free-text rejection reason. v2 payloads use `rejectionReason`;
+     *  some 1.x payloads use the legacy `declineReason`. Coalesced
+     *  here so downstream poll/webhook consumers see one stable field. */
+    rejectionReason?: string;
   }>;
 }