feat(media-use): classify and tag heygen provider telemetry, harden test isolation

[miguel-heygen]

Summary

media-use's heygen-cli integration could tell you a resolve succeeded, but not why it failed along the way, or whether a successful call went through the free (OAuth) or paid (API-key) path. This closes both gaps, plus a real test-isolation bug where local test runs could reach the production telemetry endpoint.

Companion change to heygen-com/heygen-cli#212 (identity unification + auth telemetry) — the two land independently since neither repo's release blocks the other.

What changed

• Failure classification: heygen-cli errors (not found, not authenticated, outdated, rate limited) now map to a small stable reason instead of a raw, unbounded error string — including a new rate-limit/quota case that wasn't recognized before.
• Free vs. paid tagging: successful heygen-backed resolves now record whether the call used an OAuth session or an API key, without changing the existing auth-header logic other call sites depend on.
• Test isolation fix: local test runs previously relied solely on an env-var default to avoid hitting the real telemetry endpoint. That's now backed by a real interception seam (verified with a local test server), so the safety doesn't depend on every future test remembering to set the env var.

Design decisions

• The new failure reason is a stable reason value, not the display message or raw stderr text — stays a small enum a dashboard can group by, not free text.
• The free/paid signal is a new property, not encoded into the existing provider string, so it doesn't touch any dashboard tile that already keys off provider name.

Testing

• Full skills suite: 203 passed, 1 failed (pre-existing, unrelated to this change).
• oxlint / oxfmt --check: clean across all changed files.

Post-Deploy Monitoring & Validation

• No runtime/production monitoring needed beyond normal telemetry review — this is additive, best-effort instrumentation with no behavior change to resolve outcomes.
• Watch for: no increase in resolve failures or latency (telemetry calls are fire-and-forget and never block a resolve).

[somanshreddy]

Reviewed the diff end-to-end (all 9 files), traced the telemetry send path + flush ordering, and checked the classifier for exhaustiveness. Code LGTM — no correctness blockers. Telemetry-privacy invariant holds (reason is a fixed enum, never raw stderr; auth_method is oauth/api_key/absent; undefined dropped by JSON.stringify), and the interception-seam test isolation is a real improvement.

✅ Update (re-review 2026-07-10): all prior blockers resolved — merge-ready from my side.

• CI is green: the Skills: manifest in sync job now passes (manifest regenerated).
• Email-case identity split fixed: heygenAccountDistinctId now .trim().toLowerCase(), with a matching test. Confirmed the heygen-cli side (identityKey) lowercases symmetrically, so the cross-tool PostHog join actually holds.

Non-blocking nits (optional):

1. resolve.mjs:420-424 — ...heygenAuthMethodFor(provider) is spread before ...searchResult.metadata?.provenance. Inert today, but a future provider emitting authMethod in provenance would shadow the computed value. Consider spreading it after (the computed value is the intended source of truth).
2. telemetry.mjs — isTestOrCiContext() and optedOut() are near-identical env predicates for different purposes; a cross-referencing comment/shared helper would prevent drift. No bug.
3. heygen.mjs — heygenAuthMethod() and heygenAuthHeaders() independently encode "Authorization ⇒ OAuth"; a shared isOauthCred() would single-source it.
4. heygen-cli.mjs rate-limit classifier substring matches ("quota"/"throttled") on combined stderr+stdout have an inherent precision ceiling — acceptable since reason is a coarse grouping enum.

Questions (non-blocking):

1. Cache-hit auth_method replays how the asset was originally fetched, not the current resolve's auth. I think that's correct for a conversion signal — worth a one-line comment since the two paths compute it differently.
2. reused-explicit (resolve.mjs:1062) preserves the cached authMethod — confirming that's intended, consistent with Q1.

— Somu

[jrusso1020]

E2E verification (complement to Somu/tai's code passes; deferring approval to Terence/Somansh per the cross-tool-telemetry policy).

Ran f0143f26 in a throwaway worktree, exercised the real emit paths, and intercepted the PostHog payloads locally (nothing sent to prod PostHog):

• Builds + media-use tests green — telemetry.test.mjs 12/12, heygen-cli.test.mjs 20/20, resolve.test.mjs green (incl. the MEDIA_USE_TELEMETRY_HOST interception-seam test); regression "lowercased email regardless of casing" passes.
• Identity join → one profile (verified): real resolve emitted $identify distinct_id=demo@example.com $anon_distinct_id=shared-anon-e2e-0001 and media_use_resolve distinct_id=shared-anon-e2e-0001; config anonymousId unchanged (read, not regenerated). Same lowercased-email id + same shared ~/.hyperframes/config.json anon as heygen-cli feat(skills): add scene transitions skill with 35-type catalog #212 → single PostHog person; the uppercase-email split does not occur.
• No gaps: every event fires on every real path; media_use_provider_error awaited before every process.exit. Deliberate non-emit: --help/--stats/--adopt, pre-flight validation errors.
• PII-clean from captured payloads: props {type,source,provider,local_only,provider_override,surface,$ip:null} — intent text absent, no paths.
• CI 100% green.

Merge-ready on the e2e dimension.

— Rames Jusso