Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
66.1 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import type { Dispatch, SetStateAction } from 'react'
import { useAuthContext } from '@contexts/AuthContext'
import {
  useInfiniteQuery,
  useMutation,
  useQueries,
  useQuery,
  useQueryClient,
} from '@tanstack/react-query'
import { GFS_BREADCRUMB_MAX_DEPTH } from '@constants/gfsBrowser'
import { applyMoveConvergence } from '@lib/gfsEntityChangeState'
import {
  describeGfsReadError,
  isGfsSessionAuthorityFailure,
  isRateLimited,
  parseHttpStatus,
  parseRetryAfterSeconds,
} from '@lib/gfsGrantErrors'
import {
  type GfsOpenLocationRegistry,
  ancestryDependentGfsResourceIds,
  nextGfsOpenLocationId,
  publishGfsOpenLocation,
  readGfsOpenLocations,
} from '@lib/gfsOpenLocations'
import type {
  GfsGrantListItem,
  GfsInheritedAccessResult,
  GfsShareListItem,
} from '@/gfs/delegation.types'
import { deriveGfsInheritedAccess } from '@/gfs/inheritedAccess'
import { desktopQueryKeys } from './queryKeys'

/**
 * P4-S07 — Desktop Global File System browser controller (user plane).
 *
 * TanStack Query is the server-state source of truth (desktop-app/ui rule). The
 * browse is access-driven: the user first sees explicit resources granted or
 * shared with them, and can still open a `gfs://` URI manually. There is no
 * full-drive tree on the user plane — listing the whole drive is an operator
 * capability. Children are paginated with `useInfiniteQuery` so a large folder
 * is never silently truncated.
 *
 * Delegation (grant/share) and affordances flow through window.clerum.gfs, which
 * reaches control-api `/external/gfs/*` on the existing Session-JWT plane.
 * Enforcement (no-escalation) is always server-side; affordances only decide
 * which controls to SHOW.
 */

const DRIVE = 'main'
export const GFS_UNAVAILABLE_LOCATION_MESSAGE = 'This folder or file is no longer available.'

type GfsAccessState = 'active' | 'revoked'

export interface GfsBrowserChild {
  resourceId: string
  rid: string
  gfsUri: string
  drive: string
  parentResourceId: string | null
  name: string
  kind: 'file' | 'directory'
  path: string | null
  version: number
  bytes: number
  /**
   * Server-computed read decision for the listing caller. Absent on older
   * servers (treat as unknown); `false` means the row is visible but cannot
   * be opened or downloaded — a folder grant without inheritance.
   */
  readable?: boolean
}

interface GfsAccessibleResource extends GfsBrowserChild {
  sources: string[]
  permissions: string[]
  coversDescendants: boolean
}

type GfsAccessibleWirePage = Awaited<ReturnType<typeof window.clerum.gfs.listAccessible>>

function normalizeAccessibleResource(
  item: GfsAccessibleWirePage['items'][number]
): GfsAccessibleResource {
  return {
    ...item,
    drive: item.drive ?? 'main',
    parentResourceId: item.parentResourceId ?? null,
    sources: item.sources ?? [],
    permissions: item.permissions ?? [],
    coversDescendants: item.coversDescendants ?? false,
  }
}

type NavigableShareRow = {
  resourceId: string
  kind: 'file' | 'directory'
  path: string | null
  parentResourceId: string | null
}

/**
 * Virtual-root hygiene for the "Shared with me" surface. The server lists
 * EVERY resource carrying a direct grant — including files that live inside
 * folders the caller can already navigate into. Surfacing those twice (a
 * loose root item with no location, plus the real folder child) hides where
 * the file actually lives and invites acting on a different copy than
 * intended. Suppress a file from the virtual root when an accessible folder
 * covers it (path prefix, falling back to a direct parent match when the
 * server omits paths). Orphan shares — files whose location is NOT otherwise
 * reachable — stay listed; that is this surface's purpose. The filter only
 * sees already-loaded pages, so a folder on a later page suppresses its
 * files once that page loads.
 */
export function suppressNavigableShares<T extends NavigableShareRow>(rows: T[]): T[] {
  const folderPathPrefixes = new Set(
    rows
      .filter(
        (row): row is T & { path: string } =>
          row.kind === 'directory' && typeof row.path === 'string' && row.path.length > 1
      )
      .map(row => (row.path.endsWith('/') ? row.path : `${row.path}/`))
  )
  const folderIds = new Set(rows.filter(row => row.kind === 'directory').map(row => row.resourceId))
  return rows.filter(row => {
    if (row.kind !== 'file') return true
    if (typeof row.path === 'string' && row.path.length > 1) {
      for (const prefix of folderPathPrefixes) {
        if (row.path.startsWith(prefix)) return false
      }
    }
    return !(row.parentResourceId && folderIds.has(row.parentResourceId))
  })
}

export interface GfsCrumb {
  resourceId: string
  gfsUri: string
  name: string
  kind: 'file' | 'directory'
  version: number
  bytes: number
}

export interface GfsBrowserAffordances {
  held: string[]
  canDelegate: boolean
  grantableBits: string[]
  canCreateShare: boolean
}

export interface GfsBrowserControllerOptions {
  /**
   * Enables the grants listing for the current resource. The Manage dialog is
   * the only consumer, so the query runs only while it is open.
   */
  grantsListEnabled?: boolean
}

function toMessage(error: unknown): string {
  return error instanceof Error ? error.message : String(error)
}

/**
 * Present a read-plane failure as the verdict a user can act on.
 *
 * `toMessage` returns the RAW `Error.message`, which still carries Electron's
 * `Error invoking remote method '<channel>': ` wrapper — the name of our own
 * main/renderer split, which means nothing to a user — and spells a 429 as a
 * bare status line rather than as "too many file requests".
 *
 * Only fields that feed a BANNER are presented here. Fields that feed a
 * CLASSIFIER stay raw on purpose: `accessibleError` is read by
 * `classifyDiscoveryFailure`, and `error` by the folder failure card, both of
 * which match status tokens and the `retryAfterSeconds=` suffix that this
 * mapping deliberately replaces with prose.
 */
function toPresentedMessage(error: unknown): string {
  return describeGfsReadError(error).message
}

export type GfsDiscoveryFailureKind = 'unsupported' | 'rate-limited' | 'failed'

export interface GfsDiscoveryFailure {
  kind: GfsDiscoveryFailureKind
  message: string
  /**
   * Absolute epoch (ms) at which the server's own window closes, or null when
   * this failure named no window.
   *
   * An absolute deadline, not a duration, and derived from the query's
   * `errorUpdatedAt` rather than from the message. Two consecutive 429s carry a
   * byte-identical message — the server keeps refusing with the same words —
   * so anything memoized on the message alone returns the SAME object, and
   * every effect keyed on it stays silent for the second failure. The pause
   * would then never re-arm after a retry, which is the hammering this
   * controller exists to prevent. `errorUpdatedAt` advances on every settled
   * error, identical message or not.
   *
   * A deadline also survives a remount and cannot drift: a consumer counting
   * down derives the remainder from the clock instead of decrementing state.
   *
   * The parsed duration itself is deliberately NOT carried alongside. It was,
   * and no consumer ever read it — every surface counts down from this
   * deadline — so the seam published a second, redundant spelling of the same
   * fact that nothing validated against the first. A future consumer reaching
   * for it would have trusted a number no test covered.
   */
  retryAvailableAt: number | null
}

