feat(scripts): surface duplicate-install cleanup and upgrade discoverability

guide.sh now renders per-install version + active (PATH default) + preferred
(kept) markers for duplicates and offers an inline 'c' action to remove the
non-preferred ones. Adds 'make reconcile-all' (confirm-each) and
'reconcile-all-dry-run' (plan only). The audit readiness line and guide summary
hint at 'make reconcile-all' (when duplicates exist) and 'make upgrade-managed'.
auto_update.sh warns that native manager upgrades bypass cli-audit pins and
project lockfiles before running (skipped on dry-run or FORCE=1).

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>

Author: CybotTM

Makefile

@@ -17,6 +17,7 @@ export
 	install install-dev install-core install-python install-node install-go \
 	install-aws install-kubectl install-terraform install-ansible install-docker \
 	install-brew install-rust install-uv install-% upgrade-% uninstall-% reconcile-% \
+	reconcile-all reconcile-all-dry-run \
 	build build-dist build-wheel check-dist publish-test publish-prod \
 	clean clean-build clean-test clean-pyc clean-all \
 	scripts-perms audit-auto detect-managers upgrade-managed upgrade-dry-run \

Makefile.d/user.mk

@@ -224,6 +224,12 @@ reconcile-%: scripts-perms ## Reconcile tool installation (e.g., make reconcile-
 		echo "Error: No installer found for '$*'" >&2; exit 1; \
 	fi
 
+reconcile-all: scripts-perms ## Remove duplicate installs across ALL tools (confirm each; keeps preferred)
+	@$(PYTHON) audit.py --reconcile --all --apply
+
+reconcile-all-dry-run: scripts-perms ## Preview duplicate-install cleanup across ALL tools (removes nothing)
+	@$(PYTHON) audit.py --reconcile --all
+
 # ----------------------------------------------------------------------------
 # SYSTEM MANAGEMENT
 # ----------------------------------------------------------------------------

cli_audit/render.py

@@ -332,3 +332,16 @@ def _effective(t: dict[str, Any]) -> str:
         f"\nReadiness{offline_tag}: {', '.join(parts)}",
         file=sys.stderr,
     )
+
+    # Discoverability hints (only when relevant)
+    if conflicts > 0:
+        print(
+            f"  → {conflicts} tool(s) with duplicate installs: "
+            "'make reconcile-all' (keeps preferred, removes the rest)",
+            file=sys.stderr,
+        )
+    if outdated > 0:
+        print(
+            "  → upgrade the package managers themselves: 'make upgrade-managed'",
+            file=sys.stderr,
+        )

scripts/auto_update.sh

