feat: "Ran while you were away" card on /studies (feat_overnight_studies_summary_card)

[SoundMindsAI]

Summary

Ships the "Ran while you were away" card on /studies — the index-page surface for the overnight autopilot (the chain panel + <OvernightResultCard> already cover the detail page).

• Backend — new read-only discovery endpoint GET /api/v1/studies/chains/recent returning the deduplicated set of recently-completed overnight chains (length ≥ 2, terminal, optional ?since= cutoff). Repo helper list_recent_completed_chains reuses the Phase 1 get_chain_for_study traversal and derive_chain_stop_reason — no chain math is re-derived. Inert pagination per OQ-2 (next_cursor: null, has_more: false, X-Total-Count = len(data)).
• Frontend — new RecentChainsCard component above the studies table, owning its own data via two new hooks: useRecentChains(since) (TanStack) and useStudiesVisited() (localStorage, +1ms exclusive dismissal nudge per FR-5). Stop-reason phrasing reuses CHAIN_STOP_REASON_PHRASE from ui/src/lib/chain-stop-reason.ts — the same map shipped with feat_overnight_final_solution_phase2, so the card and the chain panel never drift. New recent_chains_card glossary key.
• Tests — 7 integration (Story 1.1 repo helper) + 4 integration (Story 1.2 endpoint) + 9 contract (Story 1.2 response shape + 422 envelope) + 4 vitest (Story 2.1 hook) + 8 vitest (Story 2.2 card) + 2 Playwright (Story 3.1 E2E, smoke-job opt-in). Full UI suite green (1115 vitest).
• Docs — api-conventions.md + ui-architecture.md updated per Story 3.2.

No migration. All chain math is derived from existing schema; Alembic head stays at 0022_solr_engine_auth_check.

Verdict tables (cross-model adjudication)

GPT-5.5 Epic 1 review (1 finding)

