[BUG] `apm uninstall -g` leaves Copilot hook files in `~/.copilot/hooks/`

[sproott]

Describe the bug

Uninstalling a user-scope package (apm install -g → apm uninstall -g) removes
every other primitive it deployed but leaves its Copilot hook files behind in
~/.copilot/hooks/. The orphaned file is live wiring: Copilot CLI keeps firing a
hook belonging to a package that is gone from apm.yml, apm_modules/, and the
lockfile. Reinstalling never clears it either — the path is simply never a
deletion candidate.

Copilot is the only harness affected, and only at user scope. Uninstall's
file-level removal routes each lockfile deployed_files path into a per-primitive
bucket via
BaseIntegrator.partition_managed_files,
which walks a segment trie built from every non-skills/hooks primitive prefix
and falls back to the skills/hooks prefix tuples only when the trie yields no
match:

if last_bucket is not None:
    buckets[last_bucket].add(p)
    continue
# Fall back to cross-target buckets
if p.startswith(skill_tuple):
    buckets["skills"].add(p)
elif p.startswith(hook_tuple):
    buckets["hooks"].add(p)

At user scope the Copilot target's
user_primitive_overrides
maps instructions to PrimitiveMapping("", ".md", "copilot_user_instructions") —
an empty subdir, so its prefix is the bare target root .copilot/. That prefix
becomes a catch-all trie node: .copilot/hooks/<pkg>-<hook>.json matches at the
first segment, last_bucket is set to instructions_copilot, and the continue
skips the hook fallback. The hook path is handed to
InstructionIntegrator.sync_for_target,
whose copilot_user_instructions guard narrows the prefix to
.copilot/copilot-instructions.md and discards it. No integrator ever deletes the
file, and HookIntegrator.sync_integration never sees it in managed_files.

Nothing shadows .copilot/prompts/ or .copilot/agents/ — they own deeper trie
nodes and win by longest prefix. Hooks lose because they are routed by the
fallback tuples rather than by the trie. At project scope Copilot hooks land in
.github/hooks/, outside the .copilot/ root, so the shadowing never applies and
removal works. The other harnesses escape for a different reason: their hooks are
merged into a shared config (.claude/settings.json, .cursor/hooks.json, …) and
cleaned by _apm_source marker rather than by managed_files.

The symptom resembles #2245 / #2250, but those cover the merged-hook JSON path;
this is the per-file deployment path and a different root cause. Same target and
scope as #2232, also a different cause.

To Reproduce

Steps to reproduce the behavior:

1. cd uninstall-copilot-user-hook-orphan
2. make user — installs a package holding one hook and one prompt to user scope
   (--target copilot) under an isolated fake $HOME, then uninstalls it
3. See the prompt is removed and reported (Cleaned up 1 integrated prompts),
   while .copilot/hooks/hookpkg-notify.json survives and no hook cleanup is
   reported at all
4. make matrix — repeats install + uninstall at user scope for every hook-capable
   harness; only copilot reports an orphan
5. make project — installs the same package at project scope across all those
   harnesses; every hook is removed

Expected behavior

apm uninstall -g removes the hook files it deployed to ~/.copilot/hooks/, the
same way it removes the package's prompts, and the same way project-scope
uninstall removes Copilot hooks from .github/hooks/. After uninstall no
harness still fires a hook from the removed package.

Environment (please complete the following information):

• OS: Linux (Arch Linux)
• Python Version: 3.14.6
• APM Version: 0.28.0 (e041462)

Logs

make user — prompt cleaned, hook orphaned:

  [+] ./hookpkg (local)
  |-- 1 prompts integrated -> .copilot/prompts/
  |-- 1 hook(s) integrated -> .copilot/hooks/
  |   postToolUse: runs echo hookpkg-ran (notify.json)

[*] Installed 1 APM dependency in 1.9s.
--- deployed under ~/.copilot/ ---
./.copilot/hooks/hookpkg-notify.json
./.copilot/prompts/greet.prompt.md

[i] Uninstalling from user scope (~/.apm/)
[>] Uninstalling 1 package(s)...
[+] _local/hookpkg - found in apm.yml
[i] Removed _local/hookpkg from dependencies.apm in apm.yml
[i] Removed _local/hookpkg from apm_modules/
[+] Cleaned up 1 integrated prompts
[*] Uninstall complete: Removed 1 package(s) from apm.yml, Removed 1 package(s) from apm_modules/
--- after uninstall (prompt gone, hook orphaned) ---
./.copilot/hooks/hookpkg-notify.json

make matrix — user scope, every hook-capable harness:

claude: clean
codex: clean
copilot: ORPHANED ./.copilot/hooks/hookpkg-notify.json
cursor: clean
gemini: clean
windsurf: clean

make project — same package, project scope, all six harnesses:

[+] Cleaned up 1 integrated prompts
[+] Cleaned up 4 integrated commands
[+] Cleaned up 6 integrated hooks
[*] Uninstall complete: Removed 1 package(s) from apm.yml, Removed 1 package(s) from apm_modules/
--- after uninstall (no file still carries the hook command) ---

Additional context

Minimal reproduction: https://github.com/sproott/apm-bugs
(make user / make matrix / make project in
uninstall-copilot-user-hook-orphan/).

[github-actions]

Triage Panel Verdict

Issue: [BUG] apm uninstall -g leaves Copilot hook files in ~/.copilot/hooks/

---

Panel Analysis

DevX UX Expert

Orphaned hooks that continue firing after a package is uninstalled is a serious correctness regression with a visible, reproducible symptom. The reporter provides an isolated test harness (make user / make matrix / make project in a dedicated repo) that cleanly demonstrates the issue across all six hook-capable harnesses -- only copilot at user scope is affected. The expected behavior ("uninstall removes what install deployed") is the most basic contract of a package manager.

Supply Chain Security Expert

A hook from an uninstalled package that remains live in ~/.copilot/hooks/ is orphaned execution wiring: Copilot CLI will keep firing it after the package is gone. If the hook payload was a security-sensitive script, it remains exploitable post-uninstall. This is a security-adjacent concern even if the primary bug is a routing error.

Python Architect

Root cause is precisely diagnosed: in BaseIntegrator.partition_managed_files, the trie built from user_primitive_overrides maps Copilot's instructions primitive to a bare .copilot/ prefix (empty subdir). This catch-all wins over the hook fallback tuple check for .copilot/hooks/ paths, routing hook paths to the instructions_copilot bucket. InstructionIntegrator then discards them (it only handles .copilot/copilot-instructions.md). The fix is to shorten the catch-all trie node or add a specific .copilot/hooks/ entry in the trie so hook paths win by longest-prefix and reach HookIntegrator. The reporter's code citations (base_integrator.py, targets.py, instruction_integrator.py) are accurate.

APM CEO (Arbiter)

Live orphaned hooks after uninstall is a correctness defect that also carries a security-adjacent concern. The root cause is a trie routing priority bug that the reporter has fully traced. High priority, scoped fix.

---

Decision

Dimension	Decision
Type	Bug -- confirmed
Area	CLI
Priority	High
Milestone	omitted -- maintainer to assign

Suggested next action: In src/apm_cli/integration/targets.py (or base_integrator.py), ensure the Copilot user_primitive_overrides for hooks maps to a prefix deeper than .copilot/ (e.g., .copilot/hooks/) so it wins by longest-prefix over the empty-subdir instructions catch-all. Alternatively, add .copilot/hooks/ as an explicit trie node that routes to the hooks bucket. Use the reporter's make matrix test harness as the regression test baseline.

---

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 · 99.5 AIC · ⌖ 6.37 AIC · ⊞ 9.2K · ◷