feat(api): add contributor notifications REST routes + CLI mirror

[galuis116]

Summary

• loopover_list_notifications and loopover_mark_notifications_read (MCP tools in src/mcp/server.ts) had no REST or CLI-accessible mirror. src/api/routes.ts had no contributor-facing notification-feed route -- only /v1/app/notification-model (a static describe-the-model endpoint) and the unrelated /v1/app/digest/subscriptions.
• Added GET /v1/contributors/:login/notifications and POST /v1/contributors/:login/notifications/read in src/api/routes.ts, reusing requireContributorAccess exactly as /v1/contributors/:login/profile and /decision-pack already do, and calling the same listNotificationDeliveriesForRecipient / buildNotificationFeed / markNotificationDeliveriesRead functions the MCP tools use so the two surfaces can never drift.
• Added two CLI subcommands, loopover-mcp notifications and loopover-mcp notifications-read, following the same login-resolution precedent as contributor-profile (--login / active session / LOOPOVER_LOGIN / GITHUB_LOGIN). notifications-read accepts repeated --id <id> flags to clear specific notifications, or clears everything when omitted.

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 #6745

Validation

• git diff --check
• npm run actionlint (no workflow changes in this PR)
• npm run typecheck
• npm run test:coverage locally (targeted: the new routes-notifications.test.ts (8 tests) and mcp-cli-notifications.test.ts (6 tests), plus the existing mcp-notifications.test.ts and mcp-cli-completion-spec.test.ts, all pass -- 79 tests total across the touched files)
• npm run test:workers (not applicable to this change)
• npm run build:mcp (not applicable to this change)
• npm run test:mcp-pack (not applicable to this change)
• npm run ui:openapi:check (this route is not part of the curated public OpenAPI surface, same as its sibling open-pr-monitor/decision-pack contributor routes)
• npm run ui:lint (no UI changes in this PR)
• npm run ui:typecheck (no UI changes in this PR)
• npm run ui:build (no UI changes in this PR)
• npm audit --audit-level=moderate (no dependency changes in this PR)
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• This PR only touches backend MCP-mirror REST/CLI surfaces plus their tests (no UI, workers, MCP package build, or dependency changes), so the UI-scoped and package-build checks above have no surface to exercise. npm run docs:drift-check, npm run manifest:drift-check, and npm run command-reference:check were also run locally and pass.

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. The new routes' tests cover: unauthenticated (401), a session reading another login's notifications (403 forbidden_contributor), and a successful self-scoped read/mark-read.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A -- no UI changes in this PR.)
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots. (N/A -- this PR has no UI/visual surface; it adds backend REST routes + a CLI mirror only.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• No UI Evidence table: this PR is backend-only (two REST routes plus a CLI mirror) with no visual surface to screenshot.

[superagent-security]

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

[codecov]

Codecov Report

❌ Patch coverage is 86.66667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.71%. Comparing base (4966070) to head (80bc8bb).

Files with missing lines	Patch %	Lines
src/api/routes.ts	86.66%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6969      +/-   ##
==========================================
- Coverage   93.71%   93.71%   -0.01%     
==========================================
  Files         686      686              
  Lines       68392    68407      +15     
  Branches    18730    18733       +3     
==========================================
+ Hits        64093    64106      +13     
  Misses       3302     3302              
- Partials      997      999       +2     

Flag	Coverage Δ
shard-1	43.74% <20.00%> (-0.01%)	⬇️
shard-2	36.98% <20.00%> (+0.05%)	⬆️
shard-3	32.83% <20.00%> (+0.02%)	⬆️
shard-4	34.25% <20.00%> (+0.39%)	⬆️
shard-5	31.96% <86.66%> (-0.17%)	⬇️
shard-6	45.75% <20.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/api/routes.ts	94.77% <86.66%> (-0.06%)	⬇️

[loopover-orb]

Caution

🛑 LoopOver review result - fixes required

_{Review updated: 2026-07-17 16:40:59 UTC}

5 files · 1 AI reviewer · no blockers · CI failing · unstable

🛑 Suggested Action - Fix Blockers

Review summary
This PR adds REST routes (GET/POST) mirroring existing MCP notification tools, plus matching CLI subcommands, closely following the established patterns for contributor-profile routes (requireContributorAccess, VERBATIM schema mirroring) and CLI login-resolution precedent. The implementation reuses existing service functions (listNotificationDeliveriesForRecipient, buildNotificationFeed, markNotificationDeliveriesRead) rather than duplicating logic, and includes solid test coverage across both the REST routes (auth, self-scoping, malformed JSON, over-cap validation) and CLI mirror (login resolution, encoding, --id repeats). The PR closes the linked issue #6745 and is well-scoped to just this feature.

Nits — 5 non-blocking

• src/api/routes.ts:3329 hardcodes a `limit: 50` for notification deliveries — consider naming this as a constant alongside MAX_NOTIFICATION_DELIVERY_ID_LENGTH for consistency with the other bounds mirrored from server.ts.
• codecov/patch is at 86.66% against a 99% target — worth checking which branches in the new CLI functions (notificationsCli/notificationsReadCli) or route handlers are untested, e.g. the plain-text (non-JSON) output branches.
• packages/loopover-mcp/bin/loopover-mcp.js:3742-3780 duplicates the login-resolution one-liner (`options.login ?? activeProfile.session?.login ?? ...`) verbatim in both new CLI functions and matches the existing contributorProfileCli pattern — consider factoring into a shared helper if a fourth command needs the same resolution, though this is consistent with existing repetition in the file so not blocking.
• Add a named constant (e.g. `NOTIFICATION_FEED_LIMIT = 50`) in src/api/routes.ts for the hardcoded limit to match the pattern of MAX_NOTIFICATION_DELIVERY_ID_LENGTH / MAX_NOTIFICATION_MARK_READ_IDS already imported.
• Consider adding a test asserting the plain-text (non --json) output format for `notifications-read` explicitly shows the marked count message, if not already covered.

CI checks failing

• codecov/patch — 86.66% of diff hit (target 99.00%)

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6745
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High 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: 1957 registered-repo PR(s), 1287 merged, 52 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	galuis116; Gittensor profile; 1957 PR(s), 52 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds both required routes (GET .../notifications and POST .../notifications/read) using requireContributorAccess exactly as the profile/decision-pack routes do, reuses the same MCP-backing functions, adds two CLI subcommands with matching login-resolution precedent, and includes unit tests for routes and CLI including a parity-oriented fixture.

Review context

• Author: galuis116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: JavaScript, Python, Dart, TypeScript, HTML, MDX, Rust, C++
• Official Gittensor activity: 1957 PR(s), 52 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (issue #6747, issue #6745)
• Related work: Items reference the same linked issue REST + CLI mirror for loopover_pr_outcome #6747. (issue #6747, PR #6963)
• Related work: Open PR work references issue REST + CLI mirror for loopover_pr_outcome #6747. (issue #6747, PR #6963)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Start here: Review top overlaps.
• Then work through the remaining 2 steps in the Signals table above.

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.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (CI is failing (codecov/patch)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.