Repository navigation
fix(scope): make APM_HOME the single root for APM-owned user state - #3614
Conversation
Centralize APM-owned user metadata under APM_HOME while keeping target deployment paths independent. Document and test the contract across package, config, lifecycle, and architecture boundaries.
…2884) Finish the APM_HOME single-root contract on top of the cherry-picked change from @WilliamK112 (closed PR #2967): - Deployment receipts move under get_apm_home(); the deploy-root .apm-local identity stays with the deployment root, like target files. - The architecture guard also pins the deployment ledger consumer. - Tests: subprocess isolation (two APM_HOME values, every global command family) and parity (unset/empty == ~/.apm); conftest drops a developer APM_HOME so the suite stays hermetic. - Docs: env-var contract lists marketplace registrations, receipts, lock, precedence, migration and the out-of-contract paths; apm-guide and CHANGELOG updated (entry moved to Unreleased). Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…e-user-root-2884 # Conflicts: # docs/src/content/docs/reference/cli/config.md
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Different APM_HOME values allow operations on the same project to acquire separate lifecycle locks, enabling a failed install’s rollback to overwrite another operation’s manifest changes.
2 open issues
What changed in this PR
This PR centralizes APM-owned user metadata under get_apm_home(), addressing #2884 and providing the resolver needed by #3006. It preserves ~/.apm as the default and keeps target deployment destinations separate.
Changes:
- Routes configuration, global package state, lifecycle state, and deployment receipts through the shared resolver.
- Adds isolation tests and an architecture guard against independent root resolution.
- Updates CLI messages, documentation, and the shipped APM guide to describe the path contract.
| File | Description |
|---|---|
tests/unit/test_outdated_command.py |
Expects the resolved path in diagnostics. |
tests/unit/test_deployment_materialization_receipts.py |
Tests receipt relocation and default parity. |
tests/unit/test_config.py |
Tests configuration isolation in a fresh process. |
tests/unit/scripts/test_architecture_runner.py |
Registers the expected architecture rule. |
tests/unit/install/test_workspace_locking.py |
Tests the overridden lifecycle lock path. |
tests/unit/core/test_scope.py |
Tests metadata paths and deployment separation. |
tests/unit/compilation/test_compile_global_flag.py |
Updates manifest-path diagnostic assertions. |
tests/integration/test_compile_global.py |
Tests metadata and target-directory separation. |
tests/integration/test_architecture_owner_rule_mutations.py |
Adds a resolver mutation case. |
tests/integration/test_architecture_apm_home.py |
Tests resolver ownership enforcement. |
tests/integration/test_apm_home_isolation.py |
Exercises isolation and fallback through CLI processes. |
tests/conftest.py |
Clears inherited APM_HOME during test setup. |
src/apm_cli/security/executables.py |
Relocates legacy approval lookup. |
src/apm_cli/install/phases/integrate.py |
Reports the configured approval-store path. |
src/apm_cli/install/manifest_helpers.py |
Displays the selected user metadata root. |
src/apm_cli/install/locking.py |
Moves lifecycle locking under the selected root. |
src/apm_cli/deps/registry/config_loader.py |
Uses the canonical user manifest path. |
src/apm_cli/deps/registry/auth.py |
Updates the configuration remediation path. |
src/apm_cli/core/script_trust.py |
Delegates trust-store path resolution. |
src/apm_cli/core/script_executors.py |
Delegates lifecycle log path resolution. |
src/apm_cli/core/scope.py |
Defines the canonical user metadata resolver. |
src/apm_cli/core/lifecycle_scripts.py |
Delegates user lifecycle manifest resolution. |
src/apm_cli/core/deployment_ledger.py |
Relocates receipts while retaining deployment identity. |
src/apm_cli/config.py |
Derives configuration paths from the resolver. |
src/apm_cli/commands/view.py |
Updates global-scope help text. |
src/apm_cli/commands/update.py |
Updates help and missing-manifest diagnostics. |
src/apm_cli/commands/uninstall/cli.py |
Updates help and user-scope progress output. |
src/apm_cli/commands/outdated.py |
Reports the selected metadata directory. |
src/apm_cli/commands/mcp.py |
Updates global installation help. |
src/apm_cli/commands/lock.py |
Updates help and missing-manifest diagnostics. |
src/apm_cli/commands/lifecycle.py |
Reports the resolved script-log path. |
src/apm_cli/commands/install.py |
Explains metadata versus deployment in help. |
src/apm_cli/commands/discover.py |
Updates user-manifest help text. |
src/apm_cli/commands/deps/why.py |
Updates user lockfile help text. |
src/apm_cli/commands/deps/cli.py |
Updates global help and path diagnostics. |
src/apm_cli/commands/config.py |
Reports the configured persistence path. |
src/apm_cli/commands/compile/cli.py |
Updates manifest provenance and global help. |
src/apm_cli/commands/approve.py |
Uses the configured store label and revised help. |
scripts/architecture_linter/checks/registry_owner_guards.py |
Enforces canonical resolver ownership and delegation. |
packages/apm-guide/.apm/skills/apm-usage/governance.md |
Updates the user configuration location. |
packages/apm-guide/.apm/skills/apm-usage/commands.md |
Documents metadata scope and exclusions. |
docs/src/content/docs/reference/environment-variables.md |
Defines the authoritative APM_HOME contract. |
docs/src/content/docs/reference/cli/view.md |
Documents overridden package metadata paths. |
docs/src/content/docs/reference/cli/update.md |
Documents global metadata and deployment separation. |
docs/src/content/docs/reference/cli/uninstall.md |
Updates user manifest and cleanup descriptions. |
docs/src/content/docs/reference/cli/self-update.md |
Clarifies the preserved configuration location. |
docs/src/content/docs/reference/cli/publish.md |
Updates the registry credential-store path. |
docs/src/content/docs/reference/cli/outdated.md |
Updates global dependency locations. |
docs/src/content/docs/reference/cli/mcp.md |
Separates user metadata from runtime configuration. |
docs/src/content/docs/reference/cli/lock.md |
Updates user manifest and lockfile locations. |
docs/src/content/docs/reference/cli/lifecycle.md |
Updates trust/log paths and links the contract. |
docs/src/content/docs/reference/cli/install.md |
Updates metadata, dry-run, and receipt documentation. |
docs/src/content/docs/reference/cli/experimental.md |
Updates feature-flag storage paths. |
docs/src/content/docs/reference/cli/deps.md |
Updates global dependency state paths. |
docs/src/content/docs/reference/cli/deny.md |
Updates the user denial-store location. |
docs/src/content/docs/reference/cli/config.md |
Updates configuration paths and precedence examples. |
docs/src/content/docs/reference/cli/compile.md |
Documents overridden inputs and separate outputs. |
docs/src/content/docs/reference/cli/approve.md |
Updates approval storage and legacy migration paths. |
docs/src/content/docs/enterprise/registry-proxy.md |
Revises marketplace registration and cache locations. |
CHANGELOG.md |
Records the fix and adds a historical GitLab entry. |
.apm/architecture/owners/core-runtime.json |
Registers metadata-root ownership and its guard. |
Review effort: Balanced
apm lock -g and apm update -g chdir into the APM home, so a relative APM_HOME such as 'metadata' resolved to metadata/metadata on later lookups and split the manifest from its lockfile, modules and config. get_apm_home() now expands a leading ~ and anchors a relative value once against the working directory captured at import. Addresses Copilot inline on src/apm_cli/core/scope.py:54 (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Moving the lifecycle lock under APM_HOME let processes with different homes mutate the same project or harness directories at once, so a failed install's rollback could overwrite another operation's manifest. acquire_lifecycle_lock() now takes the OS-user deployment-root lock in ~/.apm-local/ (named by the deployment owner) before the APM_HOME metadata lock and releases both together; unset APM_HOME keeps the ~/.apm layout. Adds a cross-home contention regression and updates home write-set snapshots and the pre-compile lock probe. Addresses Copilot inline on src/apm_cli/install/locking.py:44 (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The APM_HOME path contract now states that ~ is expanded, a relative value resolves against the start directory, and ~/.apm-local/.apm-lifecycle.lock serializes commands across APM_HOME values. Mirrors the change in apm-guide and the CHANGELOG entry (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 1 | 2 | Single-owner discipline is textbook; two-lock composite is sound; move LOCAL_STATE_DIR out of deployment_ledger to avoid eager import chain in every decorated command. |
| Test Coverage Expert | 0 | 1 | 0 | Strong coverage across all done-when promises; one gap: new deployment-root lock at ~/.apm-local/ lacks a symlink-rejection test. |
| Doc Writer | 0 | 2 | 1 | Done-when docs coverage met; remove stray CHANGELOG 0.31.0 hunk, fix install.md drift, link the contract from CLI pages. |
| DevX UX Expert | 0 | 1 | 2 | Help text and error wording correctly resolve APM_HOME; approve/deny docstrings still hardcode ~/.apm/config.json in user-visible --help. |
| Performance Expert | 0 | 0 | 1 | No hot-path regression; one nit: locking.py top-level import of deployment_ledger solely for a string constant adds ~5ms startup on every mutating command. |
| Supply Chain Security Expert | 0 | 0 | 1 | APM_HOME relocation preserves trust-store, receipt, approval, and locking integrity invariants. |
| Auth Expert | 0 | 0 | 1 | Token resolution chains untouched; credential config paths route through get_apm_home(); no credential leakage. Ship. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Test Coverage Expert] Add a symlink-rejection unit test for the deployment-root lock at ~/.apm-local/.apm-lifecycle.lock -- Evidence outcome=missing on a secure-by-default surface; the metadata-lock symlink test covers a different base path.
- [Doc Writer] Remove the stray '### Fixed' hunk inside the released [0.31.0] CHANGELOG section (cherry-pick artifact from fix: honor APM_HOME for global user state #2967) -- Violates changelog.instructions.md and ships an out-of-scope entry in a released block.
- [DevX UX Expert] Replace hardcoded ~/.apm/config.json in approve_cmd and deny_cmd Click docstrings with resolved path or generic wording -- Click renders docstrings as --help text; users with APM_HOME set see a stale path. Foldable.
- [Doc Writer] Fix install.md line 283 to reference the APM_HOME contract page instead of hardcoding ~/.apm/ as canonical root -- Done-when requires install docs to state the contract correctly; a one-line link swap.
- [Python Architect] Move LOCAL_STATE_DIR constant from deployment_ledger.py to core/scope.py so locking.py avoids the full ledger import chain -- Reduces ~20 command modules' import-time coupling; performance-expert independently confirmed ~5ms startup cost. Best as a post-merge refactor.
Architecture
classDiagram
direction LR
class ScopeModule {
<<CanonicalOwner>>
+get_apm_home() Path
+get_apm_dir(scope) Path
+get_manifest_path(scope) Path
+get_lockfile_dir(scope) Path
+ensure_user_dirs() Path
}
class InstallScope {
<<Enum>>
PROJECT
USER
}
class ConfigModule {
<<FrozenAtImport>>
+CONFIG_DIR str
+CONFIG_FILE str
}
class LifecycleLockHandle {
<<Composite>>
-_deployment FileLock
-_metadata FileLock
+lock_file str
+is_locked bool
+release() void
}
class LockingModule {
<<Module>>
+lifecycle_lock() FileLock
+deployment_root_lock() FileLock
+acquire_lifecycle_lock() LifecycleLockHandle
}
class DeploymentMaterializationSession {
<<Session>>
+state_path Path
+identity_path Path
-_receipts_base Path
}
class ArchGuardApmHome {
<<StaticAnalysis>>
+check_apm_home_resolution() Violations
}
ScopeModule *-- InstallScope : scopes
ConfigModule ..> ScopeModule : import-time get_apm_home()
LockingModule ..> ScopeModule : get_apm_home() for metadata lock
LockingModule *-- LifecycleLockHandle : creates
DeploymentMaterializationSession ..> ScopeModule : get_apm_home() for receipts
LockingModule ..> DeploymentMaterializationSession : LOCAL_STATE_DIR
ArchGuardApmHome ..> ScopeModule : enforces single owner
class ScopeModule:::touched
class LifecycleLockHandle:::touched
class LockingModule:::touched
class DeploymentMaterializationSession:::touched
class ConfigModule:::touched
class ArchGuardApmHome:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
A["CLI command e.g. apm install -g"] --> B["serialized_lifecycle (install/locking.py)"]
B --> C["acquire_lifecycle_lock()"]
C --> D["deployment_root_lock() ~/.apm-local/.apm-lifecycle.lock"]
D --> G{"deployment lock acquired?"}
G -- yes --> H["lifecycle_lock() APM_HOME/.apm-lifecycle.lock"]
G -- timeout --> I["LifecycleBusyError"]
H --> L{"metadata lock acquired?"}
L -- yes --> M["LifecycleLockHandle: both locks held"]
L -- timeout --> N["release deployment lock, LifecycleBusyError"]
M --> O["get_apm_home() core/scope.py"]
O --> P{"APM_HOME set and non-empty?"}
P -- yes --> Q["expanduser, anchor relative to startup cwd"]
P -- no --> R["Path.home() / .apm"]
Q --> S["command body reads/writes APM_HOME"]
R --> S
S --> T["release metadata lock, then deployment-root lock"]
Recommendation
All seven panelists signal ship; no blocking findings. The merge-worker should fold the three in-scope cleanups (stray CHANGELOG hunk, approve/deny --help paths, install.md reference) before landing, and the deployment-root lock symlink test should be tracked as the first post-merge follow-up since it guards a secure-by-default surface. The PR unblocks the marketplace resolver chain (#3006 / PR #3610) and should land once CI greens.
Full per-persona findings
Python Architect
- [recommended] locking.py top-level import of deployment_ledger.LOCAL_STATE_DIR couples the lock module to the full deployment-state import chain at
src/apm_cli/install/locking.py:17
~20 command modules import locking at module scope; a single string constant should live in a lightweight module (core/scope.py beside USER_APM_DIR) imported by both ledger and locking. - [nit] Relative APM_HOME silently stays relative when _STARTUP_CWD is None at
src/apm_cli/core/scope.py:68
Deleted start dir + relative APM_HOME would float across chdir; fail closed with a clear error. - [nit] _receipts_base = apm_home.parent containment base is wider than the prior Path.home() anchor at
src/apm_cli/core/deployment_ledger.py:97
For a shallow APM_HOME like /apm the containment base becomes /; symlink check is the load-bearing guard; document intent.
Test Coverage Expert
- [recommended] Deployment-root lock symlink rejection has no direct test at
tests/unit/install/test_workspace_locking.py:60
Existing symlink test covers only the metadata lock; the deployment-root lock uses a different base (Path.home()).
Proof (missing at):tests/unit/install/test_workspace_locking.py-- proves: A symlink at the cross-home serialization lock is rejected before any write. [secure-by-default]
Doc Writer
- [recommended] CHANGELOG adds a duplicate '### Fixed' heading inside the released [0.31.0] section with an unrelated Specification: preserve GitLab sparse-fetch transport #2938 entry at
CHANGELOG.md:287
Cherry-pick artifact from fix: honor APM_HOME for global user state #2967; violates changelog.instructions.md and is out of scope. - [recommended] install.md line 283 still names ~/.apm/ as canonical metadata root; install/update/deps/lock restate the contract instead of linking to it at
docs/src/content/docs/reference/cli/install.md:283
Define once, link elsewhere; Done-when requires install docs to state the contract correctly. - [nit] Env-var page says APM reads APM_HOME once at process start, but get_apm_home reads env per call; only startup cwd (and CONFIG_DIR) are captured once at
docs/src/content/docs/reference/environment-variables.md
Docs must match mechanism.
DevX UX Expert
- [recommended] approve_cmd and deny_cmd Click docstrings still hardcode ~/.apm/config.json in --help at
src/apm_cli/commands/approve.py:153
Click renders docstrings as command help; flag text says 'APM user config' while description says ~/.apm/config.json. - [nit] Busy-lock error for ~/.apm-local/ lock gives no context about cross-home serialization at
src/apm_cli/install/locking.py:118
A user with APM_HOME set may be confused that the blocking lock is outside their home. - [nit] --global help uses three different abstract nouns across commands
Minor discoverability gap; install -g carries the full explanation.
Performance Expert
- [nit] locking.py imports deployment_ledger at top level for a string constant at
src/apm_cli/install/locking.py:17
Pulls ~2k lines of modules at import for '.apm-local'.
Supply Chain Security Expert
- [nit] Relative APM_HOME silently stays floating when _STARTUP_CWD is unavailable at import at
src/apm_cli/core/scope.py:72
Fail closed instead of returning an unanchored path; practically unreachable.
Auth Expert
- [nit] Three docstrings in config_loader.py still hardcode ~/.apm paths at
src/apm_cli/deps/registry/config_loader.py:3
Internal doc drift in a credential-adjacent module.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
The cherry-pick from closed PR #2967 added a second Fixed heading with an unrelated GitLab entry inside the released 0.31.0 section. Released sections are not rewritten and the entry is outside #2884's scope. Addresses doc-writer panel finding on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
install.md still named ~/.apm/ as the canonical metadata root, and install/update/deps/lock each restated the APM_HOME contract. They now link the env-var reference instead; the env-var page no longer claims APM_HOME is read once. approve/deny --help, config_loader docstrings and lock -g help name the APM user home. Addresses doc-writer, devx-ux and auth panel findings on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Adds a symlink-rejection regression for the ~/.apm-local deployment-root lock, loads LOCAL_STATE_DIR lazily so importing locking no longer pulls the deployment ledger, names the shared lock in the busy error, fails closed when a relative APM_HOME cannot be anchored, and documents the receipts containment base. Addresses test-coverage, python-architect, performance, devx-ux and supply-chain panel findings on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The user-scope metadata location (APM_HOME) and lifecycle lock placement are CLI configuration, not OpenAPM manifest, lockfile or resolution behaviour, so no req anchor applies (#2884). apm-spec-waiver: APM_HOME relocates CLI user-state paths only; no OpenAPM manifest, lockfile or resolution behaviour changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
get_apm_home() now errors when a relative APM_HOME cannot be anchored because the start directory is gone; the env-var contract and apm-guide state it. Addresses doc-writer delta panel finding on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> # Conflicts: # docs/src/content/docs/reference/cli/view.md
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
#3608 added a longer view summary and #3643 added a check that root summaries are not truncated at 80 columns; together they fail tests/unit/test_cli_consistency.py on main and on every PR merge ref. Shorten the summary so the CI merge ref for this PR is green. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | All three prior findings resolved cleanly; no new architectural issues. |
| Test Coverage Expert | 0 | 0 | 0 | Deployment-root lock symlink gap closed; every behavioral fold carries a regression trap. |
| Doc Writer | 0 | 0 | 0 | Prior findings fixed; contract links resolve; fail-closed fold accurate. |
| DevX UX Expert | 0 | 0 | 0 | --help paths, lock -g noun and busy-lock hint resolved; error wording actionable. |
| Performance Expert | 0 | 0 | 0 | Lazy import removes the startup cost; no new hot-path cost. |
| Supply Chain Security Expert | 0 | 0 | 0 | Fail-closed anchoring and symlink rejection preserve integrity invariants. |
| Auth Expert | 0 | 0 | 0 | No token or credential resolution touched; docstrings fixed. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Recommendation
All five follow-ups from the prior advisory are folded and verified. Seven panelists converge on zero findings. The PR is CI-green, Copilot-drained, and CLA-passed. Recommend the maintainer land this at convenience to unblock the scope-migration chain (#3006 / PR #3610). No post-merge follow-ups remain.
Folded in this run
- (copilot) Serialize state changes across APM_HOME values: OS-user deployment-root lock in ~/.apm-local before the APM_HOME metadata lock, with a cross-home contention regression -- resolved in ac53bb7.
- (copilot) Anchor a relative APM_HOME once to the start directory and expand ~, with a lock -g chdir regression -- resolved in 359d6c8.
- (merge) Merged current main (feat(compile): fire a pre-compile lifecycle event before reading sources #3596, fix(mcp): name the searched registry and explain registry choice on a miss #2803, feat(cli): derive apm mcp install forwarded options from apm install #3633, fix(install): omit author from auto-bootstrapped apm.yml #3630, feat(view): add read-only
apm view --file PATHreverse provenance #3608, fix(deps): agree with prune on bundled skills after repo-to-subdirectory switch #3612, fix(cli): shorten apm view summary so root help is not truncated #3651 and later); kept APM_HOME wording in mcp/install/config/view docs; fixed the feat(compile): fire a pre-compile lifecycle event before reading sources #3596 pre-compile lock probe -- resolved in 6e67e56 and later merges. - (panel) Symlink-rejection test for the deployment-root lock -- resolved in ed4d9bd.
- (panel) Dropped stray Specification: preserve GitLab sparse-fetch transport #2938 hunk from the released 0.31.0 CHANGELOG block -- resolved in e09bab0.
- (panel) install.md canonical-root wording; install/update/deps/lock link the APM_HOME path contract; approve/deny/lock help and config_loader docstrings name the APM user home -- resolved in 2c2c02f.
- (panel) Lazy LOCAL_STATE_DIR import, fail-closed relative APM_HOME, busy-lock hint, receipts containment comment -- resolved in ed4d9bd.
- (panel) Documented the fail-closed relative APM_HOME case -- resolved in bd537cd.
- (ci) Spec conformance Mode B waiver: CLI user-state location only, no OpenAPM-observable change -- resolved in 8d396a8.
Copilot signals reviewed
src/apm_cli/install/locking.py:44-- LEGIT: moving the lock under APM_HOME dropped main's per-OS-user serialization (resolved in ac53bb7).src/apm_cli/core/scope.py:54-- LEGIT: relative APM_HOME re-resolved after chdir nested to metadata/metadata (resolved in 359d6c8).
Regression-trap evidence (mutation-break gate)
tests/unit/install/test_workspace_locking.py::test_different_apm_homes_still_serialize_on_the_deployment_root-- deleted the deployment-root lock acquisition; test FAILED as expected; guard restored.tests/unit/install/test_workspace_locking.py::test_deployment_root_lock_rejects_symlink_without_touching_target-- deleted the symlink rejection on the deployment-root lock; test FAILED as expected; guard restored.tests/unit/core/test_scope.py::TestGetApmDir::test_relative_apm_home_is_anchored_to_startup_cwdandtests/unit/commands/test_lock_command.py::test_global_lock_keeps_relative_apm_home_anchored_after_chdir-- deleted the start-directory anchoring; tests FAILED as expected; guard restored.tests/unit/core/test_scope.py::TestGetApmDir::test_relative_apm_home_fails_closed_without_startup_cwd-- deleted the fail-closed check; test FAILED as expected; guard restored.
Lint contract
ruff check and ruff format --check (pinned 0.15.12, including scripts/architecture_linter) silent; pylint R0801 10.00/10; lint-auth-signals.sh and lint-architecture-boundaries.sh clean.
CI
All 23 checks pass at 56160d7 (Lint, Build & Test shards, Lifecycle Smoke shards, Windows gates, Spec conformance, Architecture ratchets, CodeQL analyze, license/cla); 3 skipped by design (after 1 CI fix iteration: Mode B waiver).
Mergeability status
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3614 | 56160d7 |
ship_now | 2 | 13 | 0 | 2 | green | MERGEABLE | BLOCKED | pending required review |
Convergence
2 outer iteration(s); 2 Copilot round(s). Final panel stance: ship_now. Closes #2884 (full record scope). Ready for maintainer review.
Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.
…anifest-marketplaces Resolve the #3367 conflict in marketplace add by threading --offline and local apm.yml authoring catalogs through the canonical registration owner (probe_registration offline=, local_source_points_to_file, local hint on MarketplaceManifestNotFoundError) instead of a second inline probe in the command. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Resolve tests/conftest.py: keep both hermetic env pops (CODEX_HOME from this PR, APM_HOME from #3614). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…3707) * fix(tests): use an OS-absolute APM_HOME in scripts log path test On Windows '/custom/apm' is drive-relative, so get_apm_home() (since #3614) correctly anchors it to the startup drive (D:\custom\apm). The test compared against the un-anchored string and failed on the Windows release lane. Use a tmp_path-based APM_HOME, compare Path objects, and mark the test windows_compat so the PR-time Windows gate covers it. Refs #2884 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): fold #3707 into the APM_HOME entry Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…led by apm install -g (#3610) * fix: honor APM_HOME for global user state Centralize APM-owned user metadata under APM_HOME while keeping target deployment paths independent. Document and test the contract across package, config, lifecycle, and architecture boundaries. * feat(marketplace): declare marketplaces in the user manifest, reconciled by apm install -g Add a 'marketplaces:' list (name + an existing 'apm marketplace add' source form, optional ref) to the user manifest at the effective APM user root. 'apm install -g' reconciles it before resolving dependencies: registers missing entries, updates changed ones and removes only manifest-origin entries. The registry records each entry's origin; manual registrations are never overwritten or removed, and name conflicts are reported. Project and package manifests that declare 'marketplaces:' fail with an error naming the user manifest. The source-to-registration step is extracted from 'marketplace add' into marketplace.registration so both paths share one parser/probe. Refs #3006 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): reference #3610 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: complete APM_HOME contract for receipts, marketplaces and docs (#2884) Finish the APM_HOME single-root contract on top of the cherry-picked change from @WilliamK112 (closed PR #2967): - Deployment receipts move under get_apm_home(); the deploy-root .apm-local identity stays with the deployment root, like target files. - The architecture guard also pins the deployment ledger consumer. - Tests: subprocess isolation (two APM_HOME values, every global command family) and parity (unset/empty == ~/.apm); conftest drops a developer APM_HOME so the suite stays hermetic. - Docs: env-var contract lists marketplace registrations, receipts, lock, precedence, migration and the out-of-contract paths; apm-guide and CHANGELOG updated (entry moved to Unreleased). Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test: run APM_HOME isolation through the apm binary fixture (#2884) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): reference #3614 for APM_HOME entry Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test(marketplace): user-manifest marketplaces follow APM_HOME (#2884) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(scope): anchor a relative APM_HOME to the start directory apm lock -g and apm update -g chdir into the APM home, so a relative APM_HOME such as 'metadata' resolved to metadata/metadata on later lookups and split the manifest from its lockfile, modules and config. get_apm_home() now expands a leading ~ and anchors a relative value once against the working directory captured at import. Addresses Copilot inline on src/apm_cli/core/scope.py:54 (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(locking): serialize state changes across APM_HOME values Moving the lifecycle lock under APM_HOME let processes with different homes mutate the same project or harness directories at once, so a failed install's rollback could overwrite another operation's manifest. acquire_lifecycle_lock() now takes the OS-user deployment-root lock in ~/.apm-local/ (named by the deployment owner) before the APM_HOME metadata lock and releases both together; unset APM_HOME keeps the ~/.apm layout. Adds a cross-home contention regression and updates home write-set snapshots and the pre-compile lock probe. Addresses Copilot inline on src/apm_cli/install/locking.py:44 (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(apm-home): document relative values and cross-home locking The APM_HOME path contract now states that ~ is expanded, a relative value resolves against the start directory, and ~/.apm-local/.apm-lifecycle.lock serializes commands across APM_HOME values. Mirrors the change in apm-guide and the CHANGELOG entry (#2884). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): drop stray #2938 entry from the 0.31.0 block The cherry-pick from closed PR #2967 added a second Fixed heading with an unrelated GitLab entry inside the released 0.31.0 section. Released sections are not rewritten and the entry is outside #2884's scope. Addresses doc-writer panel finding on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(apm-home): link the path contract and fix stale ~/.apm wording install.md still named ~/.apm/ as the canonical metadata root, and install/update/deps/lock each restated the APM_HOME contract. They now link the env-var reference instead; the env-var page no longer claims APM_HOME is read once. approve/deny --help, config_loader docstrings and lock -g help name the APM user home. Addresses doc-writer, devx-ux and auth panel findings on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(locking): harden the cross-home lock and relative APM_HOME Adds a symlink-rejection regression for the ~/.apm-local deployment-root lock, loads LOCAL_STATE_DIR lazily so importing locking no longer pulls the deployment ledger, names the shared lock in the busy error, fails closed when a relative APM_HOME cannot be anchored, and documents the receipts containment base. Addresses test-coverage, python-architect, performance, devx-ux and supply-chain panel findings on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * chore(spec): record Mode B waiver for the APM_HOME user-state root The user-scope metadata location (APM_HOME) and lifecycle lock placement are CLI configuration, not OpenAPM manifest, lockfile or resolution behaviour, so no req anchor applies (#2884). apm-spec-waiver: APM_HOME relocates CLI user-state paths only; no OpenAPM manifest, lockfile or resolution behaviour changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(apm-home): document the fail-closed relative APM_HOME case get_apm_home() now errors when a relative APM_HOME cannot be anchored because the start directory is gone; the env-var contract and apm-guide state it. Addresses doc-writer delta panel finding on PR #3614. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(view): fit the root help summary in 80 columns #3608 added a longer view summary and #3643 added a check that root summaries are not truncated at 80 columns; together they fail tests/unit/test_cli_consistency.py on main and on every PR merge ref. Shorten the summary so the CI merge ref for this PR is green. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Revert "fix(view): fit the root help summary in 80 columns" This reverts commit bed006f. Lane F owns the main hotfix for the #3608 x #3643 root-help truncation; this PR stays out of that change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(marketplace): reconcile never destroys entries it cannot replace A malformed user manifest root (empty, list, scalar or invalid YAML) read as "no marketplaces" and removed every manifest-owned registration before package parsing rejected the file. A failed fetch for a renamed or moved entry still removed the stale one. Dry runs and no-op runs created marketplaces.json and config.json. Reject a non-mapping root before the registry is read, skip removals while any declared entry failed, and read the registry without creating files (read_registered_marketplaces). Addresses Copilot inline on src/apm_cli/marketplace/reconcile.py:116, :117 and :140. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * refactor(marketplace): add parses SOURCE through the shared owner `apm marketplace add` still split #ref fragments, resolved ref precedence and classified direct URLs itself, a second authority for the grammar the user-manifest reconcile parses with parse_registration_source. Normalize the CLI-only --branch alias at the command boundary and route add through the shared parser. Extend the marketplace-source-admission owner to registration.py and its guard: add and reconcile must call parse_registration_source, and the command may not re-split fragments or classify direct URLs. Behavioural, architecture and mutation tests cover the boundary, plus regressions for the three reconcile safety fixes. Addresses Copilot inline on src/apm_cli/marketplace/registration.py:89. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(install): keep commands/install.py within the 2100-line guard main already sits at the 2100-line cap, so the reconcile hook pushed install.py to 2105 and failed the Lint file-length guardrail. Make the hook a single call (the user-scope check moves into reconcile_user_marketplaces_or_exit) and collapse a single-name import. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(marketplace): follow APM_HOME and state reconcile limits The user manifest path now reads $APM_HOME/apm.yml (default ~/.apm/apm.yml) everywhere this PR documents it, the source column notes that entries have no --host equivalent, failure and hand-over wording matches the code, apm install's reference notes the reconcile step, the CHANGELOG leads with the benefit, the apm-guide row is shorter and the "Declare instead of add" callout opens the add section. Addresses panel follow-ups from doc-writer, devx-ux-expert and oss-growth-hacker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * refactor(marketplace): one registry write per reconcile, clearer output Fetch every new or changed entry first, then apply all registrations and removals in one locked transaction (apply_manifest_marketplaces) instead of a lock-read-write cycle per entry. Removals use the [-] symbol, the kept line pluralizes, a single failure is named directly, and the manual-conflict warning shows the current source. The source admission guard now also forbids reconcile.py from re-parsing SOURCE. The integration module declares its component marker and covers `apm install -g --dry-run` creating no registry files. Addresses panel follow-ups from performance-expert, cli-logging-expert, devx-ux-expert, test-coverage-expert, supply-chain-security-expert and python-architect. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(marketplace): reject relative local sources in the user manifest A relative local source such as ./catalog resolved against the directory where `apm install -g` ran, so the same user manifest registered different paths (or failed) depending on the cwd. Reject it with an actionable error; absolute and ~/ paths are unchanged. The shared not-found hint now says "use the path to the apm.yml file" so it reads right for both `marketplace add` and a manifest `source:`. Addresses delta panel follow-ups from doc-writer and cli-logging-expert. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com> Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* fix(tests): restore release-gate lanes for 0.36.0 Main's tag-gate lanes (build-release push + manual-build-release) were red on runs 43381609442, 43381682871 and 43394173235. PR CI never runs them. Product regressions (Windows/real installs), fixed: - Hook cleanup removed nothing on Windows: remove_stale_deployed_files looked up recorded hashes with POSIX keys while callers passed native backslash keys, so content proof failed closed (#3672, Refs #3649). - describe_path_obstruction returned None on Windows, which reports a directory-for-file as EACCES and a file-for-parent as ENOENT instead of EISDIR/ENOTDIR (#3709, Refs #3678). - Skill preflight refused claimed members of an unclaimed, populated skill directory that materialization leaves alone, failing a local bundle install (Refs #3625). Stale tests (behaviour changed intentionally), updated: - policy chain mocks now return real PolicyFetchResult (#2933, Refs #2753) - bare-cache/downloader/anonymous-https fixtures use real Git checkouts (#3603, Refs #3457) - mcp install help, registry error wording, deps why -g help (#3633 Refs #3588, #2803 Refs #2478, #3614 Refs #2884) - downloader stub carries carried_licenses (#3646, Refs #3556) - frozen-hash lifecycle uses a generic git host so -g URL validation uses git ls-remote instead of a live api.github.com 404 (#3672) New Windows-shaped regression tests are marked windows_compat. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * chore: spec waiver for release-gate repair apm-spec-waiver: restores pre-existing behaviour on Windows and in skill preflight; no OpenAPM-observable change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>


Description
TL;DR
APM_HOMEbecomes the single root for APM-owned user state. The globalapm.yml,apm.lock.yaml,apm_modules/,config.json, marketplace registrations, lifecycle trust/logs/lock and deployment receipts all resolve through one function,apm_cli.core.scope.get_apm_home(). Unset (or empty) keeps today's~/.apmbyte-for-byte; files deployed to harness directories do not move. This PR rebuilds Ching Wei Kang (@WilliamK112)'s work from closed PR #2967, keeping his authorship. It is also the prerequisite resolver for #3006.Note
Credit: the core change is Ching Wei Kang (@WilliamK112)'s commit, cherry-picked with his authorship from
WilliamK112/apm@codex/apm-home-2884(closed PR #2967; maintainers could not push to the fork). The follow-up commits complete the record's Done-when list and merge currentmain. Ching Wei Kang (@WilliamK112) please review.Important
For #3006 (declarative marketplaces in the user manifest): call
from apm_cli.core.scope import get_apm_home. The user manifest isget_manifest_path(InstallScope.USER), which isget_apm_home() / "apm.yml". Do not readAPM_HOMEdirectly: the architecture guardregistry_delegation.apm_home_resolutionrejects any other"APM_HOME"literal undersrc/.Local preflight skipped by maintainer instruction (2026-11-12); CI is the gate.
Problem (WHY)
$APM_HOME/apm.ymlwhileinstall/update/lock/deps -gread~/.apm/apm.yml, so one process could pick two different user manifests ([BUG] Document and align APM_HOME behavior for global user state #2884).config.json,marketplaces.json, the marketplace cache, the lifecycle lock and deployment receipts were hardcoded to~/.apm. An "isolated" run withAPM_HOME=/tmp/xstill read and wrote the real home.os.environ.get("APM_HOME")orPath.home() / ".apm"), so drift was a matter of time.Why these matter: the record's Done-when requires that "every global command … reads and writes only under it" and that "two different APM_HOME values do not interfere" (scope record). Repo rule: one authority per durable decision, guarded by a regression test plus a static boundary check (
.github/instructions/architecture.instructions.md).Approach (WHAT)
get_apm_home()tocore/scope.py:APM_HOMEif non-empty, else~/.apm.get_apm_dir/get_manifest_path/get_lockfile_dir/ensure_user_dirs(USER)delegate to it.config.CONFIG_DIR.~/.apm.registry_delegation.apm_home_resolution: one owner, one env lookup, pinned consumers, no"APM_HOME"literal anywhere else. Includes a mutation case.Implementation (HOW)
src/apm_cli/core/scope.py(William): the canonical resolver. Deploy roots (get_deploy_root,get_source_root) still return the OS home, so the code itself keeps APM metadata and target files apart.src/apm_cli/config.py(William):CONFIG_DIR = os.fspath(get_apm_home()). It is resolved once at import, which matches "APM readsAPM_HOMEonce at process start". Tests that monkeypatchCONFIG_DIRkeep working.src/apm_cli/core/deployment_ledger.py(follow-up): receipts move to$APM_HOME/deployment-receipts/. The containment/symlink check is anchored atget_apm_home().parent, which is still$HOMEby default (parity). The.apm-local/installationidentity stays at the deploy root; see Trade-offs.install/locking.py,core/lifecycle_scripts.py,core/script_trust.py,core/script_executors.py,deps/registry/*,security/executables.py(William): each one is now a one-line delegate toget_apm_home().scripts/architecture_linter/checks/registry_owner_guards.py+.apm/architecture/owners/core-runtime.json: the new owner guard. Merge conflicts with main's newer guards were resolved during the cherry-pick (both kept).tests/conftest.py: drops a developer'sAPM_HOMEat session start, so the suite stays hermetic.Diagrams
Legend: one resolver feeds every APM-owned path (left). Target deployment (right) never consults it. The two families do not fall back to each other.
flowchart LR ENV["APM_HOME env, read once"] --> R["core/scope.py get_apm_home()"] DEF["unset or empty"] -->|"fallback ~/.apm"| R R --> M["apm.yml, apm.lock.yaml, apm_modules/"] R --> C["config.json, marketplaces.json, cache/marketplace/"] R --> L["scripts-trust.json, logs/, .apm-lifecycle.lock"] R --> D["deployment-receipts/"] T["CLAUDE_CONFIG_DIR, CODEX_HOME, HERMES_HOME"] --> TD["target deploy dirs"] H["OS home"] -->|"fallback"| TD H --> ID[".apm-local/ identity for --global"]Trade-offs
--global.apm-local/identity stays in the OS home. It identifies the deployment root (inode and birth time of$HOME), not APM metadata.install.mdalready documents it as living "in your home directory for--global". Moving it underAPM_HOMEwould change parity when unset. The env-var reference lists this explicitly as out of contract.~/.apm/runtimes/) unchanged. They are not in the record's list, and the shell installers hardcode that path. This is documented as out of contract.config.CONFIG_DIRis import-time, not live. Production CLI processes read env once. Making it dynamic would break about 70 test files that monkeypatch the constant. In-process callers that need the live value ([FEATURE] Global marketplace directories for enterprise-wide discovery #3006) callget_apm_home().~/.apmthemselves..apm/primitives still resolve from the OS home source root (undocumented, incidental behavior;get_source_root(USER)is unchanged).Benefits
APM_HOMEset,install/update/uninstall/deps/lock -g,config,marketplaceandlifecyclewrite nothing under~/.apm. The subprocess test asserts that the OS home holds only.apm-local/and the update-check cache.APM_HOMEvalues are fully independent across config, manifest, lockfile, marketplaces, trust and uninstall.APM_HOMEproduce the same~/.apmlayout as before, receipts included.src/fails the Lint job via the owner guard.apm_cli.core.scope.get_apm_home.Issue and approved scope
Issue: Fixes #2884
Human scope-approval comment: #2884 (comment) (approve, area project, review contact Daniel Meppiel (@danielmeppiel)).
scripts/governance/eligibility.cjsfrom trustedmainreturnedrecord-present.Does this PR complete the issue, or what remains? It completes the record's Done-when. Out of scope per the record: harness deployment destinations, new env vars, automatic migration, project-scope changes, and #3006 itself.
Type of change
Testing
Scenario evidence
APM_HOME=A,config,install -g,deps list -g,lock -g,marketplace list,lifecycle trustanduninstall -guse only A. A second home B never sees A's state, and nothing lands in~/.apm.tests/integration/test_apm_home_isolation.py::test_two_apm_homes_do_not_interfere(regression-trap for #2884)APM_HOMEkeeps the exact~/.apmlayout, including receiptstests/integration/test_apm_home_isolation.py::test_unset_apm_home_keeps_the_default_layoutAPM_HOME=""behaves as unset…::test_empty_apm_home_behaves_as_unsettests/unit/core/test_scope.py::…::test_empty_apm_home_uses_defaultAPM_HOMEisolates metadata but Claude files still deploy toCLAUDE_CONFIG_DIRtests/integration/test_compile_global.py::test_apm_home_isolates_metadata_without_redirecting_target_deploymenttests/unit/core/test_scope.py::test_apm_home_does_not_redirect_target_deploymentAPM_HOME, keep symlink/containment protection, and stay at~/.apmwhen unsettests/unit/test_deployment_materialization_receipts.py::test_receipts_live_under_apm_home_while_identity_stays_at_root,::test_unset_apm_home_keeps_receipts_under_home_dot_apm,::test_symlinked_evidence_is_rejected_without_touching_referentAPM_HOMEin a fresh processtests/unit/install/test_workspace_locking.py::test_lifecycle_lock_honors_apm_hometests/unit/test_config.py::test_apm_home_selects_config_path_in_fresh_processAPM_HOMEoutside the ownertests/integration/test_architecture_apm_home.py(3 tests) and theregistry-delegation-apm-home-resolutionmutation caseValidation commands and results
Mutation-break (each reverted line turned the suite red, then was restored):
Post-merge with
origin/main:Lint mirror:
ruff checkpassed,ruff format --checkpassed, pylint R0801 scored 10.00/10,lint-auth-signals.shwas clean,lint_architecture_boundaries.py --root .exited 0, and no source file exceeds 2100 lines.How to test
export APM_HOME="$(mktemp -d)/apm"; apm config set target claude; apm install -g <org/pkg>: everything lands under$APM_HOME, and~/.apmis untouched.APM_HOME=/tmp/other apm deps list -g: the package from the previous step is not listed.unset APM_HOME; apm deps list -g: your normal~/.apmstate is shown, unchanged.APM_HOMEpath contract" indocs/src/content/docs/reference/environment-variables.md.Spec conformance (OpenAPM v0.1)
CONFORMANCE.{md,json}regeneratedCo-authored-by: Ching-Wei Kang 164879897+WilliamK112@users.noreply.github.com
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com