[audit] 7-day cache TTL + top-of-page re-audit bar

[NiveditJain]

Summary

This PR bundles three related changes to the audit page:

1. 7-day cache TTL on both audit caches

• Per-transcript cache (src/audit/cache.ts) gains a cachedAt field and a CACHE_TTL_MS = 7d reject-on-read check; schema bumps 2 → 3 so v2 entries (no cachedAt) force a clean re-scan. Number.isFinite guards the timestamp so a malformed JSON Infinity/NaN can't pin a stale entry forever.
• Dashboard cache (src/audit/dashboard-cache.ts) reuses the existing isCacheStale(cachedAt, 7d) helper on the read path. getAuditResultAction() already maps null to {status: "empty"}, so /audit falls through to the empty state past expiry. New readDashboardCacheMeta() helper bypasses the TTL but gates on schema version + parseable timestamp first — schema-incompatible caches fall through to the first-run empty copy instead of triggering the wrong banner.

2. Top-of-page re-audit bar + sticky progress strip

• New TopAuditBar (app/audit/_components/top-audit-bar.tsx) renders as the first child of .report — three modes (cached, expired, empty). Shows relative-time (audited 3d ago), an amber expires in 14h — re-audit to refresh chip when within 24h of the TTL boundary, and a [ re-audit ] button reusing .share-btn.
• Re-audit state lifts out of return-section.tsx into audit-dashboard.tsx — the top bar and bottom button share a single startRerun(source) handler with PostHog source tagging (top_bar / return_section / empty_state); concurrent clicks impossible.
• New AuditProgressStrip is pinned to the top of the viewport during a run (pink hard-offset shadow matching .share-btn:hover, mm:ss elapsed timer, CSS-only edge pulse). Red error variant on RerunError.kind (timeout / network / post_failed) with a [ dismiss ] chip.
• Success path soft-refreshes the dashboard cache via getAuditResultAction() — no more window.location.reload().
• All new chrome stays inside the existing aesthetic vocabulary: no new fonts or colours, reuses --accent-pink, --amber, --accent-green, dashed --line dividers, ━━ glyphs, lowercase mono, bracketed [ ... ] button labels. All new motion respects prefers-reduced-motion: reduce.

3. fetch-with-timeout: silence the dev-overlay AbortError warning

• Replace the manual AbortController + setTimeout in lib/fetch-with-timeout.ts with platform AbortSignal.timeout() (typed TimeoutError reason) composed with AbortSignal.any() to forward caller-supplied init.signal. Fixes two bugs at once:
  • Next.js 16's dev overlay was surfacing "signal is aborted without reason" because controller.abort() ran with no reason argument.
  • { ...init, signal: controller.signal } was silently dropping any caller-supplied init.signal, so component-unmount cancellations couldn't stop in-flight fetches.
• Both APIs covered by Next.js 16's runtime floor (Node 17.3+/20.3+ — AbortSignal.any also backported to Node 18.17 — and Chrome 116+ / Firefox 124+ / Safari 17.4+).
• isAbortError is hardened to duck-type on .name so it correctly classifies cross-realm errors and jsdom's polyfilled DOMException (which is not instanceof Error). Production callers (requestLoginCode, triggerRun, auth-dialog.tsx) keep their existing timeout-vs-network discrimination.

CodeRabbit review feedback (addressed in c0a4c41)

