feat(runner): instrument the NEED-DATA Sentry issues — setUser, fetch retry diagnostics, editor trail (DEV-2859)

[demtario]

The instrumentation half of DEV-2859. Item 0 (the Failed to fetch classifier fix) already shipped as #327; this is what makes the remaining questions answerable.

Three Sentry issues were left NEED-DATA by the DEV-2852 triage because they are not diagnosable from current telemetry. Precedent: DEV-2559's session-start tags resolved DEMOS-9, a 786-event mystery, and the decisive tag turned out to be cf_ray's absence.

Item 1 — Sentry.setUser() was missing app-wide

There was no Sentry.setUser call anywhere. Every setUser in apps/** is React local state. No sendDefaultPii, so not even an ip_address fallback identity.

users: 0 was therefore a literal statement that no user context exists — not that nobody was affected. That misled this very triage: DEMOS-2X was initially classified SUPPRESS partly on "0 users", and re-checking with trace ids showed 26 sampled events across 26 distinct traces on two separate days. That is an availability shape, not one visitor's blip.

Two-stage, because anonymous traffic is the majority: a synchronous seed in main.tsx before createRoot (so an early module-evaluation crash already has an identity), then an upgrade in auth.ts's currentUser() — the single funnel every route uses — with resets on the 401 and clearSession() paths. currentUser() is deliberately not called from main.tsx: it round-trips the Render-hosted broker, and routes that need no identity shouldn't pay that latency.

Privacy: the signed-in id is "u_" + sha256(trimmed, lowercased email).slice(0,16). No email, no username, no raw address ever set; the dev-bypass address is hashed like any other. Stated plainly: over a known internal address list a truncated hash is reversible by us — the goal is "don't ship addresses to a third party", not anonymisation.

The anonymous id is "s_" + random in sessionStorage, not localStorage, on purpose: localStorage would be a new persistent pseudonymous identifier on a public site. The cost of that choice: a reload mints a new id, so users on an anonymous issue counts sessions, not people. It's a floor, not a headcount — and it does not by itself answer "one visitor or 26" for DEMOS-2X. Item 2's attempt count does.

Plus an auth_mode tag (anonymous | google | api-token | dev-bypass), which doubles as a tripwire for the exact bundle leak the dist grep in AGENTS.md exists to catch.

Everything is behind the existing reportingEnabled guard, so nothing runs and no storage key is written under navigator.webdriver.

Item 2 — fetchVersions diagnostics, with the retry as the discriminator

fetchFailure.ts only ever classified; it has no measurement and no remedy. A bare Failed to fetch carries no status code because the request never completed, so nothing separated a visitor blip from a dip in ours.

• attempt 1 fails → retry once after 300ms → succeeds: breadcrumb only (the blip population stays silent)
• both fail → one synthesized event per page load (module latch), level: "warning", flat fingerprint
• !res.ok — our host answered → never retried, because retrying amplifies a real dip into a self-inflicted one
• per-attempt 5s AbortController (copied from checkVersionExists); a timeout does not retry either, so it can't stall the picker for 10s or storm during an outage

Tags: versions_fetch_attempts (the decisive one — a dip fails twice, a blip doesn't), versions_fetch_outcome, versions_fetch_online, versions_fetch_elapsed_bucket, net_effective_type, and api_base_origin.

That last one is a new candidate cause: a missing VITE_API_BASE leaves the http://localhost:8787 fallback in the production bundle, which fails for every visitor on that build. A localhost value there would settle DEMOS-2X outright.

This can't copy DEV-2559's shape — cf_ray is structurally unavailable when nothing arrives. Attempts + online + elapsed bucket + API-base origin are its substitutes.

Critically, the rethrown error stays classifiable: on exhaustion the original last error is rethrown with fetchDiagnostics attached non-enumerably and name/message untouched, so #327's isOpaqueNetworkFailure still matches and DEMOS-2X does not regress. catalog.ts's versions ${res.status} message is byte-identical to master so that population's grouping doesn't move.

Item 3 — DEMOS-1D editor trail

The obvious design is wrong and is not what shipped. sentry.ts sets maxBreadcrumbs: 200. A "Maximum update depth exceeded" loop calls onEdit thousands of times, so one breadcrumb per call would fill all 200 slots with identical entries and evict the preceding context that identifies the trigger — destroying the only evidence the change exists to collect.

Instead: a bounded ring buffer (capacity 24) with consecutive-identical coalescing, so a 3000-iteration loop occupies one slot carrying n: 3000 and the entry before it survives. Flushed once at capture via Sentry.addEventProcessor, which skips surface === "demo-runtime" so relayed preview events stay clean.

Two fields from the original ticket were wrong and are not here. version-switch never reaches onEdit (a version change re-pins via setFiles — its own trail entry). And the active tab is unreachable from App.tsx: it lives in packages/editor-shell, and adding a prop to a published package's surface for a temporary diagnostic is the arrangement sessionDiagnostics.ts explicitly refuses. path + seq substitute; packages/ is untouched.

Source is discriminated at the App-owned callsites, not inside onEdit: editor, style, style-reset, ai, ai-undo.

Privacy: records size = contents.length, never contents — onEdit's second argument is the visitor's own source code. path is visitor-authored too, so it's capped at 120 chars and excluded from every fingerprint. The loadWorkspace entry records the lineage prefix only (before the first :) so an ?import=<url> lineage can't carry a URL.

No onCaughtError: Sentry.reactErrorHandler() — Sentry.ErrorBoundary already captures the component stack, and adding that handler would double-report every boundary crash and corrupt the 17-event baseline this instrumentation exists to read. (React 19 owner stacks are dev-only and unavailable from a production bundle, which is why breadcrumbs are the only route — a different reason than the ticket assumed.) No fingerprint change for DEMOS-1D either: it's substatus-regressed and must keep receiving events into the same issue.

Two bugs found before landing

editorTrailTags() read the bare last buffer entry — but a Style-panel colour drag always ends with a flush-quiet entry, which masked the coalesced run of quiet style writes underneath it. That run is exactly the DEMOS-1D signal. Now walks back past trailing flush-quiet, with two tests.

visitorId guarded throwing storage methods, but reading the global sessionStorage accessor can itself throw under a storage-denial policy — which would have white-screened the app. Guarded by safeSessionStorage().

Verification

• pnpm test — 1125 tests / 1123 pass / 0 fail / 2 todo (todos pre-existing)
• pnpm typecheck — clean across all four packages
• New specs: identity 10, fetch-diagnostics 14, editor-trail 12
• Bundle hygiene: production build, grep -rl "localhost:8787\|VITE_DEV_USER\|dev@handsontable.com" dist → no matches

Two assertions are real privacy tests, not guards: hashedUserId's output contains no @ and no substring of the input local-part; and a sentinel passed as contents does not appear in snapshotEditorTrail(). The retry-storm guard asserts exactly one fetch call on !res.ok. The ring-buffer test proves 3000 pushes collapse to one entry and the pre-loop trigger survives.

Review follow-ups, in the second commit

withDocsFetchDiagnostics was applied to both branches of the docs catches, so a missing-artifact 404 got tagged context: "docs-fetch" next to a genuine transport failure — putting two faults under one context and defeating the DEMOS-7D filtering the tags exist for. Now gated on the transport sub-case only.

And the non-enumerability of fetchDiagnostics was only inferred from name/message staying intact. It's pinned directly now, verified to go red under enumerable: true.

Known gap, stated rather than hidden

The wiring in App.tsx, main.tsx, auth.ts and catalog.ts has no test coverage — none is importable by node --test (@sentry/react, import.meta.env, and a bare JSON import node can't resolve). Every decision lives in an import-free module that is tested; only wiring sits in those files. No text-grep assertions were added to fake it.

Related: docs-catalog.ts's fetchDocsJson was deliberately not routed through the new helper. A sibling ./x.js import doesn't resolve under node --experimental-strip-types, which would have broken that file's own direct-import test seam — so DEMOS-7D is served at the App.tsx callsites with a thinner bundle (online + API-base classification, no attempts/outcome). Thin, but it still answers two concrete single-cause questions: visitor offline, or VITE_API_BASE misconfigured to localhost in prod.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches auth/session reporting, startup fetch retry timing, and every edit path; mistakes could leak PII, double-report, or mis-classify outages, though guards (reportingEnabled, non-enumerable diagnostics, no contents in trail) are explicit.

Overview
Adds DEV-2859 observability so three NEED-DATA Sentry populations become diagnosable without changing product behavior (versions still fail open; docs errors still split path vs fetch).

Identity: Seeds anonymous Sentry.setUser + auth_mode before createRoot, upgrades to a truncated email hash on currentUser() success, and resets on 401/clearSession() — all behind reportingEnabled, with session-scoped visitor ids in sessionStorage.

Versions fetch: New fetchWithDiagnostics (one transport retry, 5s timeout, no retry on !res.ok/timeout) powers fetchVersions; exhausted failures emit a once-per-page-load warning with attempt/outcome/online/API-base tags, while retries that recover log breadcrumbs only. Docs transport failures get thinner scope tags via withDocsFetchDiagnostics without changing fetchDocsJson.

Editor trail: A bounded, coalescing trail records edits/workspace loads/version repins/style/chat/flush events (path redacted/capped, size only); main.tsx attaches trail tags/extras to outgoing events (skipping demo-runtime). onEdit is split into surface-specific wrappers wired to StylePanel and ChatPanel (isUndo on chat undo).

^{Reviewed by Cursor Bugbot for commit d936082. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: DEV-2852 Sentry triage: demo runner — 100 unresolved issues sorted, 6 real fixes
Task linked: DEV-2859 Instrumentation for the NEED-DATA issues — plus the fetch classifier bug that blocks DEMOS-2X
Task linked: DEV-2559 Runner: instrument Tier-2 session start so the 504s become diagnosable

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5350bc4. Configure here.}