Context
PR #12775 added Knowledge Base runtimeFreshness healthcheck observability after the stale-MCP/tool-schema incident under #12740. During review prep, @neo-opus-vega and @neo-opus-grace both flagged the same architectural smell: runtime freshness logic now exists independently in three MCP healthcheck services after #12766, #12773, and #12775.
This ticket captures the follow-up deliberately instead of widening #12775 after review was requested.
Live latest-open sweep: checked 80 open issues on 2026-06-08; saw #12774, #12772, #12768, #12748, #12747, #12746, #12743, and parent #12740, but no equivalent shared runtimeFreshness helper/consolidation issue.
Local exact sweep: rg "runtimeFreshness|runtime freshness|classifyRuntimeFreshness|stale MCP|MCP runtime" resources/content/issues resources/content/discussions .agents learn ai found the three source implementations plus older stale-MCP/healthcheck tickets, but no duplicate consolidation ticket.
Semantic KB ticket sweep: query_documents(query='runtimeFreshness shared helper MCP healthcheck', type='ticket', limit=10) returned older/noisy healthcheck tickets (#10783, #12382, #10896, #10127, #10918), none equivalent to shared runtimeFreshness helper extraction.
The Problem
The runtime freshness pattern is now duplicated across MCP services:
ai/services/github-workflow/HealthService.mjs owns boot/current identity comparison for GitHub Workflow.ai/services/memory-core/HealthService.mjs owns the parallel Memory Core shape.ai/services/knowledge-base/HealthService.mjs owns the Knowledge Base shape from #12775.
The duplicate logic already produced review friction: compact output shape, current-identity caching, and gitHead stale-signal symmetry needed to be reasoned about separately per PR. If left duplicated, future agents can drift the stale-classification semantics or reintroduce per-healthcheck git/hash work in one service while another service remains lean.
The Architectural Reality
Runtime freshness is MCP-server infrastructure, not a Knowledge Base, Memory Core, or GitHub Workflow domain feature. The likely shared substrate is ai/mcp/server/shared/services/, which already contains cross-MCP services such as RequestContextService.mjs, AuthService.mjs, and TransportService.mjs.
Structural Pre-Flight: future authoring of ai/mcp/server/shared/services/RuntimeFreshnessService.mjs qualifies for the structural fast-path: it matches the sibling pattern of shared MCP services in ai/mcp/server/shared/services/; sibling-file-lift applies; no novel directory choice. Map maintenance: not needed unless the implementation introduces a new directory or a broader runtime subsystem description.
The Fix
Extract the runtime freshness helper/service behind one shared module and migrate the three existing consumers to it.
Expected shape:
- Shared module owns file digest helpers, boot identity capture, current identity read/caching, compact stale classification, and test seams.
- Each consumer provides only service-specific inputs: root directory, relevant identity files, service display name, and restart hint text.
- Consumer
HealthService classes stay responsible for their own dependency health semantics; runtimeFreshness.status === 'stale' remains diagnostic metadata, not a top-level health failure.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
runtimeFreshness healthcheck block |
Existing #12766/#12773/#12775 healthcheck surfaces |
Shared helper returns compact {status, startedAt, stale, details, hint}-style diagnostics without public boot/current identity echo |
If identity cannot be compared, return status: 'unknown' with diagnostic detail |
OpenAPI schemas for each MCP server |
Focused unit coverage for helper + migrated consumers |
| Current identity read/cache |
#12775 peer-review feedback |
Avoid git/hash work on every cached healthcheck call; use a short runtimeFreshness TTL or equivalent cache-miss strategy |
Test seam can bypass cache or set TTL to zero |
JSDoc in shared helper |
Unit test proves cache reuse and refresh behavior |
| Service-specific identity inputs |
HealthService consumers |
Each service passes its own root path and relevant files; no hidden fallback values or cross-service path assumptions |
Missing file/root produces unknown, not throw |
JSDoc in consumer wiring |
Unit tests for missing identity reads |
gitHead stale semantics |
Peer review on #12766/#12773/#12775 |
Decide once whether gitHead is a stale trigger, contextual detail, or scoped out in favor of service-owned digests |
Document rationale in helper JSDoc and tests |
PR body + helper JSDoc |
Tests showing unrelated-field behavior |
Decision Record impact
Aligned with ADR 0019 by keeping provider/config ownership in the resolved service inputs instead of re-exporting or aliasing aiConfig. No ADR amendment expected unless the implementation changes runtime freshness semantics across service boundaries beyond helper extraction.
Acceptance Criteria
Out of Scope
- Changing the top-level health semantics for any MCP server.
- Adding a new MCP tool.
- Solving post-merge harness restart automation.
- Reopening the #12775 Knowledge Base runtime freshness implementation unless the shared extraction requires a mechanical migration.
Related
Retrieval Hint: "runtimeFreshness shared helper MCP healthcheck classifyRuntimeFreshness gitHead stale semantics"
Context
PR #12775 added Knowledge Base
runtimeFreshnesshealthcheck observability after the stale-MCP/tool-schema incident under #12740. During review prep, @neo-opus-vega and @neo-opus-grace both flagged the same architectural smell: runtime freshness logic now exists independently in three MCP healthcheck services after #12766, #12773, and #12775.This ticket captures the follow-up deliberately instead of widening #12775 after review was requested.
Live latest-open sweep: checked 80 open issues on 2026-06-08; saw #12774, #12772, #12768, #12748, #12747, #12746, #12743, and parent #12740, but no equivalent shared runtimeFreshness helper/consolidation issue.
Local exact sweep:
rg "runtimeFreshness|runtime freshness|classifyRuntimeFreshness|stale MCP|MCP runtime" resources/content/issues resources/content/discussions .agents learn aifound the three source implementations plus older stale-MCP/healthcheck tickets, but no duplicate consolidation ticket.Semantic KB ticket sweep:
query_documents(query='runtimeFreshness shared helper MCP healthcheck', type='ticket', limit=10)returned older/noisy healthcheck tickets (#10783, #12382, #10896, #10127, #10918), none equivalent to shared runtimeFreshness helper extraction.The Problem
The runtime freshness pattern is now duplicated across MCP services:
ai/services/github-workflow/HealthService.mjsowns boot/current identity comparison for GitHub Workflow.ai/services/memory-core/HealthService.mjsowns the parallel Memory Core shape.ai/services/knowledge-base/HealthService.mjsowns the Knowledge Base shape from #12775.The duplicate logic already produced review friction: compact output shape, current-identity caching, and
gitHeadstale-signal symmetry needed to be reasoned about separately per PR. If left duplicated, future agents can drift the stale-classification semantics or reintroduce per-healthcheck git/hash work in one service while another service remains lean.The Architectural Reality
Runtime freshness is MCP-server infrastructure, not a Knowledge Base, Memory Core, or GitHub Workflow domain feature. The likely shared substrate is
ai/mcp/server/shared/services/, which already contains cross-MCP services such asRequestContextService.mjs,AuthService.mjs, andTransportService.mjs.Structural Pre-Flight: future authoring of
ai/mcp/server/shared/services/RuntimeFreshnessService.mjsqualifies for the structural fast-path: it matches the sibling pattern of shared MCP services inai/mcp/server/shared/services/; sibling-file-lift applies; no novel directory choice. Map maintenance: not needed unless the implementation introduces a new directory or a broader runtime subsystem description.The Fix
Extract the runtime freshness helper/service behind one shared module and migrate the three existing consumers to it.
Expected shape:
HealthServiceclasses stay responsible for their own dependency health semantics;runtimeFreshness.status === 'stale'remains diagnostic metadata, not a top-level health failure.Contract Ledger Matrix
runtimeFreshnesshealthcheck block{status, startedAt, stale, details, hint}-style diagnostics without publicboot/currentidentity echostatus: 'unknown'with diagnostic detailHealthServiceconsumersunknown, not throwgitHeadstale semanticsgitHeadis a stale trigger, contextual detail, or scoped out in favor of service-owned digestsDecision Record impact
Aligned with ADR 0019 by keeping provider/config ownership in the resolved service inputs instead of re-exporting or aliasing
aiConfig. No ADR amendment expected unless the implementation changes runtime freshness semantics across service boundaries beyond helper extraction.Acceptance Criteria
classifyRuntimeFreshness/digest/cache implementations.boot/currentidentity objects.gitHeadstale-signal policy is decided once and covered by tests.Out of Scope
Related
Retrieval Hint: "runtimeFreshness shared helper MCP healthcheck classifyRuntimeFreshness gitHead stale semantics"