install report: first cut, generated by the helpers

Every run writes a timestamped install-report.md recording what was installed,
changed, kept, skipped, started and run as root. Written for an adversarial read:
the person who just ran a setup script off the internet hands it to an agent of
their choosing and asks whether it did anything it should not have.

Recorded by the HELPERS rather than by the sections. pkg_install and
install_config report themselves, so anything installed or written through them
appears whether or not a section author remembered — a section that has to
remember is a section that will forget, and an incomplete report is worse than
none because it reads as a full account.

"Kept" is recorded as carefully as "changed". Leaving somebody's .zshrc alone is
the claim a reviewer most wants substantiated, and it is invisible unless stated.

Secrets are redacted at the moment of recording rather than filtered at render,
so a credential never sits in memory formatted for printing. Verified against a
POSTGRES_URL and an api_key/password pair.

REPORT_FILE is passed through the sudo re-exec. It was not, first time, and the
report silently vanished — the third variable this evening lost to env_reset.

Unfinished on purpose, paused mid-task at the owner's request: machine-setup's 26
sections still only report through the two shared helpers, so the sections that
change system state directly — systemd units, netplan, ufw, sshd drop-ins — are
not yet recorded. That is the half a reviewer would care most about.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

scripts/setup/machine-setup/lib/files.sh

@@ -43,10 +43,17 @@ install_config() {
 
   if [[ ! -f "$dest" ]]; then
     install -D -m 0644 -o "$owner" -g "$(user_group "$owner")" "$src" "$dest"
+    # Recorded here rather than at the call site: "which files did it write" is
+    # the question a reviewer asks first, and a per-section report would drift
+    # from what this function actually did.
+    declare -F report_changed >/dev/null && report_changed "wrote ${dest} (0644, owner ${owner}) — did not exist"
     return 0
   fi
 
-  cmp -s "$src" "$dest" && return 1
+  if cmp -s "$src" "$dest"; then
+    declare -F report_kept >/dev/null && report_kept "${dest} already identical to the shipped version — not touched"
+    return 1
+  fi
 
   echo ""
   warn "${dest} already exists here, and differs from the one this script ships."
@@ -56,6 +63,7 @@ install_config() {
   # was present to defend.
   if [[ "${ASSUME_YES:-}" == "1" ]] || [[ ! -t 0 ]]; then
     echo "     keeping yours (nothing was asked, so nothing is replaced)"
+    declare -F report_kept >/dev/null && report_kept "${dest} differs from ours and was KEPT — unattended run, nothing replaced"
     return 2
   fi
 
@@ -67,17 +75,20 @@ install_config() {
     if ! read -rp "  Which one? (1/2/3) [1]: " answer; then
       echo ""
       echo "     keeping yours"
+      declare -F report_kept >/dev/null && report_kept "${dest} differs from ours and was KEPT — no answer available"
       return 2
     fi
     case "${answer:-1}" in
       1)
         echo "     keeping yours"
+        declare -F report_kept >/dev/null && report_kept "${dest} differs from ours and was KEPT by choice"
         return 2
         ;;
       2)
         cp -a "$dest" "${dest}.before-machine-setup"
         install -D -m 0644 -o "$owner" -g "$(user_group "$owner")" "$src" "$dest"
         ok "replaced — yours is at ${dest}.before-machine-setup"
+        declare -F report_changed >/dev/null && report_changed "REPLACED ${dest} by choice — previous kept at ${dest}.before-machine-setup"
         return 0
         ;;
       3)