fix(web): root-cause fix for daemon query retries + TQ conversion (WEB-7, WEB-2H)

[devin-ai-integration]

Prompt / plan

Root-cause fix for Sentry issues WEB-7 (77 events) and WEB-2H (1 event). Instead of suppressing errors via bestEffort (symptom treatment), this prevents them via TanStack Query retry and proper data-fetching patterns.

What changed

1. Shared daemon-error utilities (utils/daemon-errors.ts)

• isExpectedDaemonTransientError(error) — classifies 503/502/401/400-org-header as expected transient daemon startup errors. Moved from lib/sentry/capture-error.ts (wrong location per CONVENTIONS.md — not Sentry-specific)
• shouldRetryDaemonError(failureCount, error) — TQ retry predicate. retry: shouldRetryDaemonError is now the convention for daemon queries
• Re-exported from capture-error.ts for backward compatibility

2. WEB-7 fix (use-history-pagination.ts)

• Replaced unjustified retry: false with retry: shouldRetryDaemonError
• TQ now retries 503 "still starting up" transparently (user sees spinner → success, no error flash)

3. WEB-2H fix (web-search-card.tsx)

• Converted imperative useEffect + async IIFE secret read to TQ useQuery — gains retry, caching, abort, refetch-on-focus
• Eliminated: secretScopeRef, secretReadRevision (manual cache-bust), cancelled boolean, webSearchHasStoredKey useState
• Fixed permanent-false bug: old code set webSearchHasStoredKey = false on transient daemon 503 with no retry
• Added optimistic savedOverride state to prevent save button race condition during async config refetch
• Uses useDaemonConfigQuery + useDaemonConfigMutation + useProvisionProviderKey from PR refactor(web): split useDaemonConfig god-hook, fix untyped patches and double invalidation (LUM-2184) #33156's refactor

4. Defense-in-depth — bestEffort: true in error handlers catches anything retry doesn't cover (retries exhausted)

5. Convention docs — Updated CONVENTIONS.md and STATE_MANAGEMENT.md with daemon retry guidance

Architecture

daemon 503 → TQ retry (1s → 2s → 4s) → success (user sees loading → data)
                                       ↓ retries exhausted
                                  captureError(e, { bestEffort: true })
                                       → silences expected transient errors
                                       → reports real bugs (500, data integrity)

Closes LUM-2199
Related: LUM-2205 (same pattern in provider-editor-modal.tsx, separate PR)

Test plan

• bunx tsc --noEmit — clean
• bun run lint — clean
• All 7 CI checks passing (lint, typecheck, build, test, socket security)
• Unit tests added for isExpectedDaemonTransientError and shouldRetryDaemonError (daemon-errors.test.ts)
• Config/logic-only changes — Sentry noise will clear as stale caches expire post-deploy

Link to Devin session: https://app.devin.ai/sessions/c2e17ff1867f4ebd90aac007ea0f5453
Requested by: @ashleeradka

[linear]

LUM-2199

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 1 potential issue.

View 5 additional findings in Devin Review.

[ashleeradka]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ad62a900de

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Gate credential query on org readiness

In platform-hosted sessions this daemon request needs the Vellum-Organization-Id header, but the new TanStack query can run as soon as assistantId exists even if the org store has not hydrated yet. I checked apps/web/docs/STATE_MANAGEMENT.md and useIsOrgReady(): queries that need this header should include that gate; otherwise, if the 400 org-header retries exhaust before hydration completes, the query stays errored with webSearchHasStoredKey treated as false and users with an existing BYOK web-search key can be blocked/asked for a key until something else causes a refetch.

Useful? React with 👍 / 👎.

[devin-ai-integration]

Good catch — this is a real bug. Fixed in ca4f9da.\n\nAdded useIsOrgReady() gate to the credential query's enabled condition, matching the established pattern in conversation-queries.ts. The query now waits for org store hydration before firing, preventing 400 "Organization-Id header" errors that could exhaust retries and leave webSearchHasStoredKey permanently false.\n\nNote: useDaemonConfigQuery itself also lacks this gate (pre-existing), but that's a separate concern — it's gated on assistantId which in platform mode implies the lifecycle service has run, which typically means org is ready. The credential query was more vulnerable because it could mount eagerly via requiresProviderCredential before the config query resolves.

[vex-assistant-bot]

✦ APPROVE

Value: Replaces a bestEffort-style symptom mute with proper TanStack Query retry + the useIsOrgReady() hydration gate so WEB-7 (77 events) and WEB-2H stop firing for the reason they fire, not just at the Sentry shipping layer. Centralizes the daemon-transient predicate where every retry-aware caller can reach it.

What this does: Moves isExpectedDaemonTransientError from lib/sentry/capture-error.ts → utils/daemon-errors.ts (correct home, not Sentry-specific), adds shouldRetryDaemonError as the canonical TQ retry predicate (3 retries max, exponential backoff, fails fast on 500/programming bugs), wires it into use-history-pagination (replaces unjustified retry: false), and rewrites web-search-card.tsx to use useDaemonConfigQuery + useQuery for the secret-presence check — eliminating secretScopeRef, secretReadRevision, cancelled, and the permanent-false bug.

Review detail

Verified at HEAD ca4f9da9:

• daemon-errors.ts matches the predicate shape adopted in #33160 (503/502/401/400+org-header). MAX_DAEMON_RETRIES = 3 is sensible — at 1s/2s/4s backoff that's ~7s of recovery window, well above typical hydration time.
• use-history-pagination.ts:144 — retry: shouldRetryDaemonError is the right call. Old retry: false on history pagination was the textbook case the PR description calls out.
• capture-error.ts re-exports the predicate for migration compatibility — diff is strictly subtractive (–31/+5).

Codex P2 / Devin P1 — both real, both already addressed:

• Codex P2 (org-header hydration race on credential query): legitimate — same pattern just landed in #32912/#33160. Fixed by Devin in ca4f9da9 by adding useIsOrgReady() to the enabled predicate at line 125. Verified.
• Devin P1 (save button briefly re-enables in the refetch window between setSaving(false) and daemon config invalidation): real race. Fixed in e2c6e1d8 via the savedOverride synchronous bridge that clears when reconciled updates. The dual-state pattern (savedOverride for synchronous bridging + reconciled for ground truth) is clean.

Anti-pattern grep on full file at HEAD:

• Zero new runtime-boundary casts. as ServiceMode on the localStorage read is pre-existing parity with sibling cards.
• data!.found at L123 — gated by if (!response.ok) throw immediately prior; HeyAPI shape guarantees data when response is ok. Defensible.
• assistantId! at L112 — gated by enabled: !!assistantId && requiresProviderCredential && isOrgReady. Defensible.
• Zero @ts-ignore, zero eslint-disable, zero || 0.

Architecture note: useDaemonConfigQuery itself doesn't have the useIsOrgReady gate (Devin called this out in the response thread as a separate, pre-existing concern). Worth a follow-up — it's gated on assistantId, which transitively gates on assistantsListOptions succeeding, but on the platform path that upstream query needs the org header too. Probably a clean follow-up ticket rather than scope creep into this PR.

Test coverage: daemon-errors.test.ts (+107) covers the full status matrix (503/502/401/400-org/400-other/500/TypeError/Error) for both isExpectedDaemonTransientError and shouldRetryDaemonError, plus the failureCount >= MAX_DAEMON_RETRIES cap.

Vellum Constitution — Trust-seeking: replaces a silent-by-default Sentry mute with bounded, observable retry + an explicit hydration gate. Failure modes that survive retries still surface; expected transients no longer pollute the signal.

[vex-assistant-bot]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".