fix: harden global lifecycle state handling

[lkshrk (lkshrk)]

Summary

Fixes four global lifecycle correctness issues discovered during Omni's APM hard migration:

• remove stale Antigravity and Hermes MCP entries without touching user-owned entries
• make Hermes a stable explicit-only target
• make global audit resolve external deployment roots without mutating them
• serialize every lifecycle state mutator with one cross-process user lock

Closes #2608.

Safety properties

• MCP config updates and cleanup use atomic writes and preserve mode/user entries
• cleanup fails closed before lock ownership is discarded
• audit replay remaps absolute Hermes/Claude roots into scratch and remains read-only
• install/update/uninstall/prune/lock/deps/init/approve/marketplace/plugin mutations share one lifecycle lock
• teardown, interruption, repeated completion, abandoned transactions, Windows home resolution, and lock timeout paths are covered

Scenario Evidence

User promise	Test evidence	Principle
Lifecycle state mutators serialize across processes and release the lock on failure.	uv run --extra dev pytest tests/integration/test_lifecycle_workspace_lock.py tests/integration/test_architecture_lifecycle_lock.py -q	DevX, governed by policy
Stale Antigravity and Hermes MCP cleanup preserves user-owned config and fails closed on unsafe writes.	uv run --extra dev pytest tests/integration/test_mcp_install_flow.py tests/unit/test_mcp_integrator_remove_stale.py tests/unit/test_uninstall_engine_helpers.py -q	Secure by default, governed by policy
Global audit reads external Hermes/Claude roots, detects drift and unsafe symlinks, and does not mutate those roots.	uv run --extra dev pytest tests/integration/test_global_audit_deploy_root.py -q	Secure by default, governed by policy
Hermes is stable explicit-only and is excluded from all while remaining selectable by manifest or --target.	uv run --extra dev pytest tests/integration/test_hermes_target.py tests/unit/core/test_target_catalog.py tests/unit/core/test_target_detection.py tests/unit/core/test_target_resolution_v2.py -q	Multi-harness support, DevX

Validation

• 19,879 unit tests passed
• 75 focused integration tests passed
• 166 architecture tests passed
• 898 audit/drift tests passed
• Windows compatibility gate: 153 passed
• Ruff lint/format, mypy on touched code, test-authority checks, and diff checks passed
• Independent code review: approved

[Copilot]

Pull request overview

Hardens global (user-scope) lifecycle state correctness by (1) making audit/CI checks understand deployment roots outside ~/.apm, (2) stabilizing Hermes as an explicit-only target (not experimental-flag gated), (3) tightening MCP stale-server cleanup to fail closed and preserve user-owned config, and (4) serializing workspace mutations with a cross-process lifecycle lock.

Changes:

• Add a cross-process lifecycle lock and apply it to most CLI state-mutating commands; make install transactions acquire/release the same lock safely across error paths.
• Fix global audit/drift to resolve and compare against external deployment roots (e.g., ~/.agents, ~/.hermes, ~/.claude) without mutating those roots.
• Make Hermes stable explicit-only (remove experimental flag gating) and extend MCP cleanup to cover Hermes YAML and Antigravity’s user-scope config location.

Reviewed changes

