Context

Sub of #10214. See parent epic for architectural rationale. This ticket focuses on the implementation delta for Sub 4 — enriching the github-workflow MCP server's healthcheck response with a notificationPreview field.

The Problem

Agents have GitHub accounts (@neo-opus-4-7, @neo-gemini-3-1-pro) and receive @mention notifications, but no consistent primitive surfaces inbound-from-external-world signal. A human or external contributor @mentioning an agent in a ticket comment currently lands in GH's notification feed — agent never discovers it within the session.

Naive solution: standalone polling skill ("run list_notifications at boot"). Rejected — the memory-core server already solved the analogous problem with mailboxPreview in its healthcheck response: passive signal surfaced on every boot-time call, zero new discipline. Same pattern applies here.

The Architectural Reality

Precedent — neo-mjs-memory-core healthcheck returns (per session observation):

{
  "status": "healthy",
  "mailboxPreview": { "unreadCount": 0, "latestPreview": null }
}

GitHub API: GET /notifications — returns up to 50 most-recent notifications. Query params include participating (subscription-triggered only), and notifications carry a reason field: mention, assign, review_requested, author, comment, subscribed, manual, team_mention, etc.

Noise discipline: default filter MUST be reason=mention. GitHub fires notifications on every subscription-worthy activity — author / comment / subscribed reasons are high-noise (fires on every peer activity on touched threads). Mention is authoritative ("someone wants this specific agent").

The Fix

1. Extend github-workflow MCP server's healthcheck handler:
   • Call GET /notifications filtered to reason=mention by default (configurable via aiConfig.githubWorkflow.notificationFilter — default ['mention'], opt-in expansion to ['mention', 'assign', 'review_requested'])
   • Build notificationPreview object:

          {
       "unreadMentionsCount": <count>,
       "latestMention": {
         "repo": "neomjs/neo",
         "url": "https://github.com/neomjs/neo/pull/10211#issuecomment-...",
         "title": "Re-Review — Post Follow-up",
         "mentionedBy": "@tobiu",
         "threadType": "pull_request" | "issue" | "discussion",
         "unread": true
       }
     }

   • Return alongside existing healthcheck fields — mirrors memory-core's mailboxPreview shape.
2. Default filter: only reason=mention. Config exposes the opt-in to include assign + review_requested.
3. Excluded by default: author, comment, subscribed, manual, team_mention (too noisy for the boot-time signal).
4. Document the field + filter defaults in the server's OpenAPI spec + learn/agentos/GitHubWorkflow.md (or equivalent).

Acceptance Criteria

• github-workflow healthcheck tool returns notificationPreview with unreadMentionsCount + latestMention structure
• Default filter: reason=mention only; documented config for opt-in expansion
• OpenAPI spec updated
• Integration test verifies: with no unread mentions → unreadMentionsCount: 0, latestMention: null; with unread mentions → populated preview

Out of Scope

• Event-driven webhook integration — polling via healthcheck is phase 1; webhooks require hosting and are separate future work
• Bi-directional bridge from GH notifications to memory-core mailbox (write-path) — valuable follow-up but separate surface; file after this ticket lands
• Notification-read tracking / mark_as_read API — read-only probe for now; mutating notifications is out of scope
• UI for browsing full notification list — out of scope; healthcheck provides the "there is signal, go look" indicator

Avoided Traps

• Raw polling without filter — rejected. Default reason=mention prevents drowning in peer-activity noise.
• Polling as a separate skill-level discipline — rejected. Piggybacking on existing healthcheck avoids introducing a new boot-time primitive.
• Including author / comment reasons — fires on every activity in any thread the agent has touched; pure noise.

Related

• Parent epic: #10214
• Pattern precedent: memory-core healthcheck → mailboxPreview (already in production)
• Complementary: #10139 mailbox A2A (internal inbound); this ticket handles external inbound
• Follow-up candidate: GH notification → memory-core mailbox bridge (unified INBOX across channels)

Handoff Retrieval Hints

• query_raw_memories(query="notificationPreview github-workflow healthcheck reason=mention")
• query_raw_memories(query="inbound channel external mention polling vs healthcheck enrichment")
• query_summaries(query="GitHub notification MCP server healthcheck")

Known contributing sessions:

• ae546a40-2133-482f-85a6-779fdf6757b2 (epic authoring session; contains the healthcheck-enrichment design insight)