#	Sev	Location	Verdict	Notes
1	Medium	backend/app/api/v1/studies.py:631	Rejected	Claimed select_best_link returns a link object. Counter-evidence: backend/app/domain/study/chain_summary.py:212 typed `-> str

GPT-5.5 Epic 2 review (2 findings)

#	Sev	Location	Verdict	Notes
1	Medium	ui/src/components/studies/recent-chains-card.tsx:57	Accepted	Fixed in 057c6168 — replaced ?? row.stop_reason raw-enum fallback with ?? 'Chain stopped' so a forward-compat backend drift renders a generic phrase instead of leaking the raw wire value.
2	Medium	ui/src/components/studies/recent-chains-card.tsx:58	Rejected	Claimed the null-metric gate should include cumulative_lift. Counter-evidence: plan §3 Story 2.2 inventory + §11.4 consistency review gate the null branch on best_metric === null only; the existing chain panel at auto-followup-chain-panel.tsx:259 renders formatSignedLift returning "—" for null lift, which is the project's universal null-cell convention. My code matches the planned gate verbatim.

Test plan

• make lint && make typecheck (backend, clean)
• ./.venv/bin/ruff format --check backend/ (573 files formatted)
• Backend unit tests: 2224 passed
• Backend integration (make test-worktree): 8 + 4 new tests pass (Story 1.1 repo + Story 1.2 endpoint)
• Backend contract: 9 new tests pass (Story 1.2)
• Frontend pnpm test — 1115 vitest passed (151 files)
• Frontend pnpm typecheck — clean
• Frontend pnpm lint — 0 errors (176 pre-existing warnings)
• Frontend pnpm build — clean (/studies still ○ static)
• Smoke E2E job — SMOKE_TEST is OFF by default per state.md. The new spec at ui/tests/e2e/recent-chains-card.spec.ts typechecks; runtime green is gated on operator opt-in (gh variable set SMOKE_TEST --body true).
• Manual visual check on /studies after merge — does the card render correctly with seeded chains?

Deferred work captured (per plan §1)

Two 99_backlog/ idea files filed for the spec's open questions (defer-until-incident):

• chore_studies_chain_recent_indexes — OQ-3 deferral, Postgres indexes on studies.parent_study_id + studies.completed_at once the discovery query becomes hot.
• chore_studies_chain_recent_keyset_pagination — OQ-2 deferral, real keyset pagination once an operator clips the fixed 50-row cap.

Guide impact

Guide 06 (Create and monitor a study) captures 01-studies-list.png of /studies. The new RecentChainsCard renders above the table when there are recent terminated chains; the Acme seed in guide 06's setup may or may not trigger the card depending on chain tail vs the 7-day default cutoff. Flagged for operator-decided regen — the card is deterministic enough that the operator can choose to capture it (and localStorage.setItem a known cutoff) or hide it (set the cutoff to now).

Notes

Commit 04732efd docs(planned): idea — walkthrough guides on public website (relyloop.com) landed on this branch from a parallel session — it's an unrelated planned-feature idea file. Disclosing rather than reverting (the commit is coherent on its own).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements the 'Ran while you were away' feature, introducing a new backend endpoint GET /api/v1/studies/chains/recent and a frontend <RecentChainsCard> component to display recently completed overnight chains. Feedback on the backend highlights an N+1 query pattern in the chain discovery repository helper, suggesting a set-based tracking mechanism to skip redundant traversals. On the frontend, the reviewer identified a potential hydration mismatch in Next.js caused by reading from localStorage during the initial render of the useStudiesVisited hook, recommending a useEffect approach for SSR safety along with defensive validation of the retrieved date string.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current implementation of list_recent_completed_chains suffers from an N+1 query pattern. It iterates over all candidate IDs and calls get_chain_for_study for each one. Since multiple candidates can belong to the same chain, this results in redundant database queries and traversal calculations for the same chain. Keeping track of already traversed study IDs in a set allows us to skip redundant calls entirely, significantly improving performance.

    by_anchor: dict[str, ChainTraversalResult] = {}
    seen_study_ids: set[str] = set()
    for candidate_id in candidate_ids:
        if len(by_anchor) >= limit:
            break
        if candidate_id in seen_study_ids:
            continue
        traversal = await get_chain_for_study(db, candidate_id)
        if traversal is None:
            # Concurrent hard-delete between candidate query and traversal
            # (e.g. test teardown). Skip silently per Story 1.1 task 5.
            continue
        seen_study_ids.update(lk.id for lk in traversal.links)

[gemini-code-assist]

Import useEffect to handle reading from localStorage safely after mount, preventing hydration mismatches.

Suggested change

	import { useCallback, useState } from 'react';
	import { useCallback, useEffect, useState } from 'react';

[gemini-code-assist]

Initializing state directly from localStorage during the initial render causes a hydration mismatch in Next.js because the server renders with defaultSince() while the client hydrates with the value from localStorage. To ensure SSR safety, initialize the state to defaultSince() and update it in a useEffect hook on mount.

Suggested change

	export function useStudiesVisited(): UseStudiesVisitedResult {
	// Hydrate synchronously via the useState initializer — matches the
	// pattern in useLocalStorageSet (no extra render cycle, safe under
	// SSR because readVisitedAt() guards on `typeof window`).
	const [since, setSince] = useState<string>(() => readVisitedAt());
	export function useStudiesVisited(): UseStudiesVisitedResult {
	const [since, setSince] = useState<string>(() => defaultSince());
	useEffect(() => {
	setSince(readVisitedAt());
	}, []);

[gemini-code-assist]

Defensively validate the value retrieved from localStorage to ensure it is a valid date string before returning it. This prevents sending malformed parameters to the backend and triggering 422 errors.

Suggested change

	function readVisitedAt(): string {
	if (typeof window === 'undefined') return defaultSince();
	try {
	const raw = window.localStorage.getItem(STORAGE_KEY);
	if (raw) return raw;
	} catch {
	// Private browsing / quota / corrupt — fall back to default.
	}
	return defaultSince();
	}
	function readVisitedAt(): string {
	if (typeof window === 'undefined') return defaultSince();
	try {
	const raw = window.localStorage.getItem(STORAGE_KEY);
	if (raw && !Number.isNaN(Date.parse(raw))) return raw;
	} catch {
	// Private browsing / quota / corrupt — fall back to default.
	}
	return defaultSince();
	}

[SoundMindsAI]

Review adjudication (Gemini Code Assist)

Commits landing fixes: fa8a13f5

Gemini Code Assist (4 findings)

#	Sev	Location	Verdict	Notes
1	High	backend/app/db/repo/study.py:458	Accepted	Fixed in fa8a13f5 — added seen_study_ids set so candidates belonging to a chain already resolved skip the redundant get_chain_for_study call. Worst case for a 6-link chain drops from 6 traversal calls to 1. Dedup outcome unchanged.
2	High	ui/src/hooks/use-studies-visited.ts:34	Rejected	Paired with finding #3 — would add a useEffect import only if #3 was accepted. Rejected as a consequence of #3 being rejected.
3	High	ui/src/hooks/use-studies-visited.ts:72	Rejected	Claimed SSR hydration mismatch from reading localStorage in the useState initializer. Counter-evidence: (a) the card returns null while query.data is undefined (isPending) — the DOM output is identical on server (no fetch) and on the client's initial render, so no hydration mismatch is possible; (b) the useState-initializer + typeof window === 'undefined' guard pattern is the project's established convention — ui/src/hooks/use-local-storage-set.ts:46-48 uses the same shape with the documented comment "Safe under SSR because the read function checks typeof window." Accepting #3 would diverge from the established codebase pattern.
4	Medium	ui/src/hooks/use-studies-visited.ts:52	Accepted	Fixed in fa8a13f5 — added !Number.isNaN(Date.parse(raw)) guard so a corrupt localStorage value (operator manual edit, older-release shape) doesn't propagate to GET /api/v1/studies/chains/recent?since=<garbage> and 422 every request until localStorage is cleared.

Outcomes

• Applied fixes (2): backend N+1 elimination + frontend defensive Date.parse guard
• Rejected with cited counter-evidence (2): both hydration-mismatch claims (docs: MVP1 architecture + 12 feature specs + GPT-5.5 review fixes #2 + chore(pipeline): add project-wide priority-ordered status mode #3) — pattern matches established use-local-storage-set.ts convention; card renders null during pending so no DOM mismatch

Ready for human review + merge.

[SoundMindsAI]

Final cross-model review (GPT-5.5)

Convergence note: 0 findings — clean pass.

Reviewed: full PR diff (git diff origin/main..HEAD, 542 lines across backend repo/endpoint/schema, frontend hooks/card/page, glossary, tests, docs, deferred-work idea files).

Rejection log carried forward from prior phases (Epic 1 + Epic 2 GPT-5.5, Gemini #2/#3) was supplied as a no-re-raise hint; final review found no new High/Medium issues to surface and did not re-raise any rejected findings.

CI is green on fa8a13f5 (the head after Gemini fixes). Ready for human review + merge.