/**
 * Classify a discovery rejection by a signal we actually produce, never by the
 * IPC wording. Electron's `ipcRenderer.invoke` always prefixes a rejection with
 * `Error invoking remote method 'gfs:listAccessible'`, so matching that
 * substring classified EVERY failure of the call — a 429 included — as "this
 * server does not support discovery".
 *
 * `404 Not Found` is our own httpClient format, so it still identifies a server
 * that predates the endpoint. The preload-absent case is not handled here: it
 * has no error to classify and stays on the `canListAccessibleResources` branch.
 *
 * Delimited on both sides for the same reason `isRateLimited` is, and with the
 * same delimiter set: `\b` counts `-` and `/` as boundaries, so a failure whose
 * body merely QUOTED the phrase — a path like `/docs/404 Not Found.md`, which
 * `httpClient` copies verbatim into the message when the JSON carries no
 * top-level `error`/`message` — was classified as a server that has no
 * discovery endpoint. That verdict is the one with no way back: `unsupported`
 * offers no retry, so the user is told their files cannot be listed by a
 * server that would have answered.
 *
 * Every shape the wire produces delimits the status the same way
 * (`404 Not Found: <body>`, and through IPC `…: Error: 404 Not Found: …`), so
 * requiring the delimiter loses no real detection.
 *
 * The vetted status outranks both patterns when the main process supplied one.
 * `unsupported` is the verdict with no way back, and prose is a poor thing to
 * reach it on: a 500 whose body quotes `404 Not Found` from an upstream hop is
 * a server that is failing, not one that lacks the endpoint. `ApiError.status`
 * says which, and it arrives here as `httpStatus=…`.
 */
function classifyDiscoveryFailure(message: string): GfsDiscoveryFailureKind {
  const status = parseHttpStatus(message)
  if (status !== null) {
    if (status === 404) return 'unsupported'
    return isRateLimited(message) ? 'rate-limited' : 'failed'
  }
  if (/(?:^|[\s:])404 Not Found(?=[\s:]|$)/.test(message)) return 'unsupported'
  // Share the predicate with the presentation layer rather than restating it.
  // A third copy of "what counts as rate limited" is a copy that will rot, and
  // the two must agree: the card renders copy chosen by `describeGfsReadError`
  // for a failure this function classified.
  if (isRateLimited(message)) return 'rate-limited'
  return 'failed'
}

/**
 * Focus-refetch pause applied when the server rate limited us without naming a
 * window.
 *
 * The manual Retry button stays enabled — spending the user's own click is
 * their decision, and the card tells them to "try again shortly". What this
 * suppresses is the automatic revalidation on every window focus, which would
 * otherwise keep drawing on a budget the server is still refusing. The case is
 * reachable: an upstream proxy or CDN answers 429 with its own body, which
 * carries no `retryAfterSeconds` for us to parse.
 *
 * One minute is the window of the per-minute limiters behind this endpoint.
 */
const UNKNOWN_RATE_LIMIT_PAUSE_MS = 60_000

export { isGfsSessionAuthorityFailure } from '@lib/gfsGrantErrors'

