feat(review): capture review turnaround duration onto the publish audit event (#4446)

[JSONbored]

Summary

• First slice of feat(stats): review turnaround-time tracking (webhook received → comment posted), public + historical #4446 (part of epic Epic: public, tracked-over-time benchmarks for gittensory's own review engine (speed, accuracy trend, efficiency) #4445): captures a per-PR review turnaround duration (reviewDurationMs) onto the existing github_app.pr_public_surface_published audit event, reusing the startedAt timestamp activeReviewTracking already records for review-evasion protection.
• New getActiveReviewStartedAt(env, repoFullName, pullNumber, headSha) (src/db/repositories.ts) reads that row, matched to the exact headSha being published so a race with a newer pass degrades to "no duration" rather than a wrong number.
• New pure, exported reviewDurationMsSince(startedAt, nowMs) (src/queue/processors.ts) clamps the computed duration to a sane non-negative finite value — a clock-skew/future timestamp or unparseable string degrades to undefined rather than ever reaching the public payload with a negative or NaN value.
• Mirrors the exact precedent reviewEffortMinutes already set at the same call site: a raw per-PR number conditionally spread into the same audit event's metadata, to be aggregated by a rollup job later.
• The daily p50/p95 rollup, cron wiring, GET /v1/public/stats extension, and homepage trend chart are deliberately deferred to follow-up PRs — this slice only lands the capture, so there's real data to aggregate once those land.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• Advances feat(stats): review turnaround-time tracking (webhook received → comment posted), public + historical #4446 (part of epic Epic: public, tracked-over-time benchmarks for gittensory's own review engine (speed, accuracy trend, efficiency) #4445) — a partial slice, not the full deliverable, so this does not close the issue.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — 100% line/branch coverage on the diff (including the future-timestamp/clock-skew and unparseable-string branches, and the .catch() fail-safe path)
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate — 0 vulnerabilities
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — N/A, no auth/session surface touched.
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A, this slice adds no new public API surface (the reviewDurationMs field lands in a private audit-event payload, not a public response).
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A, backend-only change.
• Visible UI changes include a UI Evidence section. — N/A, backend-only change, no visible UI.
• Public docs/changelogs are updated where needed. — N/A, no public-facing behavior changed yet (deferred to the API/frontend follow-up PR).

Notes

• Read-site placement inside maybePublishPrPublicSurface is deliberately AFTER startActiveReviewTracking and the AI-review section both run in the same pass (confirmed via finishPublicSurfacePublication's actual call site, not its earlier definition line).

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.11%. Comparing base (2234cb7) to head (14cfa54).
⚠️ Report is 8 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4635   +/-   ##
=======================================
  Coverage   94.11%   94.11%           
=======================================
  Files         432      432           
  Lines       38370    38379    +9     
  Branches    13989    13994    +5     
=======================================
+ Hits        36113    36122    +9     
  Misses       1600     1600           
  Partials      657      657           

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.61% <100.00%> (+<0.01%)	⬆️
src/queue/processors.ts	95.39% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-10 08:54:54 UTC}

4 files · 1 AI reviewer · 2 blockers · readiness 93/100 · CI green · unknown

⏸️ Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Review summary
This adds reviewDurationMs to the pr_public_surface_published audit event by reading the existing activeReviewTracking.startedAt row (matched to the exact headSha being published) and clamping the elapsed time through a small pure function, reviewDurationMsSince, that degrades clock-skew and unparseable timestamps to undefined rather than a negative or NaN value. It mirrors the established reviewEffortMinutes precedent at the same call site, touches no schema, and every named edge case (future timestamp, bad string, cross-pass headSha race, lookup failure) has a real regression test that exercises the actual processJob call path rather than a fabricated payload.

Nits — 4 non-blocking

• src/db/repositories.ts:5312 reuses boundedString(repoFullName, 200) from the adjacent pre-existing hasActiveReviewForHeadSha — the 200 isn't new to this diff, but if you ever want to name it, a shared REPO_FULL_NAME_MAX_LEN constant would remove the duplication between the two functions.
• The external brief's 'leaked secret' flags at queue.test.ts:4045/4080/4114 are false positives — they're `GITHUB_APP_PRIVATE_KEY: await generatePrivateKeyPem()`, the same test-key-generation helper already used elsewhere in this suite, not a real credential.
• Consider a one-line JSDoc-style note on getActiveReviewStartedAt's exported signature restating that it's intentionally not gated on status==='active' (the inline comment already explains it, but it's an easy invariant for a future reader to accidentally 'fix' by adding a status filter).
• Since this is explicitly the capture-only slice of feat(stats): review turnaround-time tracking (webhook received → comment posted), public + historical #4446, it'd be worth a one-line TODO or issue cross-reference near reviewDurationMsForStats pointing at the follow-up rollup PR so the raw-metadata-only state doesn't look abandoned to a future reader.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 48 registered-repo PR(s), 40 merged, 334 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 48 PR(s), 334 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 48 PR(s), 334 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review