[VALIDATION-5] Lockfile portability: absolute paths leak across machines

[danielmeppiel]

Summary

After running apm install in a fresh clone, the lockfile uses absolute paths from my home directory (e.g., /Users/jdoe/.cache/apm/...) instead of relative paths. Sharing the lockfile across machines becomes impossible -- a teammate gets path not found on every entry.

Reproduction

1. git clone <repo>; cd <repo>
2. apm install -- generates apm.lock.yaml with absolute resolved paths
3. Commit + push the lockfile
4. On a different machine: apm install reads the absolute path, fails

Expected

Lockfile entries should reference repo-relative or cache-key-relative paths so the file is portable.

Workaround

Manually post-process the lockfile with sed before committing. Not great.

Environment

• APM 0.9.3 on macOS 14
• Tested with both Copilot and Claude Code targets

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/lockfile
area/docs-site
type/bug
status/accepted
priority/high

Milestone

0.9.4

Suggested next action

Fix apm.lock.yaml path storage in src/apm_cli/deps/lockfile.py to write repo-relative (or cache-root-relative) paths instead of absolute paths, and update docs/src/content/docs/reference/lockfile-spec.md to document the portable path format in the same PR.

Suggested issue comment

Thanks for the detailed reproduction steps and the workaround note -- this is a clear regression against APM's core promise that a committed `apm.lock.yaml` produces deterministic installs on any machine.

**What is happening:** Lockfile entries are being written with absolute paths (e.g. `/Users/jdoe/.cache/apm/...`). These should be stored as paths relative to a stable base (project root or APM cache root), then reconstructed to absolute paths at install time on each machine.

**Scope of the fix:**
- `src/apm_cli/deps/lockfile.py` -- change path serialization to relative paths at write time; resolve back to absolute at read time (path containment guards via `path_security.ensure_path_within` must still apply after reconstruction)
- `docs/src/content/docs/reference/lockfile-spec.md` -- document the portable path format
- A backward-compat signal for existing absolute-path lockfiles (graceful error with a clear migration step, e.g. `apm install --refresh-lock`, is preferred over silent migration)

**Key design question for the PR:** relative to what base? Project root is the most intuitive for repo-committed lockfiles; cache root works if the APM cache location is user-configurable. Documenting that choice in the PR description will make review faster.

This is targeted for `0.9.4`. If you want to open a draft PR, the lockfile writer is the right entry point. Happy to review.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps directly to APM's stated mental model invariant: "Lockfile is canonical -- apm install from a lockfile is deterministic. CI must not need extra flags." Absolute paths in apm.lock.yaml shatter this invariant: the lockfile becomes machine-local, un-committable, and useless for team CI. Every major package manager (npm package-lock.json, Cargo.lock, pip-compiled requirements) uses portable references -- this is table-stakes DX for any package manager. The manual sed workaround is a red flag indicating a missing default behavior. User task is "commit lockfile, share with team, get identical installs everywhere" -- a fundamental workflow that must work out of the box. Priority: high.

Supply Chain Security Expert -- Risk-Surface Reviewer

No new threat surfaces introduced by this fix. The issue is about path representation (absolute vs relative), not about integrity or hash provenance. There is a positive security co-benefit: absolute paths like /Users/jdoe/.cache/apm/... committed to a public repo disclose local filesystem topology (username, home directory structure). Relative paths eliminate that information disclosure. The fix MUST ensure that resolved absolute paths at install time continue to flow through path_security.validate_path_segments and ensure_path_within -- the relative-to-absolute reconstruction step must not bypass path containment. No theme/security required as the primary theme; theme/portability is correct. Area: area/lockfile.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with extensive prior history on microsoft/apm; tone tuning for a new or low-interaction contributor is not warranted.

Python Architect -- Architecture Reviewer

Feasibility: clear, well-precedented fix. The lockfile writer (src/apm_cli/deps/lockfile.py) stores paths at write time and reconstructs them at read time; changing the storage representation from absolute to relative is localized to that module plus any downstream callers that pass lockfile paths to integrators or path-security guards. Cross-cutting impact: (1) lockfile.py serialization/deserialization, (2) install pipeline phases that read path entries and pass them to ensure_path_within, (3) the lockfile spec doc. Key design decision: relative to what base? -- project root (most intuitive, best for committed lockfiles) vs cache root (works if cache is configurable). This can be resolved in PR discussion; no separate design doc needed. Backward compatibility: existing lockfiles with absolute paths should fail gracefully with a clear migration message rather than silently migrating. status/accepted is appropriate -- direction is clear and no new interface or protocol design is required before coding starts.

Doc Writer -- Documentation Reviewer

Docs work is implied: docs/src/content/docs/reference/lockfile-spec.md must be updated to document that path entries in apm.lock.yaml are stored as relative paths (relative to the chosen base), not absolute resolved paths. The implementing PR should carry area/docs-site as a secondary area label as a reminder. The suggested comment uses "lockfile" and "apm.lock.yaml" consistently, aligned with README and docs vocabulary. Wording is grounded in user-facing language from the README quickstart and the lockfile spec.

APM CEO -- Triage Arbiter

Clean accept at priority/high. Lockfile portability is not a nice-to-have -- it is the foundational promise that makes APM useful in team and CI contexts. The reproduction is precise, the fix direction is clear (relative paths, a well-understood pattern across the package manager ecosystem), and the implementing PR scope is bounded to lockfile.py plus a spec doc update. No design doc is required; the relative-base choice is the only open question and PR discussion is the right forum for it. Milestone 0.9.4 is correct (patch bug fix, not a feature). Label set is exactly 6 (theme/portability, area/lockfile, area/docs-site, type/bug, status/accepted, priority/high), within the cap.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/lockfile", "area/docs-site"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Fix apm.lock.yaml path storage in src/apm_cli/deps/lockfile.py to write relative paths instead of absolute paths, and update docs/src/content/docs/reference/lockfile-spec.md in the same PR.",
  "comment_markdown": "Thanks for the detailed reproduction steps and the workaround note -- this is a clear regression against APM's core promise that a committed `apm.lock.yaml` produces deterministic installs on any machine.\n\n**What is happening:** Lockfile entries are being written with absolute paths (e.g. `/Users/jdoe/.cache/apm/...`). These should be stored as paths relative to a stable base (project root or APM cache root), then reconstructed to absolute paths at install time on each machine.\n\n**Scope of the fix:**\n- `src/apm_cli/deps/lockfile.py` -- change path serialization to relative paths at write time; resolve back to absolute at read time (path containment guards via `path_security.ensure_path_within` must still apply after reconstruction)\n- `docs/src/content/docs/reference/lockfile-spec.md` -- document the portable path format\n- A backward-compat signal for existing absolute-path lockfiles (graceful error with a clear migration step, e.g. `apm install --refresh-lock`, is preferred over silent migration)\n\n**Key design question for the PR:** relative to what base? Project root is the most intuitive for repo-committed lockfiles; cache root works if the APM cache location is user-configurable. Documenting that choice in the PR description will make review faster.\n\nThis is targeted for `0.9.4`. If you want to open a draft PR, the lockfile writer is the right entry point. Happy to review."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel for issue #956 · ● 517.4K · ◷

[danielmeppiel]

Closed: validation mock for triage-panel automation. Scenario 5 (fast-path via status/needs-triage label trigger) verified end-to-end. See PR #954 for details.