feat(notifications): schedule the maintainer recap job on a configurable cadence

[oktofeesh1]

Summary

• Adds the cron trigger for the cross-repo maintainer recap digest (Maintainer review recap digest (Discord / Slack) #1963): a new generate-maintainer-recap job type, gated behind GITTENSORY_MAINTAINER_RECAP (default off), enqueues on a configurable GITTENSORY_RECAP_CADENCE=daily|weekly cadence (default weekly, GITTENSORY_RECAP_HOUR/GITTENSORY_RECAP_DAY pick when) — following the exact isHourly/hour/getUTCDay enqueue idiom already used for generate-weekly-value-report and prune-retention.
• The job's processor (runMaintainerRecapJob, src/review/maintainer-recap-wire.ts) scans registered (preferring agent-configured) repos, folds each repo's already-computed gate-precision + outcome-calibration reports into one RecapReport via the existing buildMaintainerRecap (feat(notifications): pure maintainer-recap builder — aggregate review activity into a RecapReport #2239), and delivers it through the existing deliverRecapToDiscord (feat(notifications): Discord delivery for the maintainer recap digest (reuse discord-notify) #2245). A per-repo aggregator failure is logged and skipped so one repo's D1 hiccup never blanks the whole digest, mirroring ops-wire.ts's runOpsAlerts.
• Closes feat(notifications): schedule the recap job on the cron with a configurable cadence knob #2248.

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.
• I linked a currently open issue this PR resolves — Closes #2248.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — 100% branch coverage on every changed line (verified via lcov.info against the diff).
• 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 — see below.
• Full npm run test:ci green (both before and after rebasing onto the latest main).

Test coverage added:

• test/unit/maintainer-recap-wire.test.ts: isRecapEnabled on/off convention; shouldFireMaintainerRecap cadence gate — default weekly (Monday 14:00 UTC) fires only there, explicit weekly, daily cadence (fires every day, ignores day-of-week), an invalid cadence value falling back to weekly (not daily), custom hour/day-of-week, out-of-range (but finite) hour/day clamping, non-finite hour/day falling back to the default; runMaintainerRecapJob — cross-repo aggregation across multiple repos, default vs. custom windowDays threaded through, preferring agent-configured repos over the full registered set, falling back to every registered repo when settings resolution errors for every repo (a settings blip must not abort the scan), a per-repo aggregator failure being logged/skipped without aborting the job, and still delivering a zeroed report when there are no registered repos.
• test/unit/index.test.ts: the cron enqueues the job only when the flag is on and the cadence tick matches (flag-off is byte-identical), does not enqueue outside the configured cadence, and honors a custom daily cadence.
• test/unit/queue.test.ts: the processor runs the job end-to-end (through to a real Discord audit row) when the flag is on, and no-ops (no fetch, no audit row) when the flag is off — mirroring the existing generate-review-recap processor tests.

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/CORS/session surface touched.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP surface changed; internal job/queue only.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no UI changes.)
• Visible UI changes include a UI Evidence section. (N/A — no visible UI changes; backend-only.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (N/A — no changelog edit.)

UI Evidence

N/A — backend-only change (cron scheduling + queue processor), no UI surface touched.

Notes

• Default OFF (GITTENSORY_MAINTAINER_RECAP=false): the cron enqueues zero new work and the worker is byte-identical to today until an operator opts in.

[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 93.97%. Comparing base (3e4df6d) to head (6a8cf27).
⚠️ Report is 24 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4418   +/-   ##
=======================================
  Coverage   93.96%   93.97%           
=======================================
  Files         401      402    +1     
  Lines       36913    36954   +41     
  Branches    13497    13507   +10     
=======================================
+ Hits        34687    34729   +42     
  Misses       1570     1570           
+ Partials      656      655    -1     

Files with missing lines	Coverage Δ
src/index.ts	95.06% <100.00%> (+0.12%)	⬆️
src/queue/processors.ts	95.37% <100.00%> (+<0.01%)	⬆️
src/review/maintainer-recap-wire.ts	100.00% <100.00%> (ø)
src/selfhost/maintenance-admission.ts	100.00% <ø> (ø)
src/types.ts	100.00% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 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-09 17:23:50 UTC}

11 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/queue/processors.ts (matched src/queue/**), src/selfhost/maintenance-admission.ts (matched src/selfhost/**), wrangler.jsonc (matched wrangler.jsonc), wrangler.jsonc (matched **/wrangler.jsonc).

Review summary
Adds a cron-scheduled cross-repo maintainer recap digest, closely mirroring the existing selftune-wire.ts/ops-wire.ts conventions (flag-gated default-OFF, per-repo fail-safe try/catch, defense-in-depth re-check of the flag in the queue processor for stale in-flight jobs). The enqueue/cadence logic (isHourly + shouldFireMaintainerRecap) is well isolated and thoroughly unit tested including invalid-cadence fallback and hour/day clamping, and wiring into JobMessage, processors.ts, maintenance-admission.ts, and wrangler.jsonc/worker-configuration.d.ts is consistent and complete for the flag-off byte-identical claim.

Nits — 6 non-blocking

• src/review/maintainer-recap-wire.ts:29-38 normalizeRecapHour/normalizeRecapDayOfWeek treat an empty-string env value (`Number("") === 0`) as a valid hour/day of 0 rather than falling back to the default, so `GITTENSORY_RECAP_HOUR=""` silently fires at hour 0 instead of the documented default of 14 — worth an explicit `value === undefined || value === ""` check.
• The PR description marks issue feat(notifications): schedule the recap job on the cron with a configurable cadence knob #2248 coverage as only partial per the linked-issue check; worth confirming the issue's full acceptance criteria are met before merge.
• src/review/maintainer-recap-wire.ts:110 console.warn truncates the error message to 200 chars like ops-wire.ts/selftune-wire.ts — consistent with the existing pattern, not a real defect, but flagged by tooling as a possible debug leftover so worth a one-line comment noting it's intentional structured logging.
• src/review/maintainer-recap-wire.ts's recapScanRepos duplicates selfTuneRepos' agent-configured-with-fallback logic almost verbatim (minus the manifest opt-out check) — consider extracting a shared helper if a third caller shows up.
• Consider hardening normalizeRecapHour/normalizeRecapDayOfWeek against empty-string env values as noted above.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2248
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 (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 30 registered-repo PR(s), 23 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	oktofeesh1; Gittensor profile; 30 PR(s), 0 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR adds the recap enqueue block in scheduled() gated on isRecapEnabled/isHourly/hour/getUTCDay exactly as specified, implements a validated GITTENSORY_RECAP_CADENCE=daily|weekly knob with clamped hour/day-of-week (normalizeRecapCadence/Hour/DayOfWeek) defaulting safely, and includes a comprehensive unit test suite for shouldFireMaintainerRecap covering daily, weekly, invalid-value fallback, an

Review context

• Author: oktofeesh1
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: JavaScript, MDX, Python, TypeScript
• Official Gittensor activity: 30 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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