• Number.isFinite(cachedAt) guard added to the per-transcript cache.
• Schema validity gated in readDashboardCacheMeta before surfacing "expired".
• cachedAt reworded as TTL metadata (not cache-key) in docs/cli/audit.mdx.
• failproof policy add → failproofai policy add typo fixed in docs/dashboard.mdx.
• Runtime compatibility note in lib/fetch-with-timeout.ts tightened to reference per-API Node minima against Next.js 16's Node ≥ 20.9 floor.
• All three 0.0.11-beta.6 CHANGELOG entries now end with (#428).

Docs updated in docs/dashboard.mdx + docs/cli/audit.mdx; CHANGELOG.md 0.0.11-beta.6 entry under ### Features, ### Fixes, and ### Docs. Merged origin/main (PR #429 goldfish-classifier fix) — combined CHANGELOG ### Fixes now lists both #429 and #428 entries.

Test plan

• bun run test:run — 1857 passed (0 failed) across 97 files; new __tests__/audit/cache.test.ts (9), __tests__/audit/top-audit-bar.test.tsx (12), __tests__/lib/fetch-with-timeout.test.ts (13), and +4 cases in __tests__/audit/dashboard-cache.test.ts.
• bun x tsc --noEmit clean.
• bun run lint clean (only pre-existing <img> warnings unrelated to this PR).
• Manual: bun run dev → /audit after a recent run, click the top [ re-audit ], confirm sticky pink strip + soft-refresh (no full reload). Confirm the dev console no longer shows "signal is aborted without reason" while the polling loop runs.
• Manual: simulate expiry by editing ~/.failproofai/audit-dashboard.json's cachedAt to 8 days ago, reload /audit, expect empty state + audit expired banner.
• Manual: block /api/audit/run in DevTools → confirm red error strip with the correct copy, no full reload.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • 7-day audit cache expiry with visible expired/empty states, re-audit top bar, and sticky re-run progress strip (elapsed timer)
  • Rerun flow wiring so re-audit actions refresh results in-place

• Bug Fixes

  • Hardened fetch timeout/abort handling and more tolerant abort/error detection

• Documentation

  • Updated audit caching and re-audit workflow docs

• Tests

  • Added tests for cache TTLs, dashboard cache meta, UI banners/strip, and fetch timeout behavior

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3726b628-0385-4302-9635-29b98563ecd7

📥 Commits

Reviewing files that changed from the base of the PR and between 110edfc and f288f40.

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/cli/audit.mdx
• docs/dashboard.mdx
• lib/fetch-with-timeout.ts
• src/audit/cache.ts
• src/audit/dashboard-cache.ts

✅ Files skipped from review due to trivial changes (2)

• docs/cli/audit.mdx
• docs/dashboard.mdx

🚧 Files skipped from review as they are similar to previous changes (3)

• src/audit/dashboard-cache.ts
• src/audit/cache.ts
• lib/fetch-with-timeout.ts

---

📝 Walkthrough

Walkthrough

Implements 7-day TTL cache invalidation for per-transcript and dashboard caches, exposes dashboard cache metadata to distinguish expired vs first-run empty states, centralizes rerun orchestration (TopAuditBar + AuditProgressStrip + dashboard wiring), updates fetch timeout signal handling, and adds tests, styles, docs, and changelog entries.

Changes

Audit cache TTL with rerun UI refactor

Layer / File(s)	Summary
Cache TTL contracts and tests src/audit/cache.ts, src/audit/dashboard-cache.ts, __tests__/audit/cache.test.ts, __tests__/audit/dashboard-cache.test.ts	Per-transcript cache schema bumped to include cachedAt; reads reject entries older than 7 days; writes stamp cachedAt. Dashboard cache read returns null when stale and exposes readDashboardCacheMeta() to read cachedAt without TTL gating. Tests validate TTL, schema, and metadata behaviors.
Expired-aware action and page init app/actions/get-audit-result.ts, app/audit/page.tsx	getAuditResultAction() now returns empty payloads with expired and expiredAt when no fresh cache exists by reading dashboard cache meta. Audit page initializes empty state using the same metadata to select banner mode.
TopAuditBar, progress strip, styles, and tests app/audit/_components/top-audit-bar.tsx, app/audit/_components/audit-progress-strip.tsx, app/audit/audit-styles.css, __tests__/audit/top-audit-bar.test.tsx	Adds TopAuditBar (cached/expired/empty) with relativeTimeAgo/timeUntilExpiry, AuditProgressStrip with RerunStatus/formatElapsed, CSS for both strips, and tests covering formatting, modes, expiry note, progress timing, error state, and rerun interaction.
Dashboard rerun orchestration and wiring app/audit/_components/audit-dashboard.tsx, app/audit/_components/return-section.tsx	Centralizes rerunStatus and startRerun in AuditDashboard, wires TopAuditBar and AuditProgressStrip into views, passes rerun props to MainReport and ReturnSection, and expands ShellEmpty props to render top-bar and handle rerun dismissal.
Fetch timeout signal composition and tests lib/fetch-with-timeout.ts, __tests__/lib/fetch-with-timeout.test.ts, app/audit/_components/rerun-button.tsx	fetchWithTimeout uses AbortSignal.timeout() + AbortSignal.any() to compose timeout and caller signals; isAbortError uses name-based duck-typing. Tests validate signal composition, timeout and abort behavior, and error classification; docs/comment updated to reflect cachedAt in status responses.
Docs and changelog CHANGELOG.md, docs/cli/audit.mdx, docs/dashboard.mdx	Updates release notes and documentation to describe 7-day TTL cache read rejection, expired-state UI, re-audit CTAs, polling behavior, and in-place streaming refresh during reruns.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• FailproofAI/failproofai#429: Related classifier/goldfish regression and distribution test referenced by the changelog entry.
• FailproofAI/failproofai#397: Related prior work on dashboard cache and audit result flow extended here with TTL and meta reads.
• FailproofAI/failproofai#377: Earlier PR that introduced the per-transcript audit cache module; this change bumps schema and adds TTL semantics.

"I'm a rabbit in the cache meadow, bright and spry,
Seven days I hop, then wave the old logs bye,
A top bar hums, a progress strip beats on,
Re-audit the fields until the stale is gone,
🐇✨ Fresh audits bloom beneath the morning sky."

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[audit] 7-day cache TTL + top-of-page re-audit bar' directly reflects the main changes: cache TTL enforcement and new UI components for re-audit functionality.
Description check	✅ Passed	The description comprehensively covers all three major changes (cache TTL, UI components, fetch-with-timeout refactor) with technical details, includes a test plan with concrete results, and documents CodeRabbit feedback addressed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

docs/cli/audit.mdx

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

docs/dashboard.mdx

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

lib/fetch-with-timeout.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

• 2 others

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
failproofai	🟢 Ready	View Preview	Jun 10, 2026, 4:35 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/dashboard.mdx (1)

62-62: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Audit section still describes a CLI flow that docs now deprecate.

Lines 62 and 71 refer to the failproofai audit CLI and “supported flags,” which conflicts with the updated /audit-page-first guidance. Please align phrasing so users don’t expect a runnable audit subcommand.

Also applies to: 71-71

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/dashboard.mdx` at line 62, Update the copy that references the
deprecated CLI command `failproofai audit` and any mention of “supported flags”
to instead point users to the web-based `/audit` page; specifically, replace the
phrase “Runs the same scan as the `failproofai audit` CLI” with something like
“Runs the same scan as the /audit page” and remove or rephrase any “supported
flags” wording (also update the second occurrence of `failproofai audit` near
the later paragraph) so the dashboard text consistently directs users to the
/audit page rather than implying a runnable CLI subcommand.

🧹 Nitpick comments (1)

app/audit/_components/top-audit-bar.tsx (1)

133-138: 💤 Low value

Minor: redundant null check.

The remainingMs !== null guard on line 133 is redundant—expiringSoon (computed on lines 73–77) already ensures remainingMs !== null when true. You can simplify to:

-{expiringSoon && remainingMs !== null && (+{expiringSoon && (
<div className="top-audit-bar__center" aria-live="polite">

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@app/audit/_components/top-audit-bar.tsx` around lines 133 - 138, Remove the
redundant null check by using only the expiringSoon guard in the render: when
expiringSoon is true it already implies remainingMs !== null (computed earlier),
so simplify the conditional from "expiringSoon && remainingMs !== null && (...)"
to "expiringSoon && (...)" in the component that renders the expiry message
(referencing expiringSoon, remainingMs, timeUntilExpiry and cachedAtMs in
top-audit-bar.tsx).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CHANGELOG.md`:
- Around line 5-13: The CHANGELOG.md entries under the "Fixes", "Docs", and
"Features" sections (the long-form paragraphs referencing
lib/fetch-with-timeout.ts:25, isAbortError,
__tests__/lib/fetch-with-timeout.test.ts, docs/dashboard.mdx,
src/audit/{cache.ts,dashboard-cache.ts},
app/audit/_components/top-audit-bar.tsx, AuditProgressStrip, and the various
__tests__/audit/* files) must be collapsed into concise single-line bullets and
each appended with the PR number in the format "(`#428`)"; replace each multi-line
paragraph with a one-line summary that mentions the main change (e.g., "Fix:
prevent Next.js 16 dev-overlay 'signal is aborted without reason' warning and
harden isAbortError — use AbortSignal.timeout + AbortSignal.any (`#428`)"),
likewise compress the Docs and Features paragraphs into one-liners referencing
their main effect and append "(`#428`)".
In `@docs/cli/audit.mdx`:
- Line 50: The documentation incorrectly lists cachedAt as part of the cache
key; update the sentence in docs/cli/audit.mdx so the per-transcript cache is
described as keyed by (mtime, size, engineVersion, detectorVersion) and state
that cachedAt is stored as TTL/expiration metadata (used to reject entries older
than 7 days) rather than as a key component, ensuring the wording no longer
implies cache invalidation happens due to cachedAt changes.
In `@docs/dashboard.mdx`:
- Line 68: Update the example command string shown as "$ failproof policy add
<slug>" to use the correct executable name "failproofai" so the docs match the
rest of the documentation and the command will work for users; locate the
occurrence of the literal command string in docs/dashboard.mdx (the Findings
card example) and replace it accordingly.
In `@lib/fetch-with-timeout.ts`:
- Around line 10-22: Update the runtime compatibility note in
lib/fetch-with-timeout.ts: replace the incorrect “Both APIs… (Node 20.3+)” claim
with accurate minima for the two APIs (for example state that
AbortSignal.timeout is available in Node 20.3+ while AbortSignal.any was
backported to Node 18.17+, or simply say “Node 18.17+/20.3+ depending on API”),
and remove the outdated “Next.js 15 / Node 18” wording—ensure the text
references the exact API names AbortSignal.timeout and AbortSignal.any and the
repo’s Next.js target (Next.js 16 requiring Node >=20.9.0) so the doc matches
the project requirements.
In `@src/audit/cache.ts`:
- Line 107: Replace the loose typeof check for cachedAt with a finite-number
check: ensure entry.cachedAt is a finite numeric value (use
Number.isFinite(entry.cachedAt)) and still verify TTL (Date.now() -
entry.cachedAt > CACHE_TTL_MS) so Infinity/NaN are rejected; update the
conditional that currently reads the typeof check to use Number.isFinite for
entry.cachedAt and keep the CACHE_TTL_MS comparison.
In `@src/audit/dashboard-cache.ts`:
- Around line 135-137: readDashboardCacheMeta is only checking cachedAt and can
let schema-invalid entries pass through; update the logic in the
readDashboardCacheMeta (src/audit/dashboard-cache.ts) to validate the parsed
object against the full DashboardCacheEntry schema (e.g., using an existing type
guard/validator or add a new isValidDashboardCacheEntry function) before
returning { cachedAt: entry.cachedAt }; if the object fails the full-schema
check return null so downstream logic (app/actions/get-audit-result.ts) cannot
misclassify invalid entries as expired.
---
Outside diff comments:
In `@docs/dashboard.mdx`:
- Line 62: Update the copy that references the deprecated CLI command
`failproofai audit` and any mention of “supported flags” to instead point users
to the web-based `/audit` page; specifically, replace the phrase “Runs the same
scan as the `failproofai audit` CLI” with something like “Runs the same scan as
the /audit page” and remove or rephrase any “supported flags” wording (also
update the second occurrence of `failproofai audit` near the later paragraph) so
the dashboard text consistently directs users to the /audit page rather than
implying a runnable CLI subcommand.
---
Nitpick comments:
In `@app/audit/_components/top-audit-bar.tsx`:
- Around line 133-138: Remove the redundant null check by using only the
expiringSoon guard in the render: when expiringSoon is true it already implies
remainingMs !== null (computed earlier), so simplify the conditional from
"expiringSoon && remainingMs !== null && (...)" to "expiringSoon && (...)" in
the component that renders the expiry message (referencing expiringSoon,
remainingMs, timeUntilExpiry and cachedAtMs in top-audit-bar.tsx).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5eadd1bc-62e8-48ce-8cb9-b77352b3456d

📥 Commits

Reviewing files that changed from the base of the PR and between ec5c52e and 110edfc.

📒 Files selected for processing (18)

• CHANGELOG.md
• __tests__/audit/cache.test.ts
• __tests__/audit/dashboard-cache.test.ts
• __tests__/audit/top-audit-bar.test.tsx
• __tests__/lib/fetch-with-timeout.test.ts
• app/actions/get-audit-result.ts
• app/audit/_components/audit-dashboard.tsx
• app/audit/_components/audit-progress-strip.tsx
• app/audit/_components/rerun-button.tsx
• app/audit/_components/return-section.tsx
• app/audit/_components/top-audit-bar.tsx
• app/audit/audit-styles.css
• app/audit/page.tsx
• docs/cli/audit.mdx
• docs/dashboard.mdx
• lib/fetch-with-timeout.ts
• src/audit/cache.ts
• src/audit/dashboard-cache.ts