feat(claw-app): audit cleanup dialog with typed-confirmation gate

Adds a Storage button to the /audit header that opens a two-stage
shadcn AlertDialog for the destructive /audit/cleanup endpoint.

Stage 1 lets the user pick a threshold (15/30/90 days). Only ranges
with at least one session appear as options, per Dani's spec; if none
of the three has any candidates, the whole button is hidden.

Stage 2 is a typed-confirmation gate: the user has to type
'delete N sessions older than D days' verbatim before the destructive
Delete button unlocks. Case-sensitive exact match. The phrase mirrors
the read-back line above the input and rebuilds when the range
changes so muscle memory from a prior cleanup cannot unlock a new
one. Same UX as GitHub repo delete / Stripe account delete.

On success: the mutation invalidates useTasks + useAuditCleanupCandidates
so the audit list, empty state, and Storage button all refetch on the
same tick. On failure: dialog stays on Stage 2 with the typed input
cleared so hitting Enter cannot silently retry.

Client hooks (useAuditCleanupCandidates + useAuditCleanup) live in
modules/api/audit.hooks.ts alongside the existing useTasks factories,
per the react-query-kit rules in CLAUDE.md.

Tests: 15 helper tests (phrase builder + case-sensitive matcher +
byte formatter) + 3 button-visibility tests. The interactive
two-stage flow is exercised by the pure-logic helpers plus the
server-side cleanup tests.

Author: DaniAkash

packages/browseros-agent/apps/claw-app/components/audit/CleanupButton.test.tsx

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2025 BrowserOS
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Static-markup checks for the audit CleanupButton's visibility gate.
+ * Interactive two-stage dialog behaviour is covered by the pure-logic
+ * unit tests in `cleanup.helpers.test.ts` (phrase builder + comparator)
+ * plus the server-side audit-cleanup tests. This file only asserts the
+ * outer rule: the button hides itself when there is nothing to clean.
+ */
+
+import { describe, expect, it, mock } from 'bun:test'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { CleanupCandidatesResponse } from '@/modules/api/audit.hooks'
+import * as auditHooks from '@/modules/api/audit.hooks'
+
+let candidatesOverride: CleanupCandidatesResponse | undefined
+
+// Re-export the real module surface with only the two cleanup hooks
+// stubbed. Preserves useTasks, useTaskDetail, useDispatches etc. for
+// any downstream consumer (Audit.test.tsx runs in the same process
+// and would otherwise resolve to a mock that's missing those exports).
+mock.module('@/modules/api/audit.hooks', () => ({
+  ...auditHooks,
+  useAuditCleanupCandidates: () => ({ data: candidatesOverride }),
+  useAuditCleanup: () => ({ mutate: () => {}, isPending: false }),
+}))
+
+const { CleanupButton } = await import('./CleanupButton')
+
+function render(): string {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return renderToStaticMarkup(
+    <QueryClientProvider client={client}>
+      <CleanupButton />
+    </QueryClientProvider>,
+  )
+}
+
+describe('CleanupButton visibility', () => {
+  it('renders nothing when candidates data is still loading', () => {
+    candidatesOverride = undefined
+    expect(render()).toBe('')
+  })
+
+  it('renders nothing when every range has zero sessions', () => {
+    candidatesOverride = {
+      ranges: [
+        {
+          olderThanDays: 15,
+          sessionCount: 0,
+          dispatchCount: 0,
+          bytesOnDisk: 0,
+        },
+        {
+          olderThanDays: 30,
+          sessionCount: 0,
+          dispatchCount: 0,
+          bytesOnDisk: 0,
+        },
+        {
+          olderThanDays: 90,
+          sessionCount: 0,
+          dispatchCount: 0,
+          bytesOnDisk: 0,
+        },
+      ],
+    }
+    expect(render()).toBe('')
+  })
+
+  it('renders the Storage button when at least one range has sessions', () => {
+    candidatesOverride = {
+      ranges: [
+        {
+          olderThanDays: 15,
+          sessionCount: 3,
+          dispatchCount: 12,
+          bytesOnDisk: 1000,
+        },
+        {
+          olderThanDays: 30,
+          sessionCount: 0,
+          dispatchCount: 0,
+          bytesOnDisk: 0,
+        },
+        {
+          olderThanDays: 90,
+          sessionCount: 0,
+          dispatchCount: 0,
+          bytesOnDisk: 0,
+        },
+      ],
+    }
+    const html = render()
+    expect(html).toContain('Storage')
+  })
+})

