fix(state): align server/client state with best practices (query-key bugs, persist hygiene, useState)

.claude/rules/sim-hooks.md

@@ -48,3 +48,19 @@ export function useFeature({ id, onSelect }: UseFeatureProps) {
 4. Wrap returned functions in useCallback
 5. Server data goes through React Query (`hooks/queries/`), never `useState` + `fetch`
 6. Keep only UI/orchestration state in these hooks
+
+## State shape
+
+Never mirror a prop into state with `useState(prop)` + a syncing `useEffect` — a prop change clobbers in-progress local edits. Use the prop directly, reset via a remount `key`, or — when you must seed local state from a prop only on a transition (e.g. a modal opening) — reset during render with the `prevX` ref idiom:
+
+```typescript
+const prevOpenRef = useRef(open)
+if (prevOpenRef.current !== open) {
+  prevOpenRef.current = open
+  if (open) setName(initialName) // closed → open only
+}
+```
+
+Model mutually-exclusive flags as ONE `status` enum, not several contradictory booleans. `isLoading`/`isVerified`/`isInvalidOtp` describing one machine collapse to `status: 'idle' | 'verifying' | 'verified' | 'error'` (+ `errorMessage`); derive any boolean a consumer still needs (`status === 'error'`).
+
+Derive busy/success from the mutation object — never duplicate `mutation.isPending`/`mutation.isSuccess` into local `useState`. Read them directly (`mutation.isSuccess`) and reset with `mutation.reset()`.

.claude/rules/sim-queries.md

@@ -25,6 +25,8 @@ export const entityKeys = {
 
 Never use inline query keys — always use the factory.
 
+**Every identifier the `queryFn` uses MUST appear in the `queryKey`.** If the fetch is scoped by `workspaceId`, `cursor`, `limit`, an org id, etc., those values must be part of the key — otherwise distinct fetch args share one cache entry (a cross-tenant / per-param cache collision). The lone exception is a globally-unique id used as the key while a second fetch arg is only an authz scope that cannot collide; annotate those with `// rq-lint-allow: <reason>`. Enforced by the `key-fetch-arg-drift` check in `scripts/check-react-query-patterns.ts`.
+
 ## File Structure
 
 ```typescript
@@ -142,4 +144,4 @@ const handler = useCallback(() => {
 
 ## Enforcement
 
-`scripts/check-react-query-patterns.ts` (`bun run check:react-query`, run in CI) statically enforces these conventions: every `useQuery`/`useInfiniteQuery`/`useSuspenseQuery` declares an explicit `staleTime`, inline `queryFn`s destructure `signal`, `queryKey`s reference a colocated factory rather than an inline literal, and every `*Keys` factory in `hooks/queries/**` exposes an `all` root key. `hooks/queries/**` is a zero-tolerance zone; the rest of `apps/sim/**` is ratcheted against `scripts/check-react-query-patterns.baseline.json`. For a genuine exception, put `// rq-lint-allow: <reason>` on the line directly above the flagged construct.
+`scripts/check-react-query-patterns.ts` (`bun run check:react-query`, run in CI) statically enforces these conventions: every `useQuery`/`useInfiniteQuery`/`useSuspenseQuery` declares an explicit `staleTime`, inline `queryFn`s destructure `signal`, `queryKey`s reference a colocated factory rather than an inline literal, every `*Keys` factory in `hooks/queries/**` exposes an `all` root key, and every identifier the `queryFn` forwards into the fetch also appears in the `queryKey` (`key-fetch-arg-drift`). `hooks/queries/**` is a zero-tolerance zone; the rest of `apps/sim/**` is ratcheted against `scripts/check-react-query-patterns.baseline.json`. For a genuine exception, put `// rq-lint-allow: <reason>` on the line directly above the flagged construct.

.claude/rules/sim-stores.md

@@ -57,7 +57,7 @@ export const useFeatureStore = create<FeatureState>()(
 
 1. Use `devtools` middleware (named stores)
 2. Use `persist` only when data should survive reload
-3. `partialize` to persist only necessary state
+3. `persist` MUST use `partialize` with an explicit whitelist of the durable fields. NEVER persist transient flags (`isResizing`, drag/hover state) or `_hasHydrated`, and never spread the whole state (`{ ...state }`) — it leaks actions and transient state into storage
 4. `_hasHydrated` pattern for persisted stores needing hydration tracking
 5. Immutable updates only
 6. `set((state) => ...)` when depending on previous state

apps/sim/app/(auth)/verify/use-verification.ts

@@ -9,6 +9,15 @@ import { validateCallbackUrl } from '@/lib/core/security/input-validation'
 
 const logger = createLogger('useVerification')
 
+/**
+ * Mutually-exclusive phases of the email-OTP verification machine.
+ * - `idle`: awaiting input
+ * - `verifying`: a verify request is in flight
+ * - `verified`: code accepted, redirecting
+ * - `error`: last verify attempt failed (paired with `errorMessage`)
+ */
+type VerificationStatus = 'idle' | 'verifying' | 'verified' | 'error'
+
 interface UseVerificationParams {
   hasEmailService: boolean
   isProduction: boolean
@@ -18,9 +27,8 @@ interface UseVerificationParams {
 interface UseVerificationReturn {
   otp: string
   email: string
-  isLoading: boolean
-  isVerified: boolean
-  isInvalidOtp: boolean
+  status: VerificationStatus
+  isResending: boolean
   errorMessage: string
   isOtpComplete: boolean
   hasEmailService: boolean
@@ -41,10 +49,9 @@ export function useVerification({
   const { refetch: refetchSession } = useSession()
   const [otp, setOtp] = useState('')
   const [email, setEmail] = useState('')
-  const [isLoading, setIsLoading] = useState(false)
-  const [isVerified, setIsVerified] = useState(false)
+  const [status, setStatus] = useState<VerificationStatus>('idle')
+  const [isResending, setIsResending] = useState(false)
   const [isSendingInitialOtp, setIsSendingInitialOtp] = useState(false)
-  const [isInvalidOtp, setIsInvalidOtp] = useState(false)
   const [errorMessage, setErrorMessage] = useState('')
   const [redirectUrl, setRedirectUrl] = useState<string | null>(null)
   const [isInviteFlow, setIsInviteFlow] = useState(false)
@@ -96,8 +103,7 @@ export function useVerification({
   async function verifyCode() {
     if (!isOtpComplete || !email) return
 
-    setIsLoading(true)
-    setIsInvalidOtp(false)
+    setStatus('verifying')
     setErrorMessage('')
 
     try {
@@ -108,7 +114,7 @@ export function useVerification({
       })
 
       if (response && !response.error) {
-        setIsVerified(true)
+        setStatus('verified')
 
         try {
           await refetchSession()
@@ -135,12 +141,9 @@ export function useVerification({
       } else {
         logger.info('Setting invalid OTP state - API error response')
         const message = 'Invalid verification code. Please check and try again.'
-        setIsInvalidOtp(true)
+        setStatus('error')
         setErrorMessage(message)
-        logger.info('Error state after API error:', {
-          isInvalidOtp: true,
-          errorMessage: message,
-        })
+        logger.info('Error state after API error:', { errorMessage: message })
         setOtp('')
       }
     } catch (error: any) {
@@ -155,23 +158,18 @@ export function useVerification({
         message = 'Too many failed attempts. Please request a new code.'
       }
 
-      setIsInvalidOtp(true)
+      setStatus('error')
       setErrorMessage(message)
-      logger.info('Error state after caught error:', {
-        isInvalidOtp: true,
-        errorMessage: message,
-      })
+      logger.info('Error state after caught error:', { errorMessage: message })
 
       setOtp('')
-    } finally {
-      setIsLoading(false)
     }
   }
 
   function resendCode() {
     if (!email || !hasEmailService || !isEmailVerificationEnabled) return
 
-    setIsLoading(true)
+    setIsResending(true)
     setErrorMessage('')
 
     const normalizedEmail = normalizeEmail(email)
@@ -185,32 +183,37 @@ export function useVerification({
         setErrorMessage('Failed to resend verification code. Please try again later.')
       })
       .finally(() => {
-        setIsLoading(false)
+        setIsResending(false)
       })
   }
 
+  /**
+   * On a complete (6-char) code, clear any lingering message — including a
+   * resend failure (which sets `errorMessage` while `status` stays `idle`) — and
+   * exit the error state, matching the prior unconditional reset on a full OTP.
+   */
   function handleOtpChange(value: string) {
     if (value.length === 6) {
-      setIsInvalidOtp(false)
+      if (status === 'error') setStatus('idle')
       setErrorMessage('')
     }
     setOtp(value)
   }
 
   useEffect(() => {
-    if (otp.length === 6 && email && !isLoading && !isVerified) {
+    if (otp.length === 6 && email && status !== 'verifying' && status !== 'verified') {
       const timeoutId = setTimeout(() => {
         verifyCode()
       }, 300)
 
       return () => clearTimeout(timeoutId)
     }
-  }, [otp, email, isLoading, isVerified])
+  }, [otp, email, status])
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
       if (!isEmailVerificationEnabled) {
-        setIsVerified(true)
+        setStatus('verified')
 
         const handleRedirect = async () => {
           try {
@@ -234,9 +237,8 @@ export function useVerification({
   return {
     otp,
     email,
-    isLoading,
-    isVerified,
-    isInvalidOtp,
+    status,
+    isResending,
     errorMessage,
     isOtpComplete,
     hasEmailService,

apps/sim/app/(auth)/verify/verify-content.tsx

@@ -25,16 +25,19 @@ function VerificationForm({
   const {
     otp,
     email,
-    isLoading,
-    isVerified,
-    isInvalidOtp,
+    status,
+    isResending,
     errorMessage,
     isOtpComplete,
     verifyCode,
     resendCode,
     handleOtpChange,
   } = useVerification({ hasEmailService, isProduction, isEmailVerificationEnabled })
 
+  const isVerified = status === 'verified'
+  const isInvalidOtp = status === 'error'
+  const isBusy = status === 'verifying' || isResending
+
   const [countdown, setCountdown] = useState(0)
   const [isResendDisabled, setIsResendDisabled] = useState(false)
 
@@ -88,7 +91,7 @@ function VerificationForm({
                 maxLength={6}
                 value={otp}
                 onChange={handleOtpChange}
-                disabled={isLoading}
+                disabled={isBusy}
                 className={cn('gap-2', isInvalidOtp && 'otp-error')}
               >
                 <InputOTPGroup>
@@ -112,10 +115,10 @@ function VerificationForm({
 
           <button
             onClick={verifyCode}
-            disabled={!isOtpComplete || isLoading}
+            disabled={!isOtpComplete || isBusy}
             className={AUTH_SUBMIT_BTN}
           >
-            {isLoading ? (
+            {isBusy ? (
               <span className='flex items-center gap-2'>
                 <Loader className='size-4' animate />
                 Verifying…
@@ -138,7 +141,7 @@ function VerificationForm({
                   <button
                     className='font-medium text-[var(--landing-text)] underline-offset-4 transition hover:text-white hover:underline'
                     onClick={handleResend}
-                    disabled={isLoading || isResendDisabled}
+                    disabled={isBusy || isResendDisabled}
                   >
                     Resend
                   </button>

apps/sim/app/(landing)/components/contact/contact-form.tsx

@@ -69,7 +69,6 @@ export function ContactForm() {
       captureClientEvent('landing_contact_submitted', { topic: variables.topic })
       setForm(INITIAL_FORM_STATE)
       setErrors({})
-      setSubmitSuccess(true)
     },
     onError: () => {
       turnstileRef.current?.reset()
@@ -78,7 +77,6 @@ export function ContactForm() {
 
   const [form, setForm] = useState<ContactFormState>(INITIAL_FORM_STATE)
   const [errors, setErrors] = useState<ContactErrors>({})
-  const [submitSuccess, setSubmitSuccess] = useState(false)
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [website, setWebsite] = useState('')
   const [widgetReady, setWidgetReady] = useState(false)
@@ -141,6 +139,7 @@ export function ContactForm() {
   }
 
   const isBusy = contactMutation.isPending || isSubmitting
+  const submitSuccess = contactMutation.isSuccess
 
   const submitError = contactMutation.isError
     ? toError(contactMutation.error).message || 'Failed to send message. Please try again.'
@@ -161,7 +160,7 @@ export function ContactForm() {
         </p>
         <button
           type='button'
-          onClick={() => setSubmitSuccess(false)}
+          onClick={() => contactMutation.reset()}
           className='mt-6 font-season text-[13px] text-[var(--landing-text)] underline underline-offset-2 transition-opacity hover:opacity-80'
         >
           Send another message

apps/sim/app/(landing)/components/demo-request/demo-request-modal.tsx

@@ -69,22 +69,21 @@ export function DemoRequestModal({ children, theme = 'dark' }: DemoRequestModalP
   const [open, setOpen] = useState(false)
   const [form, setForm] = useState<DemoRequestFormState>(INITIAL_FORM_STATE)
   const [errors, setErrors] = useState<DemoRequestErrors>({})
-  const [submitSuccess, setSubmitSuccess] = useState(false)
 
   const demoMutation = useMutation({
     mutationFn: submitDemoRequest,
     onSuccess: (_data, variables) => {
       captureClientEvent('landing_demo_request_submitted', {
         company_size: variables.companySize,
       })
-      setSubmitSuccess(true)
     },
   })
 
+  const submitSuccess = demoMutation.isSuccess
+
   function resetForm() {
     setForm(INITIAL_FORM_STATE)
     setErrors({})
-    setSubmitSuccess(false)
     demoMutation.reset()
   }
 

apps/sim/app/workspace/[workspaceId]/home/components/mothership-view/components/resource-registry/resource-registry.tsx

@@ -255,9 +255,9 @@ const RESOURCE_INVALIDATORS: Record<
   scheduledtask: (qc, wId) => {
     qc.invalidateQueries({ queryKey: scheduleKeys.list(wId) })
   },
-  log: (qc, _wId, id) => {
+  log: (qc, wId, id) => {
     qc.invalidateQueries({ queryKey: logKeys.details() })
-    qc.invalidateQueries({ queryKey: logKeys.detail(id) })
+    qc.invalidateQueries({ queryKey: logKeys.detail(wId, id) })
   },
   /**
    * Integrations are sourced from the static integration catalog

apps/sim/app/workspace/[workspaceId]/knowledge/components/edit-knowledge-base-modal/edit-knowledge-base-modal.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { memo, useEffect, useState } from 'react'
+import { memo, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import {
@@ -44,15 +44,18 @@ export const EditKnowledgeBaseModal = memo(function EditKnowledgeBaseModal({
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
-  useEffect(() => {
+  // Reset form fields when the modal opens (open transitions false → true).
+  const prevOpenRef = useRef(open)
+  if (prevOpenRef.current !== open) {
+    prevOpenRef.current = open
     if (open) {
       setName(initialName)
       setDescription(initialDescription)
       setNameError(null)
       setDescriptionError(null)
       setError(null)
     }
-  }, [open, initialName, initialDescription])
+  }
 
   const validate = (): boolean => {
     let valid = true

apps/sim/app/workspace/[workspaceId]/logs/logs.tsx

@@ -525,7 +525,7 @@ export default function Logs() {
 
       try {
         const detailLog = await queryClient.fetchQuery({
-          queryKey: logKeys.detail(logId),
+          queryKey: logKeys.detail(workspaceId, logId),
           queryFn: ({ signal }) => fetchLogDetail(logId, workspaceId, signal),
           staleTime: 30 * 1000,
         })