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

* fix(queries): close React Query key/fetch-arg drift cache collisions

Several query hooks fetched with an identifier that was absent from their
queryKey, so distinct fetch args shared one cache entry. Thread the missing
args into the key factories and update all callsites/invalidations.

- organization: useOrganization always fetched the ACTIVE org via
  getFullOrganization() while caching under detail(orgId). Pass orgId through
  to the better-auth call (query.organizationId); active-org behavior unchanged.
- logs: logKeys.detail now keys on (workspaceId, logId) to prevent cross-
  workspace collision; updated useLogDetail, useLogByExecutionId, prefetchLogDetail,
  useCancelExecution optimistic path, and external callsites.
- inbox: inboxKeys.taskList now includes cursor/limit (pagination args were sent
  but omitted from the key); keepPreviousData pagination UX preserved.
- a2a: narrow create/update byWorkflows() invalidation to byWorkflow(ws, wf)
  since their responses reliably carry both ids; delete/publish stay broad.

Not bugs (verified, left unchanged):
- kb/connectors update/delete invalidate knowledgeKeys.detail(kbId), which is a
  prefix of connectorKeys.all(kbId) — connector list/detail are invalidated
  transitively by React Query prefix matching.

Harness: add a key-fetch-arg-drift check to check-react-query-patterns.ts that
flags a camelCase identifier the queryFn forwards into the fetch but is absent
from the queryKey (excludes the requestJson contract arg, PascalCase/SCREAMING
constants, and signal/pageParam machinery). Document the rule in sim-queries.md.
tables.useTable annotated rq-lint-allow (tableId globally unique; workspaceId is
only an authz scope).

* fix(stores): whitelist durable fields in persist partialize

chat/terminal/panel persist configs leaked actions and transient state
into localStorage. Replace the chat full-state spread with an explicit
durable whitelist, and add partialize to terminal and panel (which had
none) so isResizing and _hasHydrated are no longer persisted. Panel keeps
activeTab + panelWidth because the layout.tsx blocking script reads them
from panel-state to set data-panel-active-tab before hydration (SSR
tab-flash prevention).

Harden sim-stores doctrine: persist MUST use an explicit partialize
whitelist; never persist transient flags or _hasHydrated.

* fix(state): model component useState as single source of truth

- edit-knowledge-base-modal: reset fields on closed→open via prevOpenRef
  render idiom instead of mirroring props into state through useEffect
  (a prop change while open no longer clobbers in-progress edits)
- use-verification: collapse contradictory isLoading/isVerified/isInvalidOtp
  booleans into a single status enum + errorMessage; consumer derives flags
- contact-form / demo-request-modal: derive busy/success from the mutation
  object; delete duplicated submitSuccess local state
- sim-hooks.md: add state-shape rule (no props-into-state, status enum,
  derive mutation state)

* fix(verify): clear lingering message on complete OTP (restore parity)

* docs(state): convert inline reset comment to TSDoc

* docs(state): tighten harness rules for accuracy (queryFn forwards, partialize whitelist, mutation-flag caveat)

* fix(verify): block auto-verify while a resend is in flight (restore parity)

* fix(logs): key cancel optimistic detail by route workspaceId (not the log row)

Author: waleedlatif1

.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()`. A distinct phase the mutation doesn't cover — e.g. a pre-submit captcha/Turnstile gate that runs before `mutate()` — is not a duplicate; keep that flag.

.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` forwards into the fetch MUST appear in the `queryKey`.** (Query-machinery identifiers — `signal`, `pageParam` — are exempt; they aren't fetch-scoping args.) 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. Exclude transient flags (`isResizing`, drag/hover state) and `_hasHydrated` from the whitelist, 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,43 @@ 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' &&
+      !isResending
+    ) {
       const timeoutId = setTimeout(() => {
         verifyCode()
       }, 300)
 
       return () => clearTimeout(timeoutId)
     }
-  }, [otp, email, isLoading, isVerified])
+  }, [otp, email, status, isResending])
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
       if (!isEmailVerificationEnabled) {
-        setIsVerified(true)
+        setStatus('verified')
 
         const handleRedirect = async () => {
           try {
@@ -234,9 +243,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,21 @@ export const EditKnowledgeBaseModal = memo(function EditKnowledgeBaseModal({
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
-  useEffect(() => {
+  /**
+   * Seed the fields only on the closed → open transition (render-phase reset),
+   * so a prop change while the modal is open never clobbers in-progress edits.
+   */
+  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

@@ -505,7 +505,7 @@ export default function Logs() {
     }
   }, [contextMenuLog])
 
-  const cancelExecution = useCancelExecution()
+  const cancelExecution = useCancelExecution(workspaceId)
   const retryExecution = useRetryExecution()
 
   const handleCancelExecution = useCallback(() => {
@@ -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,
         })