packages/browseros-agent/apps/claw-app/components/audit/CleanupButton.tsx

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 BrowserOS
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * The "Storage" button in the audit header. Only renders when the
+ * candidates query returns at least one non-empty range (i.e. there
+ * IS data older than the smallest threshold). Owns the dialog open
+ * state so the header component doesn't have to.
+ */
+
+import { Trash2 } from 'lucide-react'
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+import type { CleanupCandidateStats } from '@/modules/api/audit.hooks'
+import { useAuditCleanupCandidates } from '@/modules/api/audit.hooks'
+import { CleanupDialog } from './CleanupDialog'
+
+/**
+ * A range is worth showing to the user only when at least one session
+ * would be affected. Ranges with zero sessions are omitted entirely
+ * from the dialog (per Dani's spec).
+ */
+function nonEmptyRanges(
+  ranges: CleanupCandidateStats[] | undefined,
+): CleanupCandidateStats[] {
+  return (ranges ?? []).filter((r) => r.sessionCount > 0)
+}
+
+export function CleanupButton() {
+  const [open, setOpen] = useState(false)
+  const candidates = useAuditCleanupCandidates()
+  const ranges = nonEmptyRanges(candidates.data?.ranges)
+
+  if (ranges.length === 0) return null
+
+  return (
+    <>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => setOpen(true)}
+        className="h-8 gap-1.5 font-mono text-[11px] text-ink-2 uppercase tracking-[0.08em] hover:bg-card-tint"
+      >
+        <Trash2 className="size-3.5" />
+        Storage
+      </Button>
+      <CleanupDialog open={open} onOpenChange={setOpen} ranges={ranges} />
+    </>
+  )
+}

