Fix the Status writer's tab race, reload gap and silent errors #492

Summary

useHandleUserStatus writes users.status for the signed-in user. It has five faults: a tab race, a reload gap, the dedupe guard, a dead offline listener, and silent errors.

Step 1 fixes faults 2 to 5 and the in-window tab switch. It changes one hook and one doc line. It needs no SQL and no ruling, because it keeps today's hide write.

Problem

Code read at HEAD a192da752. The cited files are identical at db481158b.

Current code

• Mount. AppProviders.tsx:45 calls useHandleUserStatus(documentShell). It is enabled only on /[...slugs], /editor and /c/[channelId] (routePolicy.ts:9).
• One debounce for both directions. Show and hide both go through one 3 s debounce (useHandleUserStatus.ts:43-78). A 60 s interval writes ONLINE while the tab is visible (:34-41, :58-61).
• Dedupe guard. :16-32 skips a write when sessionStorage.userLastStatus already equals it and user.status equals it. user.status is always 'ONLINE', because applySignedInProfile.ts:32 pins it. The client cannot read status back (Stop exposing every user's online status and last-active time #434).
• Unload. beforeunload sends a keepalive PATCH {status:'OFFLINE'} to Supabase REST with the JWT held in accessTokenRef (:80-116).
• Effect deps. Every callback depends on the whole profile object (:31, :140-149). A profile_changed broadcast calls setProfile (useProfileSync.ts:48). That re-runs the effect, and its cleanup cancels a pending hide write (:138).

The five faults

1. Tab race. Tab A hides and writes OFFLINE 3 s later while tab B is visible. The row reads OFFLINE until B's next heartbeat, up to 60 s later. In an in-window tab switch, A's OFFLINE and B's ONLINE leave through equal 3 s debounces, so their order is not fixed. With side-by-side windows, B gets no show event at all.
2. Reload gap. beforeunload writes OFFLINE, and the pending 3 s write dies. So sessionStorage.userLastStatus still reads 'ONLINE'. On remount the guard skips the ONLINE write. The first heartbeat comes 60 s later.
3. The dedupe guard records a write before it runs. sessionStorage.setItem runs before the write (:23). A failed write still counts as done.
4. Dead offline listener (:128). The global fetch rejects when !navigator.onLine (component.ts:24-27), so that write never leaves the browser.
5. Silent errors. updateUser returns { error } (updateUser.ts:4-9). postgrest-js 2.117.3 catches fetch failures and also returns { error }, and it never retries a PATCH. So the catch blocks at :26 and :38 never run.

Who reads the flag

Mention and reply bell rows do not read status. No app code subscribes to postgres_changes on public.users (grep). Client Realtime presence keeps its own state and is not affected.

The lease is internal.is_user_online: status = 'ONLINE' AND online_at > now() - interval '2 minutes'. The cron job update-user-status runs */2 * * * * and sets OFFLINE where online_at < now() - interval '2 minutes'. Both were read from the local database.

These paths already leave by the lease today: sign-out (useSignOut.ts writes no status), a move to Home, and a frozen mobile or PWA page.

Decisions

None. Step 1 keeps today's hide write, so it changes no product rule.

A heartbeat-only writer (no tab writes OFFLINE) was considered and rejected; see #496 Rejected by the review. The two wrong states cost different things:

• A false OFFLINE (today's tab race) gives a user at the screen an extra bell and push.
• A false ONLINE loses the notification. A plain message makes no bell row, push or email, and mention push is dropped at insert.
• A heartbeat-only writer opens a false ONLINE window of 60 to 120 s whenever the last visible tab hides. A switch to another app does this, so it is common.
• Step 1 leaves a false OFFLINE only in rarer cases: side-by-side windows, a background tab close, and a beforeunload that does not unload.

Depends on

• Nothing must ship first. This issue can ship in any order with Stamp online_at only on ONLINE writes and clear users stuck ONLINE #489, Make the chat bell use the online lease instead of the raw status flag #490 and Make presence heartbeats HOT updates and drop the duplicate username index #491.
• Stop exposing every user's online status and last-active time #434 is shipped. Its closing comment says migration 20261009120500 is applied in production. authenticated keeps UPDATE on users.status, and Step 1 still writes status.
• Stamp online_at only on ONLINE writes and clear users stuck ONLINE #489 makes the trigger stamp online_at only on an ONLINE write. After Stamp online_at only on ONLINE writes and clear users stuck ONLINE #489, the Step 1 hide write no longer moves online_at.
• Use one client presence rule so the @ picker agrees with the avatars #493 says this issue owns useHandleUserStatus.ts:21. Step 1 deletes that line. The status pin stays, so Use one client presence rule so the @ picker agrees with the avatars #493 still holds.

Fix plan

Work on main. Read AGENTS.md, apps/webapp/CLAUDE.md and CONTEXT.md §Product HTTP first. Use Bun only.

Name the writer writeStatus. CONTEXT.md:100 lists updateUserStatus under Avoid. Do not touch the unrelated updateUserStatus in useBroadcastListener.ts:38.

Step 1. Fix the writer

Rewrite apps/webapp/src/hooks/useHandleUserStatus.ts to this shape. Two blocks come from today's file:

• The JWT effect body is today's :82-96, with user replaced by userId. Do not paste :81 or :97; the template already has the useEffect wrapper.
• The unload body is today's :102-115, the keepalive fetch, with user.id replaced by userId. Keep the fetch call exactly as it is.

import { updateUser } from '@api'
import { useAuthStore } from '@stores'
import { supabaseClient } from '@utils/supabase'
import debounce from 'lodash/debounce'
import { useEffect, useRef } from 'react'

const ONLINE = 'ONLINE'
const OFFLINE = 'OFFLINE'
const HEARTBEAT_INTERVAL = 60_000 // under the 2-minute lease in internal.is_user_online
const HIDE_DELAY = 3_000
// 2 s past HIDE_DELAY: a hidden tab's timers can fire about 1 s late, and the shown tab must write last.
const SHOW_DELAY = 5_000

export const useHandleUserStatus = (enabled = true) => {
  const userId = useAuthStore((state) => state.profile?.id)
  const accessTokenRef = useRef<string | null>(null)

  // Hold the JWT so unload can start keepalive in the same turn.
  useEffect(() => {
    /* today's :82-96 (the effect body), with `user` replaced by `userId` */
  }, [enabled, userId])

  useEffect(() => {
    if (!enabled || !userId) return
    let heartbeat: ReturnType<typeof setInterval> | null = null

    const writeStatus = async (status: typeof ONLINE | typeof OFFLINE) => {
      if (!navigator.onLine) return // the global fetch rejects offline; skip to keep the log quiet
      const { error } = await updateUser(userId, { status })
      if (error) console.warn(`Status write ${status} failed`, error.message)
    }
    const showWrite = debounce(() => void writeStatus(ONLINE), SHOW_DELAY)
    const hideWrite = debounce(() => void writeStatus(OFFLINE), HIDE_DELAY)
    const stopHeartbeat = () => {
      if (heartbeat) clearInterval(heartbeat)
      heartbeat = null
    }
    const show = () => {
      hideWrite.cancel()
      showWrite()
      stopHeartbeat()
      heartbeat = setInterval(() => void writeStatus(ONLINE), HEARTBEAT_INTERVAL)
    }
    const hide = () => {
      showWrite.cancel()
      stopHeartbeat()
      hideWrite()
    }
    const onVisibility = () => (document.visibilityState === 'visible' ? show() : hide())
    const onOnline = () => {
      if (document.visibilityState === 'visible') showWrite()
    }
    const handleUnload = () => {
      showWrite.cancel()
      hideWrite.cancel()
      /* today's :102-115 keepalive PATCH, with userId */
    }

    if (document.visibilityState === 'visible') show()
    document.addEventListener('visibilitychange', onVisibility)
    window.addEventListener('online', onOnline)
    window.addEventListener('beforeunload', handleUnload)
    return () => {
      stopHeartbeat()
      showWrite.cancel()
      hideWrite.cancel()
      document.removeEventListener('visibilitychange', onVisibility)
      window.removeEventListener('online', onOnline)
      window.removeEventListener('beforeunload', handleUnload)
    }
  }, [enabled, userId])
}

The rules this shape must keep:

• ONLINE and OFFLINE each have their own debounce. Show cancels the pending OFFLINE, and hide cancels the pending ONLINE. Without the cross-cancel, a show then a hide within 5 s races.
• SHOW_DELAY must stay at least 2 s longer than HIDE_DELAY. Browsers throttle timers in a hidden tab, so the hide write can fire about 1 s late. This is read from browser behaviour; browser check 1 measures it.
• The 60 s interval calls writeStatus(ONLINE) directly, not through the debounce. It starts on show and stops on hide.
• The online event goes through the ONLINE debounce, and only when the tab is visible.
• An offline skip writes nothing and logs nothing. The server row did not change.

Deletes:

• the sessionStorage guard (faults 2 and 3)
• the offline listener (fault 4)
• both dead try/catch blocks
• the 'Updated user status' console.info
• the useAuthStore ? guard at :12

Adds: one console.warn on { error } (fault 5). PostgREST returns no error when RLS filters an UPDATE to 0 rows. So the warn covers transport and permission failures only. Do not add count.

Behaviour changes to state in the PR:

• In-window tab switch: A writes OFFLINE at about +3 s, and B writes ONLINE at +5 s. The row reads OFFLINE for at most about 2 s. Today it can read OFFLINE for up to about 57 s when the OFFLINE write lands last.
• Reload: the old page's keepalive OFFLINE lands at once. The new page writes ONLINE 5 s after the profile loads. Nothing guarantees this order, but the 5 s gap makes it hold in practice.
• Reorder: an OFFLINE and a later ONLINE can still swap. In a tab switch, the OFFLINE request must stay in flight for more than about 1 s. In one tab, it must stay in flight for more than 5 s.
• Return latency: a tab that shows writes ONLINE after 5 s, up from 3 s.
• Background mount: a tab opened hidden writes nothing until it is shown. Today it writes ONLINE after 3 s.
• Keyed on userId: a profile_changed broadcast no longer re-runs the effect, so a profile save no longer cancels a pending hide write.
• Not fixed in Step 1:
  • side-by-side windows, where B gets no show event;
  • a beforeunload that fires while the page stays open, for example the Report row's mailto: link (reportContent.ts:25), read from code only;
  • closing or reloading a background pad tab while another pad tab is visible: OFFLINE for up to 60 s.

Doc:

• apps/webapp/CLAUDE.md:221: change "Heartbeat, visibility, online, and offline stay" to "Heartbeat, visibility, and online stay".

Check:

bunx eslint --max-warnings=0 apps/webapp/src/hooks/useHandleUserStatus.ts
bun run --filter @docs.plus/webapp typecheck

Both must exit 0. Do not run next build while next dev is running.

Rollout

PR, then app deploy. No SQL. Old tabs keep today's writer until they reload, which is safe.

Rollback

Revert the webapp commit and redeploy. There is no data and no SQL to undo.

Verify

Run the app with make dev-local from the repo root. It runs next dev on http://localhost:3000.

Sign in from Home at http://localhost:3000 with an email link, not from a pad URL; a magic link to a pad drops the auth hash. Read the link in the local mail catcher at http://localhost:54324. Then open a pad.

Find your user id, then poll the row once a second. N is the number of polls:

docker exec supabase_db_docsplus_supabase psql -U postgres -d postgres -Atc "select id, email from auth.users order by last_sign_in_at desc nulls last limit 3;"
USER_ID=<your id>
poll() { for i in $(seq 1 "$1"); do docker exec supabase_db_docsplus_supabase psql -U postgres -d postgres -Atc "select now()::time(0), status, online_at::time(0), internal.is_user_online(id) from public.users where id = '$USER_ID';"; sleep 1; done; }

Step 1. Start a new poll 30 run for each check:

1. In-window tab switch. Open two pad tabs in one window. Switch from A to B after about 5 polls. Expected: OFFLINE for at most about 2 s, from about +3 s, then ONLINE from about +5 s to the end. Do this 5 times, because the old race was intermittent. Every run must pass.
2. Reload. Reload a pad tab after about 5 polls. Expected: OFFLINE right after the reload, then ONLINE about 5 s after the pad loads. Pass: ONLINE within 15 s of the reload, and no OFFLINE after that. 15 s is a chosen threshold. Today the row stays OFFLINE until the first 60 s heartbeat.
3. Hide and return. Hide a tab for 4 to 5 s, then return. Expected: ONLINE again about 5 s after return.
4. Error log. In the hook's own updateUser call, change { status } to { statusx: status } as a temporary edit. Expected: one Status write ONLINE failed warn per failed write. Revert the edit. Do not break apps/webapp/src/api/users/updateUser.ts, because Settings shares it. DevTools Offline mode shows no warn, because of the navigator.onLine skip.

Add no Cypress test. Cypress drives one tab, and this is not dense logic (AGENTS.md §Test Policy).

Scale

• About 181 users in production (2026-09-28 Supabase review). The hook sends about one heartbeat per visible tab per minute. Writes stay negligible to 1000x; the cost per heartbeat is Make presence heartbeats HOT updates and drop the duplicate username index #491's subject.
• A heartbeat fires no profile_changed broadcast and no Realtime change. Measured locally: the only update triggers are trigger_update_user_online_at and users_profile_changed, and the second skips status. Stop exposing every user's online status and last-active time #434 took public.users out of supabase_realtime.
• Step 1 writes about as often as today. It adds at most one write per hide shorter than 3 s, which the old guard skipped.

Acceptance criteria

• useHandleUserStatus.ts has no sessionStorage, no offline listener, no try/catch and no console.info.
• ONLINE and OFFLINE use separate debounces, with SHOW_DELAY 5000 and HIDE_DELAY 3000. Each one cancels the other.
• Both effects depend on [enabled, userId], not on profile.
• A failed write logs Status write <status> failed once per failed write (browser check 4).
• In 5 of 5 in-window tab switches, the row reads OFFLINE for at most about 2 s (browser check 1).
• After a reload, the row reads ONLINE within 15 s and stays ONLINE (browser check 2).
• apps/webapp/CLAUDE.md:221 no longer lists "offline".
• The eslint and typecheck commands exit 0.

Out of scope

• The bell reader and the one lease rule. Make the chat bell use the online lease instead of the raw status flag #490 owns them.
• Admin Online Now and the Users badge. Make the chat bell use the online lease instead of the raw status flag #490 Decision 1 owns them.
• The online_at stamp and the one-time data fix. Stamp online_at only on ONLINE writes and clear users stuck ONLINE #489 owns them.
• Making heartbeats HOT. Make presence heartbeats HOT updates and drop the duplicate username index #491 owns it.
• The client presence rule (isFacePresent). Use one client presence rule so the @ picker agrees with the avatars #493 owns it.
• Removing the status pin at applySignedInProfile.ts:32. It needs a full trace of the self-profile readers. Measure workspace presence join fan-out before changing it #495 Out of scope notes the 11-key tracked object it feeds.
• A pagehide OFFLINE write. Mobile already leaves by the lease, and it would add tab-race writes.
• A heartbeat-only writer and a server Status writer. The review rejected both; see [Tracking] Stuck-Online users and the presence review follow-ups #496. Status is not a Hono route (apps/hocuspocus.server/CLAUDE.md:88).
• Idle detection for a visible tab. A visible but idle tab stays ONLINE, today and after Step 1.
• A per-user write floor on the server. It needs an RPC, because the client cannot read online_at after Stop exposing every user's online status and last-active time #434. Revisit at 1000x.

Generated by Claude Code