fix(bluefin): migrate legacy home paths for GNOME Trash

Rewrite persistent /var/home home fields to the bind-mounted /home layout before desktop services start, preventing GNOME path-based Trash operations from resolving inconsistently.

Closes #1184

Assisted-by: GPT-5.6 Luna via GitHub Copilot

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: castrojo

docs/skills/actionadon.md

@@ -94,3 +94,13 @@ Implications for agents:
 - [ ] Only queued work was claimed
 - [ ] No comments duplicated existing widget state
 - [ ] Hardware confirmation state was considered before treating the loop as closed
+
+## Lessons Learned
+
+### Legacy passwd home paths can break GNOME file operations (2026-07-31)
+
+When Dakota changed `/home` from a symlink into a bind mount, upgrades could
+retain `/var/home/<user>` in `/etc/passwd`. That stale path can make GNOME
+path-based operations such as sending files to Trash resolve inconsistently.
+The boot-time migration must rewrite those fields to `/home/<user>` before user
+sessions and desktop services start.

elements/bluefin/deps.bst

@@ -65,6 +65,7 @@ depends:
   - gnome-build-meta.bst:gnomeos-deps/wl-clipboard.bst
 
   - bluefin/bindmounts.bst
+  - bluefin/migrate-var-home-passwd.bst
 
   - gnome-build-meta.bst:gnomeos-deps/snapd.bst
 

elements/bluefin/migrate-var-home-passwd.bst

@@ -0,0 +1,35 @@
+kind: manual
+description: |
+  One-shot, idempotent boot-time migration of legacy /var/home/<user> (and
+  /var/roothome) passwd home fields to the post-#1117 bind-mount layout.
+  Installs from before 2026-06-29 carry the old fields, which breaks snapd
+  and makes path-identity comparisons disagree, which can break GNOME file
+  operations such as sending files to Trash; see projectbluefin/dakota#1184.
+
+  Ships the migration script, its oneshot unit (ordered before
+  systemd-user-sessions), and a preset to enable it.
+
+sources:
+- kind: local
+  path: files/migrate-var-home-passwd
+
+build-depends:
+- freedesktop-sdk.bst:public-stacks/runtime-minimal.bst
+
+variables:
+  strip-binaries: ""
+
+config:
+  install-commands:
+  - |
+    install -Dm755 bluefin-migrate-var-home-passwd \
+            "%{install-root}/usr/libexec/bluefin-migrate-var-home-passwd"
+  - |
+    install -Dm644 bluefin-migrate-var-home-passwd.service \
+            "%{install-root}%{indep-libdir}/systemd/system/bluefin-migrate-var-home-passwd.service"
+  - |
+    PRESET="%{install-root}%{indep-libdir}/systemd/system-preset/80-bluefin-migrate-var-home-passwd.preset"
+    install -Dm644 /dev/null "$PRESET"
+    cat > "$PRESET" <<'PRESET'
+    enable bluefin-migrate-var-home-passwd.service
+    PRESET

files/migrate-var-home-passwd/bluefin-migrate-var-home-passwd

@@ -0,0 +1,69 @@
+#!/usr/bin/bash
+# One-shot migration of legacy home fields in /etc/passwd: /var/home/<user>
+# -> /home/<user>, /var/roothome -> /root. Installs from before PR #1117
+# (2026-06-29) carry the old-layout fields, which breaks snapd and makes
+# bind-mount path-identity comparisons disagree. Full background:
+# projectbluefin/dakota#1170.
+#
+# The write is delegated to usermod (no -m: passwd field only, no data
+# moves) so locking and atomic replace are the canonical lckpwdf ones;
+# flock(2) would not interoperate. Deliberately no sentinel file: the grep
+# fast path is cheap and self-heals if a stale entry is ever reintroduced.
+#
+# MIGRATE_PREFIX=/some/dir operates on $MIGRATE_PREFIX/etc/passwd (passed
+# to usermod --prefix); tests only, leave unset in production.
+
+set -euo pipefail
+
+PREFIX="${MIGRATE_PREFIX:-}"
+PASSWD="${PREFIX}/etc/passwd"
+
+log() { echo "bluefin-migrate-var-home-passwd: $*"; }
+
+if [ ! -r "$PASSWD" ]; then
+    log "no readable $PASSWD; nothing to do"
+    exit 0
+fi
+
+# Nothing to migrate -> exit before taking any lock.
+if ! grep -qE ':(/var/home/|/var/roothome)(:|$)' "$PASSWD"; then
+    exit 0
+fi
+
+declare -a UARGS=()
+[ -n "$PREFIX" ] && UARGS+=(--prefix "$PREFIX")
+
+rc=0
+migrated=0
+
+# The loop holds the original inode open while usermod renames in new ones,
+# so every decision is made against a consistent pre-migration snapshot.
+while IFS=: read -r login _ _ _ _ home _; do
+    [ -n "$login" ] || continue
+    case "$home" in
+        /var/roothome)
+            new="/root"
+            ;;
+        /var/home/*)
+            new="/home/${home#/var/home/}"
+            ;;
+        *)
+            continue
+            ;;
+    esac
+
+    set +e
+    usermod "${UARGS[@]}" -d "$new" "$login"
+    uc=$?
+    set -e
+    if [ "$uc" -eq 0 ]; then
+        log "migrated $login: $home -> $new"
+        migrated=$((migrated + 1))
+    else
+        log "FAILED to migrate $login: $home -> $new (usermod rc=$uc)"
+        rc=1
+    fi
+done < "$PASSWD"
+
+log "done; migrated ${migrated} user(s)"
+exit "$rc"

files/migrate-var-home-passwd/bluefin-migrate-var-home-passwd.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=Migrate legacy /var/home home paths in /etc/passwd to /home
+Documentation=https://github.com/projectbluefin/dakota/issues/1170
+After=local-fs.target
+# Must rewrite passwd before anything reads it for a session:
+# systemd-user-sessions gates all logins, accounts-daemon caches home fields.
+Before=systemd-user-sessions.service
+Before=accounts-daemon.service
+Before=display-manager.service
+Before=gdm.service
+ConditionPathExists=/etc/passwd
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/libexec/bluefin-migrate-var-home-passwd
+
+[Install]
+WantedBy=multi-user.target