packages/browseros-agent/apps/claw-app/components/audit/CleanupDialog.tsx

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2025 BrowserOS
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Two-stage confirmation for the destructive /audit/cleanup call.
+ *
+ *   Stage 1  Pick a range. Radios for whichever thresholds have data.
+ *            Nothing dangerous happens here; Continue is neutral.
+ *
+ *   Stage 2  Typed-confirmation gate. Read-back line + input where the
+ *            user has to type "delete N sessions older than D days"
+ *            verbatim before Delete unlocks. Case-sensitive exact
+ *            match. Rebuilds when the range changes so muscle memory
+ *            from a prior cleanup cannot unlock a new one. Same
+ *            pattern as GitHub repo delete / Stripe account delete.
+ *
+ * Failure clears the typed input so hitting Enter without re-reading
+ * cannot retry silently.
+ */
+
+import { AlertTriangle } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group'
+import type {
+  CleanupCandidateStats,
+  CleanupResult,
+} from '@/modules/api/audit.hooks'
+import { useAuditCleanup } from '@/modules/api/audit.hooks'
+import {
+  buildConfirmationPhrase,
+  formatBytes,
+  matchesConfirmationPhrase,
+} from './cleanup.helpers'
+
+interface CleanupDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Only the non-empty ranges. Empty ones are filtered by the caller. */
+  ranges: CleanupCandidateStats[]
+  onSuccess?: (result: CleanupResult) => void
+}
+
+type Stage = 'pick' | 'confirm'
+
+export function CleanupDialog({
+  open,
+  onOpenChange,
+  ranges,
+  onSuccess,
+}: CleanupDialogProps) {
+  const [stage, setStage] = useState<Stage>('pick')
+  const [selectedDays, setSelectedDays] = useState<number | null>(
+    ranges.length === 1 ? (ranges[0]?.olderThanDays ?? null) : null,
+  )
+  const [typed, setTyped] = useState('')
+  const [errorText, setErrorText] = useState<string | null>(null)
+  const cleanup = useAuditCleanup()
+
+  // Reset internal state whenever the dialog opens so a previous
+  // typed phrase or error banner never survives across sessions.
+  useEffect(() => {
+    if (!open) return
+    setStage('pick')
+    setSelectedDays(
+      ranges.length === 1 ? (ranges[0]?.olderThanDays ?? null) : null,
+    )
+    setTyped('')
+    setErrorText(null)
+  }, [open, ranges])
+
+  const selected = ranges.find((r) => r.olderThanDays === selectedDays) ?? null
+  const phrase = selected
+    ? buildConfirmationPhrase(selected.sessionCount, selected.olderThanDays)
+    : ''
+  const canDelete =
+    stage === 'confirm' &&
+    !!selected &&
+    !cleanup.isPending &&
+    matchesConfirmationPhrase(typed, phrase)
+
+  const handleContinue = () => {
+    if (!selected) return
+    setStage('confirm')
+  }
+
+  const handleBack = () => {
+    setStage('pick')
+    setTyped('')
+    setErrorText(null)
+  }
+
+  const handleDelete = () => {
+    if (!canDelete || !selected) return
+    setErrorText(null)
+    cleanup.mutate(
+      { olderThanDays: selected.olderThanDays },
+      {
+        onSuccess: (res) => {
+          onSuccess?.(res)
+          onOpenChange(false)
+        },
+        onError: () => {
+          setErrorText(
+            'The cleanup failed. Read the confirmation again and try once more.',
+          )
+          setTyped('')
+        },
+      },
+    )
+  }
+
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        {stage === 'pick' ? (
+          <>
+            <AlertDialogHeader>
+              <AlertDialogTitle>Delete old audit data</AlertDialogTitle>
+              <AlertDialogDescription>
+                Deletes sessions, replays, and screenshots older than the
+                selected age. This cannot be undone.
+              </AlertDialogDescription>
+            </AlertDialogHeader>
+            <RadioGroup
+              value={selectedDays !== null ? String(selectedDays) : undefined}
+              onValueChange={(v) => setSelectedDays(Number(v))}
+              className="gap-2"
+            >
+              {ranges.map((r) => (
+                <label
+                  key={r.olderThanDays}
+                  htmlFor={`cleanup-range-${r.olderThanDays}`}
+                  className="flex cursor-pointer items-start gap-3 rounded-md border border-border p-3 hover:bg-muted"
+                >
+                  <RadioGroupItem
+                    id={`cleanup-range-${r.olderThanDays}`}
+                    value={String(r.olderThanDays)}
+                    className="mt-0.5"
+                  />
+                  <span className="flex flex-col text-left">
+                    <span className="font-medium">
+                      Older than {r.olderThanDays} days
+                    </span>
+                    <span className="text-muted-foreground text-xs">
+                      {r.sessionCount}{' '}
+                      {r.sessionCount === 1 ? 'session' : 'sessions'} · up to{' '}
+                      {formatBytes(r.bytesOnDisk)}
+                    </span>
+                  </span>
+                </label>
+              ))}
+            </RadioGroup>
+            <AlertDialogFooter>
+              <AlertDialogCancel>Cancel</AlertDialogCancel>
+              <Button
+                type="button"
+                onClick={handleContinue}
+                disabled={selected === null}
+              >
+                Continue
+              </Button>
+            </AlertDialogFooter>
+          </>
+        ) : (
+          <>
+            <AlertDialogHeader>
+              <AlertDialogTitle className="flex items-center gap-2">
+                <AlertTriangle className="size-5 text-destructive" />
+                Type to confirm
+              </AlertDialogTitle>
+              <AlertDialogDescription>
+                You are about to delete{' '}
+                <strong>
+                  {selected?.sessionCount}{' '}
+                  {selected?.sessionCount === 1 ? 'session' : 'sessions'} older
+                  than {selected?.olderThanDays} days
+                </strong>
+                . This frees up to {formatBytes(selected?.bytesOnDisk ?? 0)} and
+                cannot be undone.
+              </AlertDialogDescription>
+            </AlertDialogHeader>
+            <div className="flex flex-col gap-2">
+              <p className="text-muted-foreground text-xs">
+                Type the phrase below exactly to enable the Delete button:
+              </p>
+              <code className="rounded bg-muted px-2 py-1.5 font-mono text-xs">
+                {phrase}
+              </code>
+              <Input
+                autoFocus
+                spellCheck={false}
+                autoComplete="off"
+                value={typed}
+                onChange={(e) => setTyped(e.target.value)}
+                placeholder=""
+                className="font-mono text-xs"
+                data-testid="cleanup-confirm-input"
+              />
+              {errorText && (
+                <p className="text-destructive text-xs" role="alert">
+                  {errorText}
+                </p>
+              )}
+            </div>
+            <AlertDialogFooter>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={handleBack}
+                disabled={cleanup.isPending}
+              >
+                Back
+              </Button>
+              <AlertDialogAction
+                variant="destructive"
+                onClick={handleDelete}
+                disabled={!canDelete}
+                data-testid="cleanup-confirm-delete"
+              >
+                {cleanup.isPending ? 'Deleting…' : 'Delete'}
+              </AlertDialogAction>
+            </AlertDialogFooter>
+          </>
+        )}
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}