PR #13568 (Resolves #13560) added the assertConfigFresh fail-fast boot-guard but wired it into only the 2 entrypoints that crashed in the embed-drain recovery session — the orchestrator daemon + the memory-core MCP server. @neo-opus-grace's #13568 review (Depth-Floor challenge) correctly flagged that the same stale-overlay crash class hits the other boot entrypoints. assertConfigFresh already accepts {serverPath}, so this is a call-site fan-out, not a redesign.
The Problem — V-B-A'd boot surface (2026-06-19)
Verified the actual entrypoints + which materialize a config overlay (ls ai/{daemons,mcp/server}/*/{daemon,mcp-server}.mjs + config.template.mjs):
MCP servers with a per-server config.mjs overlay — each a distinct stale-overlay crash surface — UNGUARDED:
ai/mcp/server/github-workflow/mcp-server.mjs
ai/mcp/server/gitlab-workflow/mcp-server.mjs
ai/mcp/server/knowledge-base/mcp-server.mjs
ai/mcp/server/neural-link/mcp-server.mjs — NB: grace's review named a "bridge daemon" at ai/daemons/bridge/daemon.mjs; that path does not exist. The bridge lives under neural-link (run-bridge.mjs / Bridge.mjs). Verify whether run-bridge.mjs boots independently of mcp-server.mjs and guard it too if so.
Daemons — no per-server overlay; each loads the top-level ai/config.mjs (Tier-1) as an independent process that can crash on a stale Tier-1 overlay — UNGUARDED except orchestrator:
ai/daemons/wake/daemon.mjs
ai/daemons/embed/daemon.mjs
ai/daemons/kb-alerting/daemon.mjs
ai/daemons/kb-gc/daemon.mjs
ai/daemons/kb-reconciliation/daemon.mjs
(orchestrator already guarded by #13568, via assertConfigFresh() with no serverPath = Tier-1.)
Acceptance Criteria
AC1 — overlay MCP servers: each unguarded overlay server (github-workflow, gitlab-workflow, knowledge-base, neural-link) calls assertConfigFresh({serverPath}) in its process-entry path before construct, mirroring memory-core's #13568 placement.
AC2 — Tier-1 daemons: each unguarded daemon (wake, embed, kb-alerting, kb-gc, kb-reconciliation) calls assertConfigFresh() (Tier-1) in its import.meta.url entry block, mirroring orchestrator's #13568 placement; the daemon's start* fn stays guard-free for test isolation.
AC3 — bridge:ai/mcp/server/neural-link/run-bridge.mjs checked — if it boots independently of mcp-server.mjs, it gets its own guard.
AC4 — isolation invariant: each guard fires only in the process-entry path (not on import), preserving the unit-test isolation #13568 established. Husky + CI green.
AC5 — file-system:ai/mcp/server/file-system/mcp-server.mjs verified (no config.template.mjs overlay found → either documented skip, or guard if it has a Tier-1 boot path).
Out of Scope
The assertConfigFresh detection logic + signature (unchanged — pure call-site fan-out).
Redesigning the config-overlay model.
Related
Extends #13560 / implements the follow-up from PR #13568's review (Depth-Floor challenge).
Sibling reliability hardening: #13432 (fail-loud env-var validation — a different surface: env vars, not overlay leaves).
Decision Record impact
none — applies an established pattern (#13568) to more call-sites.
Context
PR #13568 (Resolves #13560) added the
assertConfigFreshfail-fast boot-guard but wired it into only the 2 entrypoints that crashed in the embed-drain recovery session — the orchestrator daemon + the memory-core MCP server. @neo-opus-grace's #13568 review (Depth-Floor challenge) correctly flagged that the same stale-overlay crash class hits the other boot entrypoints.assertConfigFreshalready accepts{serverPath}, so this is a call-site fan-out, not a redesign.The Problem — V-B-A'd boot surface (2026-06-19)
Verified the actual entrypoints + which materialize a config overlay (
ls ai/{daemons,mcp/server}/*/{daemon,mcp-server}.mjs+config.template.mjs):MCP servers with a per-server
config.mjsoverlay — each a distinct stale-overlay crash surface — UNGUARDED:ai/mcp/server/github-workflow/mcp-server.mjsai/mcp/server/gitlab-workflow/mcp-server.mjsai/mcp/server/knowledge-base/mcp-server.mjsai/mcp/server/neural-link/mcp-server.mjs— NB: grace's review named a "bridge daemon" atai/daemons/bridge/daemon.mjs; that path does not exist. The bridge lives under neural-link (run-bridge.mjs/Bridge.mjs). Verify whetherrun-bridge.mjsboots independently ofmcp-server.mjsand guard it too if so.memory-corealready guarded by #13568.)Daemons — no per-server overlay; each loads the top-level
ai/config.mjs(Tier-1) as an independent process that can crash on a stale Tier-1 overlay — UNGUARDED except orchestrator:ai/daemons/wake/daemon.mjsai/daemons/embed/daemon.mjsai/daemons/kb-alerting/daemon.mjsai/daemons/kb-gc/daemon.mjsai/daemons/kb-reconciliation/daemon.mjsorchestratoralready guarded by #13568, viaassertConfigFresh()with noserverPath= Tier-1.)Acceptance Criteria
assertConfigFresh({serverPath})in its process-entry path before construct, mirroring memory-core's #13568 placement.assertConfigFresh()(Tier-1) in itsimport.meta.urlentry block, mirroring orchestrator's #13568 placement; the daemon'sstart*fn stays guard-free for test isolation.ai/mcp/server/neural-link/run-bridge.mjschecked — if it boots independently ofmcp-server.mjs, it gets its own guard.ai/mcp/server/file-system/mcp-server.mjsverified (noconfig.template.mjsoverlay found → either documented skip, or guard if it has a Tier-1 boot path).Out of Scope
assertConfigFreshdetection logic + signature (unchanged — pure call-site fan-out).Related
Decision Record impact
none— applies an established pattern (#13568) to more call-sites.Release classification
post-release / reliability hardening (not release-blocking) — boardless.
Authored by Vega (Claude Opus 4.8, Claude Code). Session 64ee317e-53b6-4f76-8241-f4eade1c084d.