Copilot reviewed 56 out of 56 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/test_windows_compat_gate_workflow.py	Updates Windows compat gate contract to include one integration lock test path.
tests/unit/test_uninstall_engine_helpers.py	Adds failure-mode regression tests ensuring MCP cleanup failures don’t drop lock ownership.
tests/unit/test_uninstall_dev_dependencies.py	Updates expected uninstall output to reflect fail-closed MCP cleanup behavior.
tests/unit/test_prune_command.py	Adds prune regression test for MCP cleanup failure preserving lock/config bytes.
tests/unit/test_mcp_integrator_remove_stale.py	Adds coverage for atomic-failure preservation, Hermes YAML cleanup, and strict malformed shapes.
tests/unit/test_cli_consistency.py	Updates compile help assertions for explicit-only Hermes exclusion from all.
tests/unit/integration/test_targets.py	Updates Hermes target invariants and removes experimental-flag gating.
tests/unit/integration/test_antigravity_target.py	Adds Windows-compat atomic-write/mode preservation coverage for Antigravity MCP config.
tests/unit/install/test_workspace_locking.py	Unit contracts for lifecycle lock behavior and error-path release.
tests/unit/install/test_install_transaction.py	Adds multi-process serialization tests + interruption/abandonment/repeat-completion lock release coverage.
tests/unit/core/test_target_resolution_v2.py	Updates target filtering expectations to keep stable Hermes.
tests/unit/core/test_target_detection.py	Removes Hermes from experimental target set characterization.
tests/unit/core/test_target_catalog.py	Updates target-set characterization and Hermes profile expectations.
tests/unit/commands/test_uninstall_atomic_selection.py	Adds uninstall regression test ensuring MCP cleanup failure preserves lock/config bytes.
tests/integration/test_mcp_install_flow.py	Adds global manifest removal + prune flows validating Antigravity MCP cleanup semantics.
tests/integration/test_lifecycle_workspace_lock.py	Cross-command subprocess regression test ensuring lifecycle serialization across commands/scope.
tests/integration/test_hermes_target.py	Updates Hermes E2E tests for stable explicit-only behavior and MCP selection changes.
tests/integration/test_global_audit_deploy_root.py	New integration coverage: global audit resolves external roots read-only and detects drift.
src/apm_cli/policy/ci_checks.py	Resolves deployed-file paths for global scope and audits external target roots read-only.
src/apm_cli/integration/targets.py	Documentation tweak reflecting Hermes stable explicit-only status.
src/apm_cli/integration/mcp_integrator.py	Adds strict config-shape validation, atomic writes, and Hermes YAML MCP stale cleanup.
src/apm_cli/integration/mcp_integrator_install.py	Removes Hermes from auto-discovery/experimental opt-in gating.
src/apm_cli/install/transaction.py	Makes install transactions acquire/release lifecycle lock safely across failure paths.
src/apm_cli/install/phases/targets.py	Removes Hermes experimental enable-hint gate.
src/apm_cli/install/locking.py	New lifecycle locking module (FileLock-based) + decorator for command serialization.
src/apm_cli/install/drift.py	Adds user-scope replay and external-root drift comparisons with absolute-claim rebasing.
src/apm_cli/install/audit_target_roots.py	New helpers to project external target roots into audit scratch + rebase claims.
src/apm_cli/install/audit_replay.py	Threads user-scope into CI audit replay preparation and target resolution.
src/apm_cli/core/target_detection.py	Adds Hermes to accepted target vocabulary and updates description text.
src/apm_cli/core/target_catalog.py	Marks Hermes capability as explicit-only rather than experimental-flag gated.
src/apm_cli/core/scope.py	Adds helper to resolve workspace deploy root for user-scope metadata workspaces.
src/apm_cli/core/experimental.py	Removes Hermes experimental flag registration.
src/apm_cli/commands/update.py	Serializes apm update via lifecycle lock.
src/apm_cli/commands/uninstall/engine.py	Broadens stale MCP server set derivation and fails closed on cleanup write errors.
src/apm_cli/commands/uninstall/cli.py	Serializes uninstall and fails closed when MCP cleanup fails (prevents persisting dropped ownership).
src/apm_cli/commands/prune.py	Serializes prune and integrates MCP cleanup into prune-before-lock-write flow.
src/apm_cli/commands/plugin/init.py	Serializes plugin init via lifecycle lock.
src/apm_cli/commands/marketplace/plugin/remove.py	Serializes marketplace plugin remove via lifecycle lock.
src/apm_cli/commands/marketplace/plugin/add.py	Serializes marketplace plugin add via lifecycle lock.
src/apm_cli/commands/marketplace/init.py	Serializes marketplace init via lifecycle lock.
src/apm_cli/commands/marketplace/init.py	Serializes marketplace add/update/remove via lifecycle lock.
src/apm_cli/commands/lock.py	Serializes lock command execution via lifecycle lock.
src/apm_cli/commands/install.py	Serializes install and hardens root-redirect/transaction teardown ordering.
src/apm_cli/commands/init.py	Serializes project init via lifecycle lock.
src/apm_cli/commands/deps/cli.py	Serializes deps clean/update via lifecycle lock.
src/apm_cli/commands/approve.py	Serializes approve/deny via lifecycle lock.
src/apm_cli/adapters/client/gemini.py	Switches Gemini config writes to atomic writes with secure permissions.
docs/src/content/docs/reference/targets-matrix.md	Updates Hermes status and compilation guidance in targets matrix docs.
docs/src/content/docs/reference/manifest-schema.md	Reclassifies Hermes as stable in manifest schema docs.
docs/src/content/docs/reference/environment-variables.md	Updates HERMES_HOME semantics for explicit-only Hermes.
docs/src/content/docs/reference/cli/experimental.md	Removes Hermes from experimental-flag list.
docs/src/content/docs/reference/cli/deps.md	Updates deps target docs for Hermes stable explicit-only behavior and all exclusion.
docs/src/content/docs/producer/compile.md	Removes Hermes from experimental-target list in compile docs.
docs/src/content/docs/integrations/hermes.md	Updates Hermes integration page to stable explicit-only and MCP behavior.
docs/astro.config.mjs	Renames Hermes nav label to non-experimental.
.github/workflows/ci.yml	Expands Windows compat gate to include lifecycle subprocess integration contract.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[lkshrk (lkshrk)]

@microsoft-github-policy-service agree

[Daniel Meppiel (danielmeppiel)]

@.shepherd-advisory-2655.md