@@ -843,6 +843,25 @@ run_all_updates() {
   # Determine target scope
   local target_scope="${SCOPE:-$(determine_default_scope)}"
 
+  # Pin/lock override warning: this runs each package manager's own upgrade,
+  # which moves tools past the versions cli-audit pins (pins.json) and any
+  # project lockfiles. Skip the prompt in dry-run or when FORCE=1 (CI).
+  if [ "$DRY_RUN" != "1" ] && [ "${FORCE:-0}" != "1" ]; then
+    printf "[auto-update] ⚠️  This runs each package manager's own upgrade. It moves tools\n" >&2
+    printf "              PAST the versions pinned in cli-audit (pins.json) and any project\n" >&2
+    printf "              lockfiles — pins are NOT enforced here.\n" >&2
+    local ans=""
+    if [ -t 0 ]; then
+      read -r -p "[auto-update] Continue? [y/N] " ans || true
+    elif [ -r /dev/tty ]; then
+      read -r -p "[auto-update] Continue? [y/N] " ans </dev/tty || true
+    fi
+    if [ "$ans" != "y" ] && [ "$ans" != "Y" ]; then
+      log "Aborted (no changes made)."
+      return 0
+    fi
+  fi
+
   log "Starting auto-update for scope: $target_scope"
   echo ""
 

scripts/guide.sh

@@ -16,6 +16,13 @@ CLI="${PYTHON:-python3}"
 # Ignore pins: IGNORE_PINS=1 to show all tools regardless of pin status
 IGNORE_PINS="${IGNORE_PINS:-0}"
 
+# Duplicate-install count for the tool most recently passed to
+# check_multi_installs(); consumed by process_tool to offer inline cleanup.
+LAST_MULTI_COUNT=0
+# Space-separated tool names seen with duplicate installs this run (for the
+# summary hint); de-duplicated when counted.
+GUIDE_DUP_LIST=""
+
 # Summary counters
 SUMMARY_UPDATED=0
 SUMMARY_SKIPPED=0
@@ -33,6 +40,14 @@ print_summary() {
   printf "  Failed:    %d\n" "$SUMMARY_FAILED"
   echo
   echo "Re-run: make audit"
+  local dup_count=0
+  if [ -n "${GUIDE_DUP_LIST// /}" ]; then
+    dup_count="$(printf '%s\n' $GUIDE_DUP_LIST | sort -u | grep -c . || true)"
+  fi
+  if [ "$dup_count" -gt 0 ]; then
+    printf "  → %d tool(s) with duplicate installs: 'make reconcile-all'\n" "$dup_count"
+  fi
+  echo "  → upgrade the package managers themselves: 'make upgrade-managed'"
 }
 
 # Category filter: CATEGORY=python,go or --category=python
@@ -221,11 +236,50 @@ check_multi_installs() {
   local binary_name
   binary_name="$(catalog_get_property "$catalog_tool" binary_name)"
   binary_name="${binary_name:-$catalog_tool}"
+  # Cheap shell pre-check: only pay for the richer reconcile query when there
+  # actually is more than one install (the common case is a single install).
   local all_installs
   all_installs="$(detect_all_installations "$catalog_tool" "$binary_name" 2>/dev/null || true)"
   local install_count
   install_count="$(echo "$all_installs" | grep -c . || true)"
-  if [ "$install_count" -gt 1 ]; then
+  LAST_MULTI_COUNT="$install_count"
+  [ "$install_count" -le 1 ] && return 0
+  GUIDE_DUP_LIST="$GUIDE_DUP_LIST $catalog_tool"
+
+  # Duplicates exist — render version + active + preferred markers from the
+  # reconcile plan (the single source of truth). Fall back to the basic listing
+  # if reconcile produces nothing.
+  local recon_json rendered
+  recon_json="$(cd "$ROOT" && CLI_AUDIT_JSON=1 "$CLI" audit.py --reconcile "$catalog_tool" 2>/dev/null || true)"
+  rendered="$(RECON_JSON="$recon_json" "$CLI" - <<'PY'
+import os, json
+try:
+    doc = json.loads(os.environ.get("RECON_JSON", "").strip())
+    plan = (doc.get("results") or [None])[0]
+    installs = plan.get("installations") or []
+except Exception:
+    raise SystemExit(0)
+if len(installs) < 2:
+    raise SystemExit(0)
+active_path = (plan.get("active") or {}).get("path")
+pref_path = (plan.get("preferred") or {}).get("path")
+lines = [f"    ⚠️  Multiple installations detected ({len(installs)}):"]
+for i in installs:
+    marks = []
+    if i.get("active"):
+        marks.append("→ active")
+    if i.get("preferred"):
+        marks.append("✓ keep")
+    suffix = ("  " + "  ".join(marks)) if marks else ""
+    lines.append(f"       • {i.get('version') or '?'}  {i.get('method')}  {i.get('path')}{suffix}")
+if active_path and pref_path and active_path != pref_path:
+    lines.append(f"       note: cleanup would change which {plan.get('tool')} runs (active → preferred).")
+print("\n".join(lines))
+PY
+)"
+  if [ -n "$rendered" ]; then
+    printf '%s\n' "$rendered"
+  else
     printf "    ⚠️  Multiple installations detected (%d):\n" "$install_count"
     echo "$all_installs" | while IFS=: read -r inst_method inst_path; do
       printf "       • %s: %s\n" "$inst_method" "$inst_path"
@@ -446,6 +500,9 @@ process_tool() {
       printf "      p = Pin to %s (don't ask for upgrades)\n" "$installed"
     fi
     printf "      r = Remove/uninstall this tool\n"
+    if [ "${LAST_MULTI_COUNT:-0}" -gt 1 ]; then
+      printf "      c = Clean up duplicates (keep preferred, remove the rest)\n"
+    fi
     if [ -n "$is_multi_version" ]; then
       printf "      P = Skip ALL outdated %s cycles\n" "$catalog_tool"
     fi
@@ -470,6 +527,9 @@ process_tool() {
     else
       prompt_text="Upgrade? [Y/a/n/s/p/r] "
     fi
+    if [ "${LAST_MULTI_COUNT:-0}" -gt 1 ]; then
+      prompt_text="${prompt_text%] }/c] "
+    fi
   else
     if [ -n "$is_multi_version" ]; then
       prompt_text="Install? [y/a/N/s/p/P] "
@@ -706,6 +766,32 @@ process_tool() {
         printf "    Tool is not installed, nothing to remove\n"
       fi
       ;;
+    [Cc])
+      # Clean up duplicate installations: keep the preferred, remove the rest.
+      # The plan (keep/remove, active marker) was already shown by
+      # check_multi_installs above. Confirm the destructive step, then apply.
+      if [ "${LAST_MULTI_COUNT:-0}" -gt 1 ]; then
+        local ans_c=""
+        if [ -t 0 ]; then
+          read -r -p "    Remove the non-preferred duplicate(s)? [y/N] " ans_c || true
+        elif [ -r /dev/tty ]; then
+          read -r -p "    Remove the non-preferred duplicate(s)? [y/N] " ans_c </dev/tty || true
+        fi
+        if [ "$ans_c" = "y" ] || [ "$ans_c" = "Y" ]; then
+          if (cd "$ROOT" && "$CLI" audit.py --reconcile "$catalog_tool" --apply --yes); then
+            printf "    ✓ Duplicates removed (kept preferred install)\n"
+          else
+            printf "    ⚠️  Cleanup did not complete (tool may be on the protect list)\n"
+          fi
+          CLI_AUDIT_JSON=1 CLI_AUDIT_COLLECT=1 CLI_AUDIT_MERGE=1 "$CLI" audit.py "$tool" >/dev/null 2>&1 || true
+          reload_audit_json
+        else
+          printf "    Skipped cleanup\n"
+        fi
+      else
+        printf "    No duplicate installations to clean up\n"
+      fi
+      ;;
     [P])
       # Skip ALL versions of this runtime (only for multi-version tools)
       if [ -n "$is_multi_version" ]; then

tests/test_reconcile_dryrun.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Guards the safety-critical reconcile invariants at the shell/CLI boundary:
+#   - the dry-run make target must NEVER pass --apply (no removals)
+#   - the real target must pass --apply
+#   - the CLI requires an explicit tool or --all
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$DIR/.." && pwd)"
+PYTHON="${PYTHON:-python3}"
+cd "$ROOT"
+
+pass=0
+fail=0
+check() { # desc, condition-exit-code
+  if [ "$2" -eq 0 ]; then echo "  PASS: $1"; pass=$((pass + 1));
+  else echo "  FAIL: $1"; fail=$((fail + 1)); fi
+}
+
+echo "=== Test: reconcile-all-dry-run never applies ==="
+dryrun_recipe="$(grep -A1 '^reconcile-all-dry-run:' Makefile.d/user.mk | tail -1)"
+echo "$dryrun_recipe" | grep -q -- '--reconcile'; check "dry-run uses --reconcile" $?
+echo "$dryrun_recipe" | grep -q -- '--all'; check "dry-run uses --all" $?
+if echo "$dryrun_recipe" | grep -q -- '--apply'; then check "dry-run must NOT use --apply" 1; else check "dry-run must NOT use --apply" 0; fi
+
+echo "=== Test: reconcile-all applies ==="
+apply_recipe="$(grep -A1 '^reconcile-all:' Makefile.d/user.mk | tail -1)"
+echo "$apply_recipe" | grep -q -- '--apply'; check "reconcile-all uses --apply" $?
+
+echo "=== Test: CLI contract ==="
+"$PYTHON" audit.py --reconcile >/dev/null 2>&1
+check "reconcile without tool/--all exits non-zero" "$([ $? -ne 0 ] && echo 0 || echo 1)"
+
+"$PYTHON" audit.py --help 2>&1 | grep -q -- '--reconcile'
+check "--reconcile listed in --help" $?
+
+echo ""
+echo "Results: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]