export function useGfsBrowserController(options: GfsBrowserControllerOptions = {}) {
  const { grantsListEnabled = false } = options
  const queryClient = useQueryClient()
  const { isAuthenticated, me, runtimeConfigState } = useAuthContext()
  const [crumbs, setCrumbsState] = useState<GfsCrumb[]>([])
  const [openError, setOpenError] = useState<string | null>(null)
  const [resolving, setResolving] = useState(false)
  const openUriGenerationRef = useRef(0)
  const foregroundOpenUriPendingRef = useRef<number | null>(null)
  const backgroundOpenUriGenerationRef = useRef(0)
  const backgroundOpenErrorRef = useRef(false)
  const pendingDeniedResourceIdRef = useRef<string | null>(null)
  const backgroundLocationRetryRef = useRef<(uri: string) => void>(() => undefined)
  const backgroundLocationRetryTimerRef = useRef<number | null>(null)
  const backgroundLocationRetryAttemptRef = useRef(0)
  // Any browser-location update supersedes an in-flight URI resolution. This
  // includes navigation through the tree/crumbs as well as metadata updates,
  // so an older refresh (including a late 403/404) cannot overwrite a newer
  // location or clear its state.
  const setCrumbs = useCallback<Dispatch<SetStateAction<GfsCrumb[]>>>(next => {
    openUriGenerationRef.current += 1
    foregroundOpenUriPendingRef.current = null
    setResolving(false)
    setCrumbsState(next)
  }, [])
  const previousSessionScopeRef = useRef<string | null>(null)
  // Per controller-mount timestamp: discovery (`refetchOnMount: 'always'`) must
  // land a response newer than this before cached GFS state may render again.
  // Between mount and that fresh response the browser withholds cached rows
  // (authority revalidation window — R4 spec §1).
  const authorityEpochRef = useRef(Date.now())

  const current = crumbs.length ? crumbs[crumbs.length - 1] : null
  const currentCrumbRef = useRef<GfsCrumb | null>(current)
  currentCrumbRef.current = current
  const currentIsDirectory = current?.kind === 'directory'
  // Scope gfs cache/crumbs by environment too (spec §5.2): the same user/team
  // pair addresses different resources across clusters, so an env switch must
  // reset the browser + drop the gfs query subtree.
  const envKey = runtimeConfigState?.envKey ?? ''
  const sessionScope = useMemo(
    () => (isAuthenticated && me ? `${envKey}:${me.id}:${me.teamId ?? ''}` : null),
    [envKey, isAuthenticated, me]
  )
  const canListAccessibleResources = typeof window.clerum?.gfs?.listAccessible === 'function'

  // Session-authority access state, SHARED across every controller mount (the
  // sidebar tree, FilesPage, FilePreviewPage each mount their own controller).
  // A server authorization failure must never leave cached GFS metadata visible
  // — production defaults keep data for 30 minutes without revalidation, so the
  // only safe response is to drop it all and gate the queries off. That decision
  // has to be observed by EVERY mount: a 401 in one surface must revoke the
  // others, and a retry in one must re-enable them. It therefore lives in the
  // query cache (a pure subscription here; never fetches — writes go through
  // `setAccessState`), keyed by sessionScope and OUTSIDE `gfsRoot` so the
  // fail-closed purge below does not clear the flag it just set. `gcTime:
  // Infinity` keeps the revoked decision alive across a gap with no mounts, so a
  // later mount still fails closed; only retryAccess (a server round-trip) or a
  // session-scope change returns to 'active'.
  const accessStateQuery = useQuery({
    queryKey: desktopQueryKeys.gfsAccessState(sessionScope ?? 'anonymous'),
    queryFn: () => 'active' as GfsAccessState,
    enabled: false,
    initialData: 'active' as GfsAccessState,
    gcTime: Infinity,
    staleTime: Infinity,
  })
  const accessState: GfsAccessState = accessStateQuery.data ?? 'active'
  const setAccessState = useCallback(
    (next: GfsAccessState) => {
      queryClient.setQueryData(desktopQueryKeys.gfsAccessState(sessionScope ?? 'anonymous'), next)
    },
    [queryClient, sessionScope]
  )

  // The open location is CLIENT state, not server state: it records which
  // resource this mount has open and the ancestry this mount observed. It is
  // published through the query cache so EVERY mount sees it — a move
  // committed by the sidebar must be able to tell that it changes what the
  // Files page's open Share/Manage dialog inherits (RP-005).
  //
  // The subscription exists only to keep the cache entry alive: an
  // unobserved entry is garbage-collected while the app is idle, and the
  // registry would silently empty itself. `notifyOnChangeProps: []` keeps
  // another mount's publish from re-rendering this one — the registry is
  // read imperatively, never rendered.
  useQuery({
    queryKey: desktopQueryKeys.gfsOpenLocations(sessionScope ?? 'anonymous'),
    queryFn: async () => ({}) as GfsOpenLocationRegistry,
    enabled: false,
    initialData: {} as GfsOpenLocationRegistry,
    gcTime: Infinity,
    staleTime: Infinity,
    notifyOnChangeProps: [],
  })
  // One identity per controller mount: the registry holds an entry per
  // mount, and a mount that navigates replaces only its own entry.
  const openLocationIdRef = useRef<string | null>(null)
  if (openLocationIdRef.current === null) openLocationIdRef.current = nextGfsOpenLocationId()
  const openLocationId = openLocationIdRef.current
  useEffect(() => {
    if (!sessionScope) return
    // The ancestry this mount observed is the trail it loaded. Crumbs are
    // ROOT-FIRST, so publishing them reverses them into the registry's
    // NEAREST-FIRST contract — the order the relocation helper slices from
    // the nearest end. A revoked session has no open location to claim.
    const location =
      accessState === 'active' && current
        ? {
            resourceId: current.resourceId,
            ancestorResourceIds: crumbs
              .slice(0, -1)
              .map(crumb => crumb.resourceId)
              .reverse(),
          }
        : null
    publishGfsOpenLocation(queryClient, sessionScope, openLocationId, location)
    return () => {
      publishGfsOpenLocation(queryClient, sessionScope, openLocationId, null)
    }
  }, [accessState, crumbs, current?.resourceId, openLocationId, queryClient, sessionScope])

  useEffect(() => {
    const previous = previousSessionScopeRef.current
    if (previous === sessionScope) return
    previousSessionScopeRef.current = sessionScope
    if (previous !== null) {
      setCrumbs([])
      setOpenError(null)
      setAccessState('active')
      void queryClient.removeQueries({ queryKey: desktopQueryKeys.gfsRoot })
    }
  }, [queryClient, sessionScope, setAccessState])

  // Epoch (ms) before which a focus-driven revalidation would only burn
  // another slice of the rate-limit budget the server just refused. A ref,
  // not state: the refetch predicates read it when focus fires, and mutating
  // it must not re-render. 0 means "not paused".
  const pausedUntilRef = useRef(0)
  // TanStack 5 accepts `(query) => boolean | 'always'` here. It must return
  // 'always' | false, never a boolean: `true` means "refetch if stale", and
  // under desktopQueryDefaults' staleTime of Infinity a query that HOLDS DATA
  // never is — so `true` would drop the focus revalidation this option exists
  // for, which is picking up grants made from another surface. (It is not that
  // staleness is impossible under Infinity: `isStaleByTime` short-circuits to
  // true when `data === undefined` or the query was invalidated, both
  // reachable here. `'always'` is unconditional, which is what we want when
  // not paused.)
  const refetchOnFocusUnlessPaused = useCallback(
    (): 'always' | false => (Date.now() >= pausedUntilRef.current ? 'always' : false),
    []
  )

  const accessibleQuery = useInfiniteQuery({
    queryKey: desktopQueryKeys.gfsAccessible(sessionScope ?? 'anonymous', DRIVE),
    queryFn: async ({ pageParam }): Promise<GfsAccessibleWirePage> => {
      const listAccessible = window.clerum?.gfs?.listAccessible
      if (typeof listAccessible !== 'function') {
        return { items: [], nextCursor: null }
      }
      return listAccessible(DRIVE, pageParam)
    },
    enabled: Boolean(sessionScope) && canListAccessibleResources && accessState === 'active',
    // Accessible resources are permission-derived state. Another session can
    // revoke a grant/share while this user is away from Files, so an
    // Infinity-cached list must not survive a Files remount without a server
    // check — even though the app-level client defaults disable refetching.
    refetchOnMount: 'always',
    // Grants are often made from another surface (control-ui, an operator,
    // another user) while this window stays open; focusing the app must
    // surface the new shares without a hard reload — unless the server just
    // rate limited us, in which case focusing again only costs another 429.
    refetchOnWindowFocus: refetchOnFocusUnlessPaused,
    initialPageParam: undefined as string | undefined,
    getNextPageParam: lastPage => lastPage.nextCursor ?? undefined,
  })

  // Authority revalidation window (R4 spec §1): true from mount/session-return
  // until discovery lands a response NEWER than this mount. While true, every
  // cached GFS surface this controller exposes is withheld so prefetched or
  // 30-minute-cached state cannot render before the session is re-proved. If
  // discovery fails with an authority error, the query-error boundary revokes
  // (which clears the same caches); a policy error stays a local banner. When
  // the runtime has no discovery, there is nothing to revalidate against and
  // per-resource operations still fail closed through handleAuthorityFailure.
  const authorityPending =
    Boolean(sessionScope) &&
    canListAccessibleResources &&
    accessState === 'active' &&
    accessibleQuery.dataUpdatedAt < authorityEpochRef.current

  const childrenQuery = useInfiniteQuery({
    queryKey: desktopQueryKeys.gfsChildren(
      sessionScope ?? 'anonymous',
      current?.resourceId ?? '',
      DRIVE
    ),
    queryFn: ({ pageParam }) =>
      window.clerum.gfs.listChildren(current!.resourceId, DRIVE, pageParam),
    enabled:
      Boolean(sessionScope) && Boolean(current) && currentIsDirectory && accessState === 'active',
    // Folder contents change out-of-band: agents with host grants, other
    // sessions, and operator writes never pass through this client. Revisit
    // and window focus must revalidate — an Infinity-fresh cached listing
    // otherwise hides new files until a hard app reload.
    refetchOnMount: 'always',
    refetchOnWindowFocus: refetchOnFocusUnlessPaused,
    initialPageParam: undefined as string | undefined,
    getNextPageParam: lastPage => lastPage.nextCursor ?? undefined,
  })

  const affordancesQuery = useQuery({
    queryKey: desktopQueryKeys.gfsAffordances(
      sessionScope ?? 'anonymous',
      current?.resourceId ?? '',
      DRIVE
    ),
    queryFn: () => window.clerum.gfs.affordances(current!.resourceId, DRIVE),
    enabled: Boolean(sessionScope) && Boolean(current) && accessState === 'active',
  })
  const refreshAffordances = useCallback(async () => {
    const resourceId = current?.resourceId
    if (!sessionScope || !resourceId) return
    await queryClient.invalidateQueries({
      exact: true,
      queryKey: desktopQueryKeys.gfsAffordances(sessionScope, resourceId, DRIVE),
      refetchType: 'active',
    })
  }, [current?.resourceId, queryClient, sessionScope])

  /**
   * Row-level affordances for the one resource whose ⋯ menu is open. Children
   * listings carry no permission bits, so the Files page lazily resolves the
   * delete gate per menu instead of per row. Shares the affordances cache with
   * the Manage dialog, so opening Manage for the same resource is free.
   */
  const [rowAffordancesResourceId, setRowAffordancesResourceId] = useState<string | null>(null)
  const rowAffordancesQuery = useQuery({
    queryKey: desktopQueryKeys.gfsAffordances(
      sessionScope ?? 'anonymous',
      rowAffordancesResourceId ?? '',
      DRIVE
    ),
    queryFn: () => window.clerum.gfs.affordances(rowAffordancesResourceId!, DRIVE),
    enabled: Boolean(sessionScope) && Boolean(rowAffordancesResourceId) && accessState === 'active',
  })
  // The grants listing is the revoke-id source (the grant PUT returns no ids),
  // so writes must refetch it. Enabled only while the Manage dialog is open.
  const grantsQuery = useQuery({
    queryKey: desktopQueryKeys.gfsGrants(
      sessionScope ?? 'anonymous',
      current?.resourceId ?? '',
      DRIVE
    ),
    queryFn: () => window.clerum.gfs.listGrants(current!.resourceId, DRIVE),
    enabled:
      Boolean(sessionScope) && Boolean(current) && grantsListEnabled && accessState === 'active',
  })
  // Direct URI shares are a separate server surface ("this route is never
  // inferred from grants"), so the revoke-id source for shares is this list.
  // Shares the Manage-dialog gating with grants.
  const sharesQuery = useQuery({
    queryKey: desktopQueryKeys.gfsShares(
      sessionScope ?? 'anonymous',
      current?.resourceId ?? '',
      DRIVE
    ),
    queryFn: () => window.clerum.gfs.listShares(current!.resourceId, DRIVE),
    enabled:
      Boolean(sessionScope) && Boolean(current) && grantsListEnabled && accessState === 'active',
  })
  // Inherited access (ancestor folders' inheriting grants/shares) is derived
  // client-side because the grants/shares GETs list only direct rows. FILES
  // AND FOLDERS consume the derivation (the walk is kind-agnostic). A stop is
  // reported as coverage (R1-H3): rows folded before the stop are retained
  // with `inheritedCoverage` telling the dialog which notice to show; only a
  // raw session 401 (or a throw the walk cannot classify) reaches
  // `inheritedAccessError`. Gated to the Manage dialog like the direct
  // listings.
  const inheritedAccessQuery = useQuery({
    queryKey: desktopQueryKeys.gfsInheritedAccess(
      sessionScope ?? 'anonymous',
      current?.resourceId ?? '',
      DRIVE
    ),
    queryFn: () => deriveGfsInheritedAccess(current!.resourceId, DRIVE),
    enabled:
      Boolean(sessionScope) && Boolean(current) && grantsListEnabled && accessState === 'active',
    // An 'unavailable' coverage is a FAILED walk, not an observation: a
    // transient ancestor failure would otherwise be cached forever under the
    // app's Infinity staleTime and reopening Share would keep showing the
    // failure as if it were authoritative. Such a result stays stale, so
    // reopening the dialog retries the walk. A complete observation keeps
    // the app's normal policy (cached until something invalidates it).
    staleTime: query =>
      (query.state.data as GfsInheritedAccessResult | undefined)?.coverage === 'unavailable'
        ? 0
        : Infinity,
  })
  const refreshShares = useCallback(async () => {
    const resourceId = current?.resourceId
    if (!resourceId) return
    await queryClient.invalidateQueries({
      exact: true,
      queryKey: desktopQueryKeys.gfsShares(sessionScope ?? 'anonymous', resourceId, DRIVE),
    })
  }, [current?.resourceId, queryClient, sessionScope])
  const refreshGrants = useCallback(async () => {
    const resourceId = current?.resourceId
    if (!resourceId) return
    await queryClient.invalidateQueries({
      exact: true,
      queryKey: desktopQueryKeys.gfsGrants(sessionScope ?? 'anonymous', resourceId, DRIVE),
    })
  }, [current?.resourceId, queryClient, sessionScope])
  // Re-derives inherited access after a confirmed parent-folder edit changed
  // the ancestor rows the walk collected.
  const refreshInheritedAccess = useCallback(async () => {
    const resourceId = current?.resourceId
    if (!resourceId) return
    await queryClient.invalidateQueries({
      exact: true,
      queryKey: desktopQueryKeys.gfsInheritedAccess(sessionScope ?? 'anonymous', resourceId, DRIVE),
    })
  }, [current?.resourceId, queryClient, sessionScope])
  const refreshGfs = useCallback(async () => {
    await queryClient.invalidateQueries({
      queryKey: desktopQueryKeys.gfsRoot,
      // Content mutations refresh discovery and folder listings. Permission
      // affordances are refreshed explicitly when Manage opens; coupling them
      // here temporarily removes write controls between consecutive uploads.
      predicate: query => query.queryKey[3] !== 'affordances',
    })
  }, [queryClient])
  /**
   * Fail closed on a session/authorization failure: cached GFS metadata can
   * never outlive the access that produced it. Clears navigation and removes
   * every cached GFS response for this Desktop session (listings, roots,
   * affordances, grants, shares). The `accessState` gate disables the query
   * observers until an explicit retry re-enters through the server.
   */
  const clearGfsState = useCallback(() => {
    setCrumbs([])
    setOpenError(null)
    queryClient.removeQueries({ queryKey: desktopQueryKeys.gfsRoot })
  }, [queryClient])
  const clearInaccessibleGfsLocation = useCallback(() => {
    const resourceId = currentCrumbRef.current?.resourceId
    pendingDeniedResourceIdRef.current = resourceId ?? null
    // A resource-scoped denial is not loss of the authenticated session.
    // Keep accessible roots and other GFS scopes intact, and avoid the
    // foreground navigation setter so a background denial cannot advance it.
    setCrumbsState([])
    setOpenError(GFS_UNAVAILABLE_LOCATION_MESSAGE)
  }, [])
  useEffect(() => {
    const resourceId = pendingDeniedResourceIdRef.current
    if (!resourceId || current?.resourceId === resourceId) return
    pendingDeniedResourceIdRef.current = null
    if (!sessionScope) return
    // Remove the denied query after its observer has left the current folder;
    // removing an active infinite query can transiently expose an empty page.
    queryClient.removeQueries({
      exact: true,
      queryKey: desktopQueryKeys.gfsChildren(sessionScope, resourceId, DRIVE),
    })
  }, [current?.resourceId, queryClient, sessionScope])
  const revokeAccess = useCallback(() => {
    setAccessState('revoked')
    clearGfsState()
  }, [clearGfsState, setAccessState])
  const retryAccess = useCallback(() => {
    // This restores no local capability; it only re-enables the queries so a
    // server-side re-grant (or a fresh sign-in) is the sole way back in. Because
    // the flag is shared, a retry here re-activates every mounted controller.
    setAccessState('active')
  }, [setAccessState])
  /** For imperative flows (openUri, revoke mutations): fail closed on a
   * session-authority rejection; returns true when it did. */
  const handleAuthorityFailure = useCallback(
    (message: string, surface: 'discovery' | 'operation' = 'operation'): boolean => {
      if (!isGfsSessionAuthorityFailure(message, surface)) return false
      revokeAccess()
      return true
    },
    [revokeAccess]
  )
  const scheduleBackgroundLocationRetry = useCallback((uri: string, error: unknown) => {
    const message = toMessage(error)
    const status = parseHttpStatus(message)
    if (status !== null && status !== 429 && status < 500) return
    if (backgroundLocationRetryTimerRef.current !== null) return
    const attempt = backgroundLocationRetryAttemptRef.current + 1
    backgroundLocationRetryAttemptRef.current = attempt
    const retryAfterSeconds = parseRetryAfterSeconds(message)
    const delayMs = retryAfterSeconds
      ? Math.min(retryAfterSeconds * 1000, 60_000)
      : Math.min(500 * 2 ** Math.min(attempt - 1, 4), 8_000)
    backgroundLocationRetryTimerRef.current = window.setTimeout(() => {
      backgroundLocationRetryTimerRef.current = null
      backgroundLocationRetryRef.current(uri)
    }, delayMs)
  }, [])
  // All GFS mutations share the central fail-closed boundary: an authority
  // rejection (401 / typed lifecycle code) revokes the session even when the
  // caller would only have toasted. Policy verdicts (403/412) stay local.
  const failClosedOnMutationError = useCallback(
    (error: unknown) => {
      handleAuthorityFailure(toMessage(error), 'operation')
    },
    [handleAuthorityFailure]
  )
  const revokeGrantMutation = useMutation({
    mutationFn: (grantId: string) => window.clerum.gfs.revokeGrant(grantId),
    onSuccess: refreshGrants,
    onError: failClosedOnMutationError,
  })
  const revokeShareMutation = useMutation({
    mutationFn: (shareId: string) => window.clerum.gfs.revokeShare(shareId),
    onSuccess: refreshShares,
    onError: failClosedOnMutationError,
  })
  const createFolderMutation = useMutation({
    mutationFn: async (name: string) => {
      if (!current) throw new Error('No folder selected')
      return window.clerum.gfs.createFolder(current.resourceId, name, DRIVE)
    },
    onSuccess: refreshGfs,
    onError: failClosedOnMutationError,
  })
  const createFileMutation = useMutation({
    mutationFn: (input: { parentResourceId: string; name: string; encodedData: string }) =>
      window.clerum.gfs.createFile(input.parentResourceId, input.name, input.encodedData, DRIVE),
    onSuccess: refreshGfs,
    onError: failClosedOnMutationError,
  })
  const createFileFromPathMutation = useMutation({
    mutationFn: (input: { parentResourceId: string; name: string; filePath: string }) =>
      window.clerum.gfs.createFileFromPath(
        input.parentResourceId,
        input.name,
        input.filePath,
        DRIVE
      ),
    onSuccess: refreshGfs,
    onError: failClosedOnMutationError,
  })
  const replaceFileMutation = useMutation({
    mutationFn: (input: { resourceId: string; encodedData: string; ifMatch?: number }) =>
      window.clerum.gfs.replaceFile(input.resourceId, input.encodedData, DRIVE, input.ifMatch),
    onSuccess: async resource => {
      setCrumbs(prev =>
        prev.map(crumb =>
          crumb.resourceId === resource.resourceId
            ? { ...crumb, name: resource.name, version: resource.version }
            : crumb
        )
      )
      await refreshGfs()
    },
    onError: failClosedOnMutationError,
  })
  const replaceFileFromPathMutation = useMutation({
    mutationFn: (input: { resourceId: string; filePath: string; ifMatch?: number }) =>
      window.clerum.gfs.replaceFileFromPath(input.resourceId, input.filePath, DRIVE, input.ifMatch),
    onSuccess: async (receipt, input) => {
      if (receipt.resultVersion !== undefined) {
        setCrumbs(prev =>
          prev.map(crumb =>
            crumb.resourceId === input.resourceId
              ? { ...crumb, version: receipt.resultVersion! }
              : crumb
          )
        )
      }
      await refreshGfs()
    },
    onError: failClosedOnMutationError,
  })
  const renameResourceMutation = useMutation({
    mutationFn: (input: { resourceId: string; name: string; ifMatch?: number }) =>
      window.clerum.gfs.renameResource(input.resourceId, input.name, DRIVE, input.ifMatch),
    onSuccess: async (resource, input) => {
      setCrumbs(prev =>
        prev.map(crumb =>
          crumb.resourceId === input.resourceId
            ? { ...crumb, name: input.name, version: resource.version }
            : crumb
        )
      )
      await refreshGfs()
    },
    onError: failClosedOnMutationError,
  })
  const deleteResourceMutation = useMutation({
    mutationFn: (input: { resourceId: string; ifMatch?: number }) =>
      window.clerum.gfs.deleteResource(input.resourceId, DRIVE, input.ifMatch),
    onSuccess: async (_data, input) => {
      setCrumbs(prev => prev.filter(crumb => crumb.resourceId !== input.resourceId))
      await refreshGfs()
    },
    onError: failClosedOnMutationError,
  })

  // Cached GFS state is a rendering optimization only (R4 spec §1): while the
  // authority revalidation window is open, nothing cached may be exposed —
  // affordances, grants, and shares all stay withheld until discovery
  // re-proves the session (or an authority failure clears everything).
  //
  // Children are the one surface that clears the gate on its own evidence. The
  // window exists to keep PREFETCHED or 30-minute-cached state from rendering
  // before the session is re-proved, and a page fetched after this mount's
  // epoch is neither: it is a fresh server read the current principal was
  // authorized for. Withholding it renders "This folder is empty", which is
  // the one thing that successful listing disproves — the same false statement
  // this controller stopped making about a refused discovery. Row affordances
  // stay behind `authorityPending` regardless, so the rows arrive without
  // per-row actions until discovery lands.
  const childrenFetchedThisEpoch = childrenQuery.dataUpdatedAt >= authorityEpochRef.current
  const items = useMemo<GfsBrowserChild[]>(
    () =>
      authorityPending && !childrenFetchedThisEpoch
        ? []
        : (childrenQuery.data?.pages ?? []).flatMap(page => page.items),
    [authorityPending, childrenFetchedThisEpoch, childrenQuery.data]
  )
  /**
   * Children listings deliberately contain no permission bits. Resolve the
   * caller's affordances for every visible child so row-level Share, Rename,
   * and Delete controls are consistent across files and folders instead of
   * only appearing after that row's overflow menu has been opened.
   *
   * The query keys are shared with the selected-row observer above. That keeps
   * the overflow menu and Manage dialog on the same cache entry while the
   * per-row queries remain fail-closed until their own server verdict arrives.
   */
  const rowAffordancesQueries = useQueries({
    queries: items.map(item => ({
      queryKey: desktopQueryKeys.gfsAffordances(
        sessionScope ?? 'anonymous',
        item.resourceId,
        DRIVE
      ),
      queryFn: () => window.clerum.gfs.affordances(item.resourceId, DRIVE),
      enabled:
        Boolean(sessionScope) &&
        Boolean(current) &&
        currentIsDirectory &&
        !authorityPending &&
        accessState === 'active',
      // Permission changes made outside this page must not leave row actions
      // stale when a folder is revisited — but `'always'` paid for that with a
      // refetch per visible child on EVERY mount, against data the project
      // default keeps fresh forever (`staleTime: Infinity`). Re-entering a
      // 45-child folder seconds later spent 40 requests to re-derive bits the
      // cache already held, which was 47% of the affordances traffic in the
      // incident behind #681.
      //
      // A 60s bound keeps the out-of-band case working and makes the re-entry
      // free. The cost is that a row's permission bits may be up to 60s stale
      // after a change made elsewhere; server-side enforcement is unchanged, so
      // a stale row action still gets the 403 this page already handles. The
      // menu-level affordances query above serves Infinity-cached bits today,
      // so this is tighter than the status quo beside it, not looser.
      refetchOnMount: true as const,
      staleTime: 60_000,
    })),
  })
  const rowAffordancesByResourceId = useMemo(() => {
    const byResourceId: Record<string, GfsBrowserAffordances> = {}
    if (authorityPending || accessState === 'revoked') return byResourceId
    items.forEach((item, index) => {
      const data = rowAffordancesQueries[index]?.data
      if (data) byResourceId[item.resourceId] = data as GfsBrowserAffordances
    })
    return byResourceId
  }, [accessState, authorityPending, items, rowAffordancesQueries])
  // Query-surfaced authorization failures (a refetch after revocation is the
  // normal way the loss is discovered under Infinity staleTime). Discovery is
  // the session/authority boundary; per-resource verdicts stay local.
  const queryAuthorizationError = [
    accessibleQuery.error
      ? { message: toMessage(accessibleQuery.error), surface: 'discovery' as const }
      : null,
    childrenQuery.error
      ? { message: toMessage(childrenQuery.error), surface: 'operation' as const }
      : null,
    affordancesQuery.error
      ? { message: toMessage(affordancesQuery.error), surface: 'operation' as const }
      : null,
    rowAffordancesQuery.error
      ? { message: toMessage(rowAffordancesQuery.error), surface: 'operation' as const }
      : null,
    ...rowAffordancesQueries.map(query =>
      query.error ? { message: toMessage(query.error), surface: 'operation' as const } : null
    ),
    grantsQuery.error
      ? { message: toMessage(grantsQuery.error), surface: 'operation' as const }
      : null,
    sharesQuery.error
      ? { message: toMessage(sharesQuery.error), surface: 'operation' as const }
      : null,
    inheritedAccessQuery.error
      ? { message: toMessage(inheritedAccessQuery.error), surface: 'operation' as const }
      : null,
  ]
    .filter(
      (entry): entry is { message: string; surface: 'discovery' | 'operation' } => entry !== null
    )
    .find(entry => isGfsSessionAuthorityFailure(entry.message, entry.surface))
  useEffect(() => {
    if (!queryAuthorizationError || accessState === 'revoked') return
    revokeAccess()
  }, [accessState, queryAuthorizationError, revokeAccess])
  const currentFolderUnavailable =
    currentIsDirectory &&
    childrenQuery.error !== null &&
    [403, 404].includes(parseHttpStatus(toMessage(childrenQuery.error)) ?? 0)
  useEffect(() => {
    if (!currentFolderUnavailable) return
    // A soft scope invalidation preserves rows while the authoritative read is
    // pending. Once that read proves this open folder is denied or gone, none
    // of its cached descendants may remain visible in this browser session.
    clearInaccessibleGfsLocation()
  }, [clearInaccessibleGfsLocation, currentFolderUnavailable])
  const accessibleResources = useMemo<GfsAccessibleResource[]>(
    () =>
      authorityPending
        ? []
        : suppressNavigableShares(
            (accessibleQuery.data?.pages ?? []).flatMap(page =>
              page.items.map(normalizeAccessibleResource)
            )
          ),
    [accessibleQuery.data, authorityPending]
  )
  const grants = useMemo<GfsGrantListItem[]>(
    () => (authorityPending ? [] : (grantsQuery.data ?? [])),
    [authorityPending, grantsQuery.data]
  )
  const shares = useMemo<GfsShareListItem[]>(
    () => (authorityPending ? [] : (sharesQuery.data ?? [])),
    [authorityPending, sharesQuery.data]
  )
  const inheritedAccess = useMemo(
    () =>
      authorityPending || accessState === 'revoked' ? [] : (inheritedAccessQuery.data?.items ?? []),
    [accessState, authorityPending, inheritedAccessQuery.data]
  )
  // R1-H3: coverage of the walk that produced `inheritedAccess` (null while
  // never loaded). The scope/revoked guard above intentionally does NOT apply:
  // coverage describes the observation, and a revoked session empties the
  // rows through that guard instead.
  const inheritedCoverage = inheritedAccessQuery.data?.coverage ?? null
  const accessibleErrorMessage = accessibleQuery.error ? toMessage(accessibleQuery.error) : null
  // The timestamp is a dependency in its own right, not decoration. It is the
  // only thing that distinguishes two consecutive failures carrying the same
  // message, and without it the memo below never recomputes for the second one.
  const accessibleErrorUpdatedAt = accessibleQuery.error ? accessibleQuery.errorUpdatedAt : 0
  const childrenErrorMessage = childrenQuery.error ? toMessage(childrenQuery.error) : null
  const childrenErrorUpdatedAt = childrenQuery.error ? childrenQuery.errorUpdatedAt : 0
  const discoveryFailure = useMemo<GfsDiscoveryFailure | null>(() => {
    if (!accessibleErrorMessage) return null
    const kind = classifyDiscoveryFailure(accessibleErrorMessage)
    const retryAfterSeconds = parseRetryAfterSeconds(accessibleErrorMessage)
    return {
      kind,
      message: accessibleErrorMessage,
      retryAvailableAt:
        kind === 'rate-limited' && retryAfterSeconds !== null
          ? accessibleErrorUpdatedAt + retryAfterSeconds * 1000
          : null,
    }
  }, [accessibleErrorMessage, accessibleErrorUpdatedAt])
  // The folder plane's own rate-limit deadline. `listAccessible` and
  // `listChildren` are refused by ONE server budget, so a 429 on either means
  // the next focus-driven refetch of either spends a request the server just
  // turned down. Derived here rather than inside the effect below because the
  // timestamp is what separates two consecutive refusals carrying the same
  // message — without it the second one never recomputes.
  const childrenRateLimitedUntil = useMemo<number | null>(() => {
    if (!childrenErrorMessage || !isRateLimited(childrenErrorMessage)) return null
    const retryAfterSeconds = parseRetryAfterSeconds(childrenErrorMessage)
    return retryAfterSeconds !== null
      ? childrenErrorUpdatedAt + retryAfterSeconds * 1000
      : Date.now() + UNKNOWN_RATE_LIMIT_PAUSE_MS
  }, [childrenErrorMessage, childrenErrorUpdatedAt])
  useEffect(() => {
    // A rate limit with no parseable window is still a rate limit. Leaving the
    // pause open here would let every window focus spend another request
    // against a server that just refused one.
    const discoveryUntil =
      discoveryFailure?.kind === 'rate-limited'
        ? (discoveryFailure.retryAvailableAt ?? Date.now() + UNKNOWN_RATE_LIMIT_PAUSE_MS)
        : 0
    // The later of the two deadlines, never whichever one settled last. A
    // discovery refetch that succeeds does not buy back the budget a refused
    // folder listing is still waiting on, and arming from discovery alone left
    // a folder 429 free to be re-spent on the very next window focus.
    pausedUntilRef.current = Math.max(discoveryUntil, childrenRateLimitedUntil ?? 0)
  }, [childrenRateLimitedUntil, discoveryFailure])
  // The page must not reach into the query object to retry. Clearing the pause
  // here is deliberate: an explicit retry is the user's decision, and the
  // countdown in the UI is what keeps them from spending the request early.
  // It drops back to the folder plane's deadline rather than to zero — the
  // user asked for discovery, not for the next window focus to re-spend a
  // folder listing the same budget is still refusing.
  const retryDiscovery = useCallback(async () => {
    pausedUntilRef.current = childrenRateLimitedUntil ?? 0
    await accessibleQuery.refetch()
  }, [accessibleQuery, childrenRateLimitedUntil])
  // The same contract for the children query. Nothing to clear here: `refetch`
  // is not gated by the focus predicate, and the pause is shared with
  // discovery — clearing it on a folder retry would hand the next window focus
  // a discovery request the server is still refusing. A folder listing is NOT
  // fetched only on request, though: `refetchOnMount: 'always'` and the window
  // focus bridge both reach it, which is why the pause above now covers it.
  const retryChildren = useCallback(async () => {
    await childrenQuery.refetch()
  }, [childrenQuery])
  const accessibleNotice =
    sessionScope && !canListAccessibleResources
      ? 'Automatic GFS discovery is not available in this desktop runtime. You can still open any GFS link you have.'
      : discoveryFailure?.kind === 'unsupported'
        ? 'Automatic GFS discovery is not available from this server yet. You can still open any GFS link you have.'
        : null

  const openUri = useCallback(
    async (uri: string, options?: { clearIfUnavailable?: boolean; background?: boolean }) => {
      const background = options?.background === true
      // User navigation owns the location until its authoritative resolution
      // settles. A background refresh that starts before React commits that
      // navigation must not read/commit the old location in the meantime.
      if (background && foregroundOpenUriPendingRef.current !== null) return false
      const generation = background ? openUriGenerationRef.current : ++openUriGenerationRef.current
      const backgroundGeneration = background ? ++backgroundOpenUriGenerationRef.current : undefined
      const isCurrent = () =>
        openUriGenerationRef.current === generation &&
        (!background ||
          (backgroundOpenUriGenerationRef.current === backgroundGeneration &&
            currentCrumbRef.current?.gfsUri === uri))
      if (!background) {
        if (backgroundLocationRetryTimerRef.current !== null) {
          window.clearTimeout(backgroundLocationRetryTimerRef.current)
          backgroundLocationRetryTimerRef.current = null
        }
        backgroundLocationRetryAttemptRef.current = 0
        foregroundOpenUriPendingRef.current = generation
        backgroundOpenErrorRef.current = false
        setOpenError(null)
        setResolving(true)
      }
      try {
        const resource = await window.clerum.gfs.resolve(uri.trim())
        if (!isCurrent()) return false
        const crumb: GfsCrumb = {
          resourceId: resource.resourceId,
          gfsUri: resource.gfsUri,
          name: resource.name,
          kind: resource.kind === 'directory' ? 'directory' : 'file',
          version: resource.version ?? 0,
          // `resolve` may omit bytes (older servers) — crumbs display 0 then,
          // matching the `version ?? 0` handling above.
          bytes: resource.bytes ?? 0,
        }
        const ancestors: GfsCrumb[] = []
        const seenResourceIds = new Set([resource.resourceId])
        let parentResourceId = resource.parentResourceId

        while (parentResourceId && ancestors.length < GFS_BREADCRUMB_MAX_DEPTH) {
          if (seenResourceIds.has(parentResourceId)) break
          seenResourceIds.add(parentResourceId)
          try {
            const parentRid = parentResourceId.replace(/-/g, '').toLowerCase()
            const parent = await window.clerum.gfs.resolve(`gfs://${resource.drive}/${parentRid}`)
            if (!isCurrent()) return false
            if (parent.kind !== 'directory') break
            if (parent.name) {
              ancestors.push({
                resourceId: parent.resourceId,
                gfsUri: parent.gfsUri,
                name: parent.name,
                kind: 'directory',
                version: parent.version ?? 0,
                bytes: parent.bytes ?? 0,
              })
            }
            parentResourceId = parent.parentResourceId
          } catch (error) {
            const status = parseHttpStatus(toMessage(error))
            if (status === 403 || status === 404) {
              // The leaf already resolved authoritatively. A denied or deleted
              // ancestor must disappear from its path without closing a leaf
              // that remains directly readable; a later scope tick can restore
              // the breadcrumb if visibility returns.
              break
            }
            if (background) {
              backgroundOpenErrorRef.current = true
              setOpenError(toPresentedMessage(error))
              scheduleBackgroundLocationRetry(uri, error)
              return false
            }
            // A direct file grant can be readable while its parent is not. Keep
            // the file open and show only the ancestors the caller may resolve.
            break
          }
        }

        if (!isCurrent()) return false
        // A background resolve may recover its own transient error, but it
        // must not erase a foreground link/navigation error being shown for a
        // separate user action.
        if (!background || backgroundOpenErrorRef.current) {
          backgroundOpenErrorRef.current = false
          setOpenError(null)
        }
        if (background) {
          if (backgroundLocationRetryTimerRef.current !== null) {
            window.clearTimeout(backgroundLocationRetryTimerRef.current)
            backgroundLocationRetryTimerRef.current = null
          }
          backgroundLocationRetryAttemptRef.current = 0
        }
        setCrumbsState([...ancestors.reverse(), crumb])
        return crumb
      } catch (error) {
        if (!isCurrent()) return false
        const message = toMessage(error)
        // Opening a URI is an operation on one resource. A generic 403 may be
        // a per-resource policy decision; only a session-authority failure
        // (bare 401 / typed lifecycle code) fails the session closed.
        //
        // The authority check reads the RAW message — it matches status codes
        // and lifecycle tokens — while the banner shows the presented verdict.
        if (!handleAuthorityFailure(message, 'operation')) {
          const status = parseHttpStatus(message)
          if (options?.clearIfUnavailable && (status === 403 || status === 404)) {
            clearInaccessibleGfsLocation()
          } else {
            if (background) backgroundOpenErrorRef.current = true
            setOpenError(toPresentedMessage(error))
            if (background) scheduleBackgroundLocationRetry(uri, error)
          }
        }
        return false
      } finally {
        if (!background && foregroundOpenUriPendingRef.current === generation) {
          foregroundOpenUriPendingRef.current = null
          if (openUriGenerationRef.current === generation) setResolving(false)
        }
      }
    },
    [clearInaccessibleGfsLocation, handleAuthorityFailure, scheduleBackgroundLocationRetry]
  )
  useEffect(() => {
    backgroundLocationRetryRef.current = uri => {
      void openUri(uri, { background: true, clearIfUnavailable: true })
    }
    return () => {
      backgroundLocationRetryRef.current = () => undefined
      if (backgroundLocationRetryTimerRef.current !== null) {
        window.clearTimeout(backgroundLocationRetryTimerRef.current)
        backgroundLocationRetryTimerRef.current = null
      }
    }
  }, [openUri, sessionScope])

  const refreshCurrentLocation = useCallback(
    async (options?: { background?: boolean }) => {
      const uri = current?.gfsUri
      if (!uri) return false
      return openUri(uri, { clearIfUnavailable: true, background: options?.background })
    },
    [current?.gfsUri, openUri]
  )

  // The OPEN resource's inherited access is derived from its ANCESTRY. A move
  // of that resource — or of one of its ancestors — changes what it
  // inherits, so an open Share/Manage dialog must re-read those rows instead
  // of showing the pre-move observation.
  //
  // The ancestry is read from the SHARED open-location registry, not from
  // this mount's own crumbs: the dialog that shows those rows can live in
  // ANOTHER controller (the Files page) while the move is committed by this
  // one (the sidebar). Controller-local crumbs only ever proved the chain
  // this mount observed, and a resource opened by URI has ancestors that no
  // children cache ever listed (RP-005).
  const openAncestryDependentResourceIds = useCallback(
    (movedResourceId: string): string[] => {
      if (!sessionScope) return []
      return ancestryDependentGfsResourceIds(
        readGfsOpenLocations(queryClient, sessionScope),
        movedResourceId
      )
    },
    [queryClient, sessionScope]
  )

  // Move refreshes through the shared convergence planner (rev-2 §6): the
  // receipt selectively invalidates the old/new parent children listings and
  // accessible roots, and marks the moved resource plus its KNOWN cached
  // descendants' permission data stale-on-entry. The moved resource's id does
  // not change, but its version does, and when the OPEN folder (or file)
  // itself moved, its breadcrumb trail is stale: the ancestors above it
  // belong to the old location. Consume the returned version immediately and
  // reconcile navigation to the new location (resolve + ancestor walk) so a
  // follow-up Rename/Delete/Move runs with the post-move version, not the
  // pre-move one (which would 409 on ifMatch).
  //
  // The convergence is a named step because it has TWO entry points: the
  // mutation's success path, and the transport-loss path where the PATCH
  // landed but its response never arrived (the mutation rejected, so its
  // success path never ran — without this the item kept rendering in the old
  // folder until the next navigation).
  const convergeCommittedMove = useCallback(
    async (
      input: {
        resourceId: string
        destinationId: string
        newName?: string
        oldParentId?: string | null
      },
      receipt: { version: number }
    ) => {
      const movedCrumb = crumbs.find(crumb => crumb.resourceId === input.resourceId)
      setCrumbs(prev =>
        prev.map(crumb =>
          crumb.resourceId === input.resourceId
            ? {
                ...crumb,
                version: receipt.version,
                ...(input.newName !== undefined ? { name: input.newName } : {}),
              }
            : crumb
        )
      )
      if (sessionScope) {
        applyMoveConvergence(
          queryClient,
          sessionScope,
          DRIVE,
          {
            resourceId: input.resourceId,
            oldParentId: input.oldParentId ?? null,
            newParentId: input.destinationId,
          },
          {
            ancestryDependentResourceIds: openAncestryDependentResourceIds(input.resourceId),
          }
        )
      } else {
        await refreshGfs()
      }
      if (movedCrumb) await openUri(movedCrumb.gfsUri)
    },
    [crumbs, openAncestryDependentResourceIds, openUri, queryClient, refreshGfs, sessionScope]
  )

  const moveResourceMutation = useMutation({
    mutationFn: (input: {
      resourceId: string
      destinationId: string
      ifMatch?: number
      newName?: string
      oldParentId?: string | null
    }) =>
      window.clerum.gfs.moveResource(
        input.resourceId,
        input.destinationId,
        DRIVE,
        input.ifMatch,
        input.newName
      ),
    onSuccess: async (receipt, input) => {
      await convergeCommittedMove(input, receipt)
    },
    onError: failClosedOnMutationError,
  })

  /**
   * Revalidate a folder's children listing as navigation enters it. Folder
   * contents change out-of-band (agents with host grants, other sessions,
   * operator writes) and TanStack does not refetch on a live observer's
   * query-key switch, so revisit would otherwise serve the Infinity-cached
   * page until a hard app reload. `refetchType: 'all'` also refreshes the
   * currently-inactive query so fresh data lands as the crumbs update.
   */
  const revalidateChildren = useCallback(
    (resourceId: string) => {
      if (!sessionScope) return
      void queryClient.invalidateQueries({
        exact: true,
        queryKey: desktopQueryKeys.gfsChildren(sessionScope, resourceId, DRIVE),
        refetchType: 'all',
      })
    },
    [queryClient, sessionScope]
  )

  const openChild = useCallback(
    (child: GfsBrowserChild) => {
      if (child.kind !== 'directory') return
      revalidateChildren(child.resourceId)
      setCrumbs(prev => [
        ...prev,
        {
          resourceId: child.resourceId,
          gfsUri: child.gfsUri,
          name: child.name,
          kind: 'directory',
          version: child.version,
          bytes: child.bytes,
        },
      ])
    },
    [revalidateChildren]
  )

  const openResource = useCallback(
    (resource: GfsBrowserChild) => {
      setOpenError(null)
      if (resource.kind === 'directory') revalidateChildren(resource.resourceId)
      setCrumbs([
        {
          resourceId: resource.resourceId,
          gfsUri: resource.gfsUri,
          name: resource.name,
          kind: resource.kind === 'directory' ? 'directory' : 'file',
          version: resource.version,
          bytes: resource.bytes,
        },
      ])
    },
    [revalidateChildren]
  )

  const goToCrumb = useCallback(
    (index: number) => {
      setCrumbs(prev => {
        const next = prev.slice(0, index + 1)
        const target = next[index]
        if (target?.kind === 'directory') revalidateChildren(target.resourceId)
        return next
      })
    },
    [revalidateChildren]
  )

  /** Restore an exact browser location after a transient resource selection
   *  (for example, opening a row's Manage dialog). */
  const restoreCrumbs = useCallback((nextCrumbs: GfsCrumb[]) => {
    setCrumbs(nextCrumbs)
    setOpenError(null)
  }, [])

  const reset = useCallback(() => {
    setCrumbs([])
    setOpenError(null)
    void queryClient.removeQueries({ queryKey: desktopQueryKeys.gfsRoot })
  }, [queryClient])

  // Delegation actions throw on server rejection (e.g. 403 escalation_rejected);
  // the caller surfaces that — never swallow it. `inherit` omitted defaults to
  // `true` on the wire (uriHandler), so user/team panel grants cover folder
  // contents; callers that need a contents-excluding grant pass `false`.
  const grant = useCallback(
    (subjectKeys: string[], bits: string[], inherit?: boolean): Promise<void> => {
      if (!current) return Promise.reject(new Error('No resource selected'))
      return window.clerum.gfs.grant(current.resourceId, subjectKeys, bits, DRIVE, inherit)
    },
    [current]
  )

  const createShare = useCallback(
    (subjectKeys: string[]): Promise<void> => {
      if (!current) return Promise.reject(new Error('No resource selected'))
      return window.clerum.gfs.createShare(current.resourceId, subjectKeys, DRIVE)
    },
    [current]
  )

  return {
    crumbs,
    current,
    /** Cache-scope key (env + user + team) so the move dialog's queries share
     *  the controller's cache and are dropped together on scope change. */
    sessionScope: sessionScope ?? 'anonymous',
    /** 'revoked' after a session-authority failure — queries are gated off
     *  and cached GFS state is gone until retryAccess re-enters the server. */
    accessState,
    /** True while discovery re-proves the session after mount/session return;
     *  cached GFS state is withheld (R4 spec §1). FilesPage renders loading. */
    authorityPending,
    retryAccess,
    handleAuthorityFailure,
    accessibleResources,
    items,
    affordances:
      authorityPending || accessState === 'revoked'
        ? null
        : ((affordancesQuery.data as GfsBrowserAffordances | undefined) ?? null),
    affordancesError: affordancesQuery.error ? toPresentedMessage(affordancesQuery.error) : null,
    loadingAffordances: affordancesQuery.isFetching,
    rowAffordancesByResourceId,
    rowAffordancesResourceId,
    setRowAffordancesResourceId,
    rowAffordances:
      authorityPending || accessState === 'revoked'
        ? null
        : ((rowAffordancesQuery.data as GfsBrowserAffordances | undefined) ?? null),
    rowAffordancesError: rowAffordancesQuery.error
      ? toPresentedMessage(rowAffordancesQuery.error)
      : null,
    // Only the `authorityPending` term stands down on a settled discovery
    // error, never the children term: a folder that is genuinely fetching must
    // keep the spinner, or the view flashes "this folder is empty" mid-load.
    // Without the gate a 429 on discovery — which leaves `authorityPending`
    // true by design, because a rate limit does not re-prove the session —
    // pinned every consumer of this field on "Loading files…" with nothing
    // in flight to end it.
    loading:
      ((authorityPending && !discoveryFailure) || childrenQuery.isFetching) && items.length === 0,
    // A settled discovery error is not a pending load. Without this the
    // spinner outlived the failure for every consumer that derives its
    // loading state from here alone (ComposerGlobalFilesModal). The term
    // belongs on this field only: `loading` above reports the INDEPENDENT
    // children query, and gating it on a discovery error hid the spinner while
    // a folder was genuinely loading, flashing "this folder is empty".
    loadingAccessible:
      !accessibleQuery.isError &&
      ((authorityPending && canListAccessibleResources) ||
        (canListAccessibleResources &&
          accessibleQuery.isFetching &&
          accessibleResources.length === 0)),
    error: childrenErrorMessage,
    // The clock the children failure is dated by. A countdown needs the moment
    // the server refused, and only the query knows it; deriving it from render
    // time would restart the wait on every re-render.
    errorUpdatedAt: childrenErrorUpdatedAt,
    accessibleError: accessibleNotice ? null : accessibleErrorMessage,
    accessibleNotice,
    discoveryFailure,
    retryDiscovery,
    retryChildren,
    openError,
    resolving,
    hasMore: Boolean(childrenQuery.hasNextPage),
    isFetchingMore: childrenQuery.isFetchingNextPage,
    hasMoreAccessible: canListAccessibleResources && Boolean(accessibleQuery.hasNextPage),
    isFetchingMoreAccessible: canListAccessibleResources && accessibleQuery.isFetchingNextPage,
    loadMore: () => {
      void childrenQuery.fetchNextPage()
    },
    loadMoreAccessible: () => {
      if (!canListAccessibleResources) return
      void accessibleQuery.fetchNextPage()
    },
    openUri,
    refreshCurrentLocation,
    openResource,
    openChild,
    goToCrumb,
    restoreCrumbs,
    reset,
    refreshAffordances,
    grant,
    grants,
    // Raw error (not toMessage) so FilesPage can map server codes — e.g. a
    // manage_acl_required 403 renders as a quiet banner, not an error.
    grantsError: grantsQuery.error,
    loadingGrants: grantsQuery.isFetching,
    refreshGrants,
    revokeGrant: (grantId: string) => revokeGrantMutation.mutateAsync(grantId),
    revoking: revokeGrantMutation.isPending,
    shares,
    // Raw error (not toMessage) so FilesPage maps server codes symmetrically
    // with grantsError.
    sharesError: sharesQuery.error,
    loadingShares: sharesQuery.isFetching,
    refreshShares,
    // Client-derived ancestor access for FILE AND FOLDER Manage dialogs:
    // normal-looking toggleable rows whose edits route through the
    // parent-folder confirmation. Rows folded before a walk stop are always
    // retained (R1-H3); the stop itself is reported through
    // inheritedCoverage/inheritedAccessError.
    inheritedAccess,
    inheritedCoverage,
    loadingInheritedAccess: inheritedAccessQuery.isFetching,
    // Only an UNCLASSIFIED throw (today: a raw session 401) surfaces here; the
    // dialog renders a quiet notice because "no inherited rows" would silently
    // read as "no one else has access". Walk stops with classified coverage
    // are reported through inheritedCoverage instead.
    inheritedAccessError: inheritedAccessQuery.error ? toMessage(inheritedAccessQuery.error) : null,
    refreshInheritedAccess,
    revokeShare: (shareId: string) => revokeShareMutation.mutateAsync(shareId),
    revokingShare: revokeShareMutation.isPending,
    createShare,
    createFolder: (name: string) => createFolderMutation.mutateAsync(name),
    createFile: (parentResourceId: string, name: string, encodedData: string) =>
      createFileMutation.mutateAsync({ parentResourceId, name, encodedData }),
    createFileFromPath: (parentResourceId: string, name: string, filePath: string) =>
      createFileFromPathMutation.mutateAsync({ parentResourceId, name, filePath }),
    replaceFile: (resourceId: string, encodedData: string, ifMatch?: number) =>
      replaceFileMutation.mutateAsync({ resourceId, encodedData, ifMatch }),
    replaceFileFromPath: (resourceId: string, filePath: string, ifMatch?: number) =>
      replaceFileFromPathMutation.mutateAsync({ resourceId, filePath, ifMatch }),
    renameResource: (resourceId: string, name: string, ifMatch?: number) =>
      renameResourceMutation.mutateAsync({ resourceId, name, ifMatch }),
    moveResource: (
      resourceId: string,
      destinationId: string,
      ifMatch?: number,
      newName?: string,
      oldParentId?: string | null
    ) =>
      moveResourceMutation.mutateAsync({
        resourceId,
        destinationId,
        ifMatch,
        newName,
        oldParentId,
      }),
    deleteResource: (resourceId: string, ifMatch?: number) =>
      deleteResourceMutation.mutateAsync({ resourceId, ifMatch }),
    /**
     * Convergence for a move that landed without a receipt (transport loss):
     * the mutation rejected, so its success path never ran, and the item would
     * otherwise keep rendering in the old folder until the next navigation.
     */
    convergeCommittedMove,
    mutating:
      createFolderMutation.isPending ||
      createFileMutation.isPending ||
      createFileFromPathMutation.isPending ||
      replaceFileMutation.isPending ||
      replaceFileFromPathMutation.isPending ||
      renameResourceMutation.isPending ||
      moveResourceMutation.isPending ||
      deleteResourceMutation.isPending,
  }
}