Ambassador refinement — retune economics for friends (not funnel) + 1 HIGH bug

PROGRESS (commit e5b9415, held main): §2.1 HIGH FIXED (QualifyReferralOnVodArchived try/catch + log; test in QualifyReferralListenerResilienceTest). Economics RETUNED in config/vodmanager.php (base 50→1000GB, per-referral 25→50, cap 500→5000, referred 2.0→3.0, milestones 10/25/50/100→3/7/15/30 at 3.25/3.5/3.75/4.0). AppSettings still overlays these at /admin/settings/referrals. REMAINING in this brief: correctness edge cases 2.2–2.9 (chained-rename orphan link, free-tier resurrect on resync, per-account allocation vs single displayed number, approaching-cap warning, demotion exposes archives, free_tier.enabled guard inconsistency, NULL free_tier_multiplier repair, VERIFY ambassadors are exempt from the 8GB per-VOD cap); UX P0s (landing concrete numbers + avatar + dead invite-code row, acceptance warmth + live availability, share-kit hero + mobile-first + captions + stream-title snippet); P1 invite-delivery loop ("copy invite message"); per-user storage_override_gb that wins over the global formula; and the reranked deferred items (#576 emails first, #575 Reverb next, defer #574/#578/#579, ship the overlay-name privacy default pre-launch).

Deep review of the ambassador system through the "hand-picked trusted friends, happy to give huge free accounts, abuse/cost-against-strangers out of scope" lens (correctness + UX + strategy passes → Opus synth). Machinery is genuinely well-built (idempotent qualification, lock-guarded double-credit, retroactive multipliers, paid-tier exemptions, strong IA + tests). But not quite ready to hand to friends. DO THREE THINGS: (1) retune the economics, (2) fix the HIGH bug, (3) close the invite-delivery loop + put concrete numbers on landing/acceptance. == THE REFRAME (most important) == Shipped mechanics are a GROWTH FUNNEL: friend starts at 50 GB and climbs by referring strangers; first milestone is 10 qualified referrals (a friend-scale community likely never trips it, so the retroactive-bonus story stays dormant). Opposite of "here's a huge account on day one." Fix = no-deploy retune of ~6 numbers (config/vodmanager.php referrals + /admin/settings/referrals AppSettings overlay): | Knob | Current | Recommended | Why | |---|---|---|---| | ambassador_base_storage_gb | 50 | 1000 (1 TB) | real permanent archive on day one; B2 ~$6/TB/mo, 5 friends ~$30/mo | | ambassador_storage_per_qualified_referral_gb | 25 | 50–100 | satisfying line-goes-up thank-you | | ambassador_max_storage_gb | 500 | 5000 (or per-user override) | cap should never bite a friend; also fixes silent-purge edge 2.5 | | referred_base_multiplier | 2.0 | 3.0 | the shareable hook ("use my link, get 3× free storage") | | referred_max_multiplier | 4.0 | keep | fine | | milestones | 10/25/50/100 | 3/7/15/30 | first retroactive bump actually reachable → fires the "bonus went up" email | STRUCTURAL: allocation is a global formula overwritten on every qualify/settings-save (root of §2.4), so a manual per-friend bump gets clobbered. If "huge for hand-picked" means individualized, add nullable users.storage_override_gb that WINS over the formula. == CORRECTNESS (severity-ordered) == 2.1 HIGH — QualifyReferralOnVodArchived is a plain (non-queued) listener → runs SYNC inside UploadVodJob after the VOD is archived + temp file deleted; qualify() does lockForUpdate + updateOrCreate loops with NO try/catch. A lock timeout/deadlock throws out of UploadVodJob::handle → job marked FAILED+retried though the archive succeeded, and ArchiveChatJob/ArchiveStreamEventsJob/auto-encode/auto-transcribe/maybeFireFirstArchiveEvent are SILENTLY SKIPPED. Heavy trusted users (big cohorts, multi-account, concurrency) hit contention most. The OTHER listener on this event is ShouldQueue; this one is the odd one out. FIX: implements ShouldQueue + afterCommit, or wrap body in try/catch + log. **This is live on the held main; fix before any friend touches it.** 2.2 MED — chained code renames (A→B→C) orphan A's vanity link: replacementForRetiredCode resolves one hop only → /A returns 410 immediately though A's 60-day window is open. Fix: re-point replaced_by on retire, or follow the chain. 2.3 MED — syncAmbassadorStorage updateOrCreate resurrects a free-tier assignment an ambassador graduated away from (own storage). Fix: only UPDATE existing free-tier row, never create when a non-free primary exists. 2.4 MED — allocation written per Twitch account + QuotaService enforces per-assignment → 3-channel ambassador gets 3× capacity but dashboard shows one number (wrong), and cross-account purge won't balance. Decide per-account (label "per channel") vs per-user (share/divide). 2.5 MED — at the byte cap, oldest un-pinned VODs auto-purge silently; 500 GB default too low for intent + no approaching-cap warning (QuotaService already computes usagePercent/isIngestDisabled). Raise cap + surface warning. 2.6 LOW-MED — demoting an ambassador retroactively exposes their old large archives to time-purge/eviction + flips canKeepForever false. Grandfather or warn if demotion is used. 2.7 LOW — syncAmbassadorStorage ignores free_tier.enabled (assignAccountIfMissing checks it) → with the profile missing/inactive (live pre-deploy risk) ambassadors silently get no storage + archives fail with no ambassador signal. Add admin health check. 2.8 LOW — syncReferredMultipliers change-guard: SQL NULL != 2.5 is NULL, so a NULL free_tier_multiplier with matching referrer never repairs → resolves 1.0×. Also whereNull. Latent, seeder/manual only. 2.9 INFO — qualification fires on ANY VodArchivedEvent (incl. highlight clips/manual). Referred users get 2–4× retention + COUNT caps but the per-VOD 8 GB byte cap is UNMULTIPLIED and no keep-forever. VERIFY BEFORE LAUNCH: ambassadors are exempt from the 8 GB per-VOD cap (else a 1 TB allocation can't hold a 6-hr stream — "huge account" quietly fails for long-session streamers). == UX (highest-impact) == P0 landing (referrals/landing.blade.php): "Boosted free storage" x2 with ZERO numbers — resolve the ambassador's actual multiplier + show concrete numbers; the "Invite code" row is dead/confusing (attribution is session-based) → drop/reframe; no avatar (Twitch profile_image_url is available) → "[Name] invited you" + face; add reassurance line + CTA hierarchy. P0 acceptance (AmbassadorAcceptance): cold heading → "You're in. We hand-picked you." (invitedBy exposed); "How it works" hides the offer → concrete numbers; live-availability is misleading (preview renders as owned on 500ms debounce but only checks on button click) → wire availability into the debounce. P0 share kit (AmbassadorDashboard::shareKit): primary link + share kit in different columns + pushed way down on mobile → consolidate into a "Your link" hero FIRST; snippets in font-mono look like config → normal type + captions; STREAM TITLE snippet appears DROPPED (CLAUDE.md says stream title/panel/chat but shareKit returns only panel_text+chat_command — confirm not a regression); !addcom is StreamElements-only (Nightbot = !commands add); multiplier formatting inconsistent (2.0x vs 2x). P1 naming: the referee bonus is called 4 things (Viewer bonus / Referred bonus / boosted free tier / referred-user multiplier) → pick one, anchor in plain language. P1 empty state + invite delivery: brand-new dashboard is flat (add warm first-run CTA + label "Your allocation"); THE INVITE LOOP IS OPEN — creating an invitation only whitelists a Twitch login, no way to notify the friend (invisible until they log in). Add "Copy invite message"/pre-fill invite link — launch-critical for a hand-picked program (distinct from reward-email #576). P1 overlay token rotation is admin-only ("ask an admin") → give ambassador self-service; collapse the overlay section into an Advanced/OBS disclosure so the link stays hero. P2 privacy: overlays broadcast real signup NAMES live on stream while history hides emails — treat referred-user overlay opt-out/anonymization as PRE-LAUNCH (default to first-name/initial). Plus 15s meta-refresh flash, ledger reads like an accountant, dark-mode fragility, "app-owned storage" jargon, silent copy-button failure. == DEFERRED (#574–579) RERANKED for friends == 1. #576 reward-email SENDERS — DO IT, promote to top (templates exist; relationship cohort → appreciation is highest-leverage; pairs with compressed milestones so the bump email fires). Gated on Mailgun. 2. #575 Reverb-live overlays — MED-HIGH soon (on-stream pop = promotion fuel; polling works today). 3. #577 overlay opt-out — LOW, but the privacy DEFAULT should ship pre-launch (see P2). 4. #574 admin cost dashboard — DOWNGRADE to LOW (explicitly push back on HANDOFF's "high/before scaling": you're happy to pay; only high the day you open wider). 5. #578 code profanity — DEFER (trusted + admin-overridable). 6. #579 open to non-ambassador tiers — DEFER indefinitely (that's the stranger funnel you scoped out). BOTTOM LINE: fix §2.1, retune 6 numbers (§4a), close invite delivery (P1), put numbers on landing+acceptance. Everything else can follow launch. Relates to deploy-readiness #146 + comms-copy #147.