[Daniel Meppiel (danielmeppiel)]

Rebased onto current main at c919ba3 from b82f5fa -> 227d6ca.

Conflicting paths resolved (faithful merge of both intents):

• `src/apm_cli/install/transaction.py`
• `src/apm_cli/commands/compile/cli.py`
• `src/apm_cli/commands/compile/watcher.py`

Lint contract: `uv run --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/` and `uv run --extra dev ruff format --check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/` both passed post-rebase; the same pair also passed in --quiet mode with no output.

Post-push mergeability: `gh pr view --json mergeStateStatus,mergeable` reports `BLOCKED / MERGEABLE`; BLOCKED is the expected fork workflow approval/review gate, not a conflict. Push used `git push --force-with-lease=fix/omni-apm-blockers:b82f5fa8eb3e74472b0cb64a0b3dfba61e120d4e lkshrk-fork HEAD:fix/omni-apm-blockers` (--force-with-lease, never bare --force).

Fork workflows pending approval for this head: CI 33769287059, Spec conformance 33769287062, Deploy Docs 33769287068, NOTICE Drift Check 33769287091, CodeQL 33769287175, Merge Gate 33769287178, CRLF Invariance 33769287531.

Ready for maintainer review.

[Daniel Meppiel (danielmeppiel)]

Rebased onto current main at 354faad -> ac7529a.

Conflicting paths resolved (faithful merge of both intents):

• src/apm_cli/commands/uninstall/cli.py
• src/apm_cli/commands/uninstall/engine.py
• docs/src/content/docs/reference/cli/install.md
• src/apm_cli/commands/install.py
• src/apm_cli/utils/atomic_io.py
• src/apm_cli/commands/compile/cli.py

Regression-trap test re-verified post-rebase (mutation-break gate):

• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_cleanup_failure_retains_lock_ownership -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.
• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_claude_atomic_failure_retains_live_bytes_and_ownership[False] -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.
• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_claude_atomic_failure_retains_live_bytes_and_ownership[True] -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.

Lint contract: uv run --frozen --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ --quiet and uv run --frozen --extra dev ruff format --check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ --quiet both silent post-rebase. Full local lint guard also passed silently.

Post-push mergeability: gh pr view --json mergeStateStatus,mergeable reports BLOCKED / MERGEABLE; BLOCKED is the expected fork workflow approval/review gate, not a conflict. Push used git push --force-with-lease=fix/omni-apm-blockers:fa62a208c69c2046b5f5d6dcb5690df3f0f61af7 lkshrk-fork HEAD:fix/omni-apm-blockers (--force-with-lease, never bare --force).

Spec waiver preserved: apm-spec-waiver: Corrects existing adapter ownership behavior without changing the OpenAPM contract.; Mode B remained 500 substantive added lines.

Fork workflows pending approval for this head: CI 33806493037, Spec conformance 33806492140, Deploy Docs 33806492235, NOTICE Drift Check 33806492251, CodeQL 33806492187, Merge Gate 33806492160, CRLF Invariance 33806492236.

Ready for maintainer review.

[Daniel Meppiel (danielmeppiel)]

Rebased onto current main at 1560d88 -> aba8d6e.

Pre-rebase head was 7535808.

Conflicting paths resolved (faithful merge of both intents):

• src/apm_cli/commands/uninstall/cli.py

Regression-trap test re-verified post-rebase (mutation-break gate):

• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_cleanup_failure_retains_lock_ownership -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.
• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_claude_atomic_failure_retains_live_bytes_and_ownership[False] -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.
• tests/unit/test_uninstall_engine_helpers.py::TestCleanupStaleMcp::test_claude_atomic_failure_retains_live_bytes_and_ownership[True] -- deleted raise MCPUninstallCleanupError(failures) from failures[0][1]; test FAILED as expected; guard restored.

Lint contract: uv run --frozen --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ --quiet and uv run --frozen --extra dev ruff format --check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ --quiet both silent post-rebase; the R0801 duplication guard and local lint guard suite also passed.

Post-push mergeability: gh pr view --json mergeStateStatus,mergeable reports BLOCKED / MERGEABLE; BLOCKED is the expected required review / fork workflow approval gate, not a conflict. Push used git push --force-with-lease=fix/omni-apm-blockers:7535808889e511c1587208bd1d4d25590f6195b9 lkshrk-fork HEAD:fix/omni-apm-blockers (--force-with-lease, never bare --force).

Spec waiver preserved: apm-spec-waiver: Corrects existing adapter ownership behavior without changing the OpenAPM contract.; Mode B remained 500 substantive added lines.

Fork workflows pending approval for this head: Deploy Docs 33816499428, CRLF Invariance 33816499156, CodeQL 33816499183, Spec conformance 33816499190, NOTICE Drift Check 33816499328, Merge Gate 33816499297, CI 33816499308.

Ready for maintainer review.