Fixes #25120

What

hermes profile install --force and hermes profile update both advertise "user data preserved" in their help text, but _copy_dist_payload() rmtree'd + recopied every directory the distribution ships. Anything the user added inside skills/ after install was silently deleted — including skills installed with hermes skills install, which writes into the same tree. User-added cron/ jobs were deleted the same way.

This is the destructive replacement reported in #25120, implemented along the lines of its "Option B — additive merge", with one refinement for distribution-owned skills (below).

How

A new _replace_dir_merging_user_entries() replaces the wholesale rmtree + copytree in _copy_dist_payload():

• a shipped directory that is a skill root (contains SKILL.md) still replaces its counterpart wholesale, so files dropped or renamed by the new version don't linger inside distribution-owned skills;
• any other shipped directory merges recursively — this covers category folders like skills/devops/ shared by the distribution and hermes skills install --category devops (the exact layout in Bug: hermes profile install/update destructively replaces local skills despite distribution_owned flag #25120's repro);
• shipped files overwrite their counterparts;
• entries the distribution doesn't ship are left untouched.

One semantics change to be aware of: a skill the distribution removes in a new version now lingers in the profile instead of being deleted as a side effect of the mirror. If cleanup of dist-removed skills matters, the follow-up would be payload bookkeeping in the installed manifest (record shipped entries at install; delete previously-shipped-now-absent ones on update). Happy to iterate in that direction if you prefer.

Also removed: the ignore= lambda previously passed to copytree, which was dead code — it only filtered names when the visited directory equaled the staged root, but that copytree started one level below the root, so the predicate never fired. Top-level filtering already happens via the name in USER_OWNED_EXCLUDE guard at the top of the loop; TestNestedUserOwnedExcludeNotFiltered passes unchanged.

The module docstring's "Update semantics" section and the profile update parser description are updated to state the merge behavior, which makes the existing "(user data preserved)" help text on --force and update accurate.

How to test

New tests in tests/hermes_cli/test_profile_distribution.py::TestUserAdditionsSurviveReinstall — written first, red on main, green with this change:

• test_force_install_preserves_user_added_skill
• test_update_preserves_user_added_skill — dist's own skill still receives its new content
• test_update_preserves_user_skill_in_shared_category_dir — Bug: hermes profile install/update destructively replaces local skills despite distribution_owned flag #25120's skills/<category>/<custom-skill> case
• test_update_preserves_user_added_cron_job
• test_update_still_mirrors_dist_shipped_skill_dir — guard: stale files inside a dist-shipped skill must NOT linger (passes before and after)

pytest tests/hermes_cli/test_profile_distribution.py    # 74 passed

End-to-end repro (fails on stock main at e71d746, fixed with this branch):

#!/usr/bin/env bash
set -euo pipefail
HERMES_CMD="${HERMES_CMD:-hermes}"
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT
export HERMES_HOME="$TMP/hermes-home"
mkdir -p "$HERMES_HOME"

DIST="$TMP/demo-dist"
mkdir -p "$DIST/skills/dist-skill"
cat > "$DIST/distribution.yaml" <<'EOF'
name: demodist
version: 0.1.0
description: minimal repro distribution
EOF
printf -- '---\nname: dist-skill\ndescription: shipped by the distribution\n---\n# dist skill\n' \
  > "$DIST/skills/dist-skill/SKILL.md"
printf 'soul\n' > "$DIST/SOUL.md"

$HERMES_CMD profile install "$DIST" --yes >/dev/null

PROFILE="$HERMES_HOME/profiles/demodist"
mkdir -p "$PROFILE/skills/my-skill"
printf -- '---\nname: my-skill\ndescription: added by the user\n---\n# my skill\n' \
  > "$PROFILE/skills/my-skill/SKILL.md"
echo "skills before reinstall: $(ls "$PROFILE/skills" | tr '\n' ' ')"

$HERMES_CMD profile install "$DIST" --yes --force >/dev/null

echo "skills after reinstall:  $(ls "$PROFILE/skills" | tr '\n' ' ')"
if [ -d "$PROFILE/skills/my-skill" ]; then
  echo "OK: user-added skill preserved"
else
  echo "BUG: user-added skill was DELETED"
fi

Before this change: BUG: user-added skill was DELETED. After: OK: user-added skill preserved.

Platforms

macOS (Darwin 25.2.0), Python 3.11.15. Full scripts/run_tests.sh tests/hermes_cli/ run: the only failures (11 tests across 4 gateway/service test files, plus 2 provider files with collection errors) are identical on a pristine main worktree in this environment — pre-existing and unrelated to this change. The code path touched here is platform-independent (pathlib/shutil only).

🤖 Generated with Claude Code