fix(migration): harden migration script and add .env deprecation guard

Migration script:
- Switch from cp -rn to cp -a (archive mode) for faithful copy
- Marker-based idempotency instead of checking destination contents
- Verify critical files (.claude.json, plugins/, .credentials.json)
- Fix ownership after copy (source may have different uid)
- Rename old directory to .bak on success

Setup.sh:
- Detect stale CLAUDE_CONFIG_DIR=/workspaces/.claude in .env
- Override to $HOME/.claude with warning
- Auto-comment the stale line on disk

Author: AnExiledDev

.devcontainer/CHANGELOG.md

@@ -32,6 +32,8 @@
 - Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
 - Auto-migrates from `/workspaces/.claude/` if `.credentials.json` present
 - `chown` in mcp-qdrant poststart hooks now uses resolved `_USERNAME` instead of hardcoded `vscode` or `$(id -un)`
+- **Migration script hardened** — switched from `cp -rn` to `cp -a` (archive mode); added marker-based idempotency, critical file verification, ownership fixup, and old-directory rename
+- **`.env` deprecation guard** — `setup.sh` detects stale `CLAUDE_CONFIG_DIR=/workspaces/.claude` in `.env`, overrides to `$HOME/.claude`, and auto-comments the line on disk
 
 #### Documentation
 - All docs now reference `~/.claude` as default config path

.devcontainer/scripts/setup-migrate-claude.sh

@@ -3,14 +3,16 @@
 # Migrates config, credentials, and rules from the old bind-mount location
 # to the new home directory (Docker named volume).
 #
-# Safety: uses cp -rn --no-dereference to avoid following symlinks and
-# prevent overwriting files already in the destination.
+# Uses cp -a (archive) for a faithful copy that preserves permissions,
+# timestamps, symlinks, and directory structure. Migration is one-time
+# (marker-gated), so overwrite is safe — the old directory is authoritative.
 
 OLD_DIR="/workspaces/.claude"
 _USERNAME="${SUDO_USER:-${USER:-vscode}}"
 _USER_HOME=$(getent passwd "$_USERNAME" 2>/dev/null | cut -d: -f6)
 _USER_HOME="${_USER_HOME:-/home/$_USERNAME}"
 NEW_DIR="${CLAUDE_CONFIG_DIR:-${_USER_HOME}/.claude}"
+MARKER="$NEW_DIR/.migrated-from-workspaces"
 
 # Nothing to migrate if old directory doesn't exist
 if [ ! -d "$OLD_DIR" ]; then
@@ -22,8 +24,8 @@ if [ -z "$(ls -A "$OLD_DIR" 2>/dev/null)" ]; then
     exit 0
 fi
 
-# Idempotency: skip if destination already has content (migration already done)
-if [ -d "$NEW_DIR" ] && [ -n "$(ls -A "$NEW_DIR" 2>/dev/null)" ]; then
+# Idempotency: skip if migration already completed
+if [ -f "$MARKER" ]; then
     exit 0
 fi
 
@@ -36,11 +38,36 @@ fi
 echo "[setup-migrate] Migrating /workspaces/.claude → $NEW_DIR ..."
 mkdir -p "$NEW_DIR"
 
-# --no-dereference: copy symlinks as symlinks (don't follow them)
-# -n: no-clobber (don't overwrite existing files)
-# -r: recursive
-if cp -rn --no-dereference "$OLD_DIR/." "$NEW_DIR/" 2>/dev/null; then
-    echo "[setup-migrate] Migration complete. You can safely remove /workspaces/.claude/"
+# -a: archive mode (-dR --preserve=all) — preserves permissions, timestamps,
+#     symlinks, ownership, and directory structure faithfully.
+# Errors logged explicitly (no 2>/dev/null) so failures are visible.
+if cp -a "$OLD_DIR/." "$NEW_DIR/"; then
+    # Fix ownership — source files may be owned by a different uid from a
+    # previous container lifecycle. chown everything to the current user.
+    chown -R "$(id -un):$(id -gn)" "$NEW_DIR/" 2>/dev/null || true
+
+    # Verify critical files arrived
+    MISSING=""
+    [ ! -f "$NEW_DIR/.claude.json" ] && [ -f "$OLD_DIR/.claude.json" ] && MISSING="$MISSING .claude.json"
+    [ ! -d "$NEW_DIR/plugins" ] && [ -d "$OLD_DIR/plugins" ] && MISSING="$MISSING plugins/"
+    [ ! -f "$NEW_DIR/.credentials.json" ] && [ -f "$OLD_DIR/.credentials.json" ] && MISSING="$MISSING .credentials.json"
+    if [ -n "$MISSING" ]; then
+        echo "[setup-migrate] WARNING: Migration incomplete — missing:$MISSING"
+        echo "[setup-migrate] Old directory preserved at $OLD_DIR for manual recovery"
+        exit 1
+    fi
+
+    # Mark migration complete
+    date -Iseconds > "$MARKER"
+
+    # Rename old directory to .bak
+    if mv "$OLD_DIR" "${OLD_DIR}.bak" 2>/dev/null; then
+        echo "[setup-migrate] Migration complete. Old directory moved to ${OLD_DIR}.bak"
+    else
+        echo "[setup-migrate] Migration complete. Could not rename old directory — remove /workspaces/.claude/ manually"
+    fi
 else
-    echo "[setup-migrate] WARNING: Some files may not have been copied — verify $NEW_DIR before removing /workspaces/.claude/"
+    echo "[setup-migrate] ERROR: cp failed — check output above for details"
+    echo "[setup-migrate] Old directory preserved at $OLD_DIR"
+    exit 1
 fi

.devcontainer/scripts/setup.sh

@@ -12,6 +12,20 @@ if [ -f "$ENV_FILE" ]; then
     set +a
 fi
 
+# Deprecation guard: .env may still set CLAUDE_CONFIG_DIR=/workspaces/.claude
+# (pre-v2.0 default). Since .env is gitignored, PR updates can't fix it.
+# Override with warning so all child scripts use the correct home location.
+if [ "$CLAUDE_CONFIG_DIR" = "/workspaces/.claude" ]; then
+    echo "[setup] WARNING: CLAUDE_CONFIG_DIR=/workspaces/.claude is deprecated (moved to home dir in v2.0)"
+    echo "[setup]   Updating .devcontainer/.env automatically."
+    CLAUDE_CONFIG_DIR="$HOME/.claude"
+    # Fix the file on disk so subsequent restarts don't trigger this guard
+    if [ -f "$ENV_FILE" ]; then
+        sed -i 's|^CLAUDE_CONFIG_DIR=.*/workspaces/\.claude.*|# CLAUDE_CONFIG_DIR removed (v2.0: now uses $HOME/.claude)|' "$ENV_FILE"
+        echo "[setup]   .env updated — CLAUDE_CONFIG_DIR line commented out."
+    fi
+fi
+
 # Apply defaults for any unset variables
 : "${CLAUDE_CONFIG_DIR:=$HOME/.claude}"
 : "${CONFIG_SOURCE_DIR:=$DEVCONTAINER_DIR/config}"