fix: surface empty AgentMesh policy state at startup

[Ricky Gummadi (Ricky-G)]

Summary

Make AgentMesh readiness fail closed when no enabled policy rules are loaded. The policy server and governance sidecar now expose the empty-policy state consistently through HTTP 503 readiness responses and structured load diagnostics.

Problem

The policy server and governance sidecar could start with an empty or ineffective policy set while reporting readiness. The policy server also replaced the shared readiness route by mutating FastAPI's route list at import time, and its tests duplicated global-state save/restore logic.

Changes

File	What changed
agent-governance-python/agent-mesh/src/agentmesh/server/__init__.py	Allow components to opt out of the generic /readyz route without mutating the router.
agent-governance-python/agent-mesh/src/agentmesh/server/policy_server.py	Return 503 Not Ready when no effective rules are loaded, report effective_rules and load_warnings, count enabled governance/trust rules, and fail closed for a missing policy directory.
agent-governance-python/agent-mesh/src/agentmesh/server/sidecar.py	Return consistent 503 Not Ready responses from /ready and /readyz, track effective rules, and expose load_warnings in generation/status responses.
agent-governance-python/agent-mesh/src/agentmesh/governance/trust_policy.py	Read and write policy files with explicit UTF-8 encoding.
agent-governance-python/agent-mesh/tests/test_server.py	Use monkeypatch for isolated policy-server state and cover empty, disabled, trust, and missing-directory policy states.
agent-governance-python/agent-mesh/tests/test_sidecar.py	Cover sidecar readiness status and load-warning propagation.
agent-governance-python/agent-mesh/CHANGELOG.md	Document the deployment-visible readiness behavior and diagnostics.
.cspell-repo-terms.txt	Register the readyz endpoint term using the repository convention.

Closes #4061.

Related to #3538.

Attribution & Prior Art

This change incorporates the empty-policy readiness implementation and regression-test approach from #3441. Credit to sakunaharinda is included in every branch commit with Co-authored-by: sakunaharinda <sakunaj1996@gmail.com>.

Testing

• PYTHONPATH=agent-governance-python/agent-mesh/src python -m pytest agent-governance-python/agent-mesh/tests/test_server.py agent-governance-python/agent-mesh/tests/test_sidecar.py agent-governance-python/agent-mesh/tests/test_trust_policy.py -q — 95 passed, 1 skipped.
• PYTHONPATH=agent-governance-python/agent-mesh/src python -m pytest agent-governance-python/agent-mesh/tests/test_otel_bootstrap.py -q — 33 passed.
• python -m ruff check --select E,F,W --ignore E501 on changed AgentMesh files — passed.
• git diff --check — passed.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[MohammadHaroonAbuomar]

• agent-governance-python/agent-mesh/src/agentmesh/server/sidecar.py:62 The sidecar's /ready and /readyz still return 200 with policies_loaded: 0 (verified), while the policy-server now returns 503 for the same state. Flip the sidecar too or say why the two should differ; #4061 asks for the probe to distinguish the empty state.
• agent-governance-python/agent-mesh/CHANGELOG.md: no entry, yet 503-on-empty is deployment-visible: a policy-server with an empty directory, which safely denies everything today, will never become Ready and drops out of its Service. Document it and the new load_warnings / startup_warnings fields.
• Minor: .cspell.json:70 adds a term to words; the repo convention is .cspell-repo-terms.txt. .gitignore:23 .DS_Store is unrelated and comes from #3441's commit 2f269c1. In sidecar.py the field startup_warnings and the "Startup validation" message also fire on POST /api/v1/policy/reload; load_warnings would match the policy-server and the actual trigger.

[MohammadHaroonAbuomar]

Round two at 68e0cca: asks 1 and 3 through 8 are verified in code (trailer on every commit and #3441 credited; sidecar and policy-server both return 503 with zero effective rules; include_readyz replaces the route mutation; rules are counted, not files; CHANGELOG entry; fixture; terms file). CI green.

What is left is the order against #4071. This branch now carries #4071's missing-directory raise byte for byte, but git merge-tree still conflicts in three hunks of policy_server.py and one in test_server.py. I will take #4071 first, since it is the fail-closed loading fix, and this one second. Once #4071 lands, rebase this onto it, drop the duplicated missing-dir block, and I will approve.

Two minor items you can fold into that rebase, neither blocking: effective_rule_count is summed per file while PolicyEngine keeps one policy per name, so two files sharing a name overcount (probe: 1 + 2 rules under the same name reports 3 while the engine holds 2 and the sidecar reports 2); counting from the engine's policies after the loop would match. And the unauthenticated /readyz payload now includes policy_dir; /api/v1/policies already exposed it, so this is a note, not a change request.

[MohammadHaroonAbuomar]

Approving at bb1475d. The rebase onto #4071 is clean: the duplicated missing-directory block is gone, the range-diff shows no change beyond the rebase, and the combined behaviour was probed end to end (empty dir, missing dir, mode-000 dir, rules: [], one enabled rule, unreadable file on reload). Both servers report 503 with zero effective rules, the fail-closed startup and 409 reload paths from #4071 hold, and readiness is unchanged when a reload is rejected. sakunaharinda is credited on every commit. 108 tests pass, CI green.

Two notes carried as follow-ups, not blockers: effective_rule_count is summed per file, so two files sharing a policy name overcount against the engine (sidecar dedupes), and the policy-server /readyz payload includes policy_dir. Keep the co-author trailer in the squash message.