feat(deploy): add shadowing guard and evidence-based legacy env migration

deploy/install.sh

@@ -196,9 +196,9 @@ if [ "$FORCE_REFRESH" -eq 1 ] || ! check_assets_present "."; then
     echo "update.sh" >> "$MANIFEST_FILE"
   fi
 
-  if [ -f "$STAGE_DIR/.env.example" ] && [ ! -e ".env.example" ]; then
-    cp "$STAGE_DIR/.env.example" . || { echo "❌ Error: Failed to copy .env.example" >&2; exit 1; }
-    echo ".env.example" >> "$MANIFEST_FILE"
+  if [ -f "$STAGE_DIR/.mam.env.example" ] && [ ! -e ".mam.env.example" ]; then
+    cp "$STAGE_DIR/.mam.env.example" . || { echo "❌ Error: Failed to copy .mam.env.example" >&2; exit 1; }
+    echo ".mam.env.example" >> "$MANIFEST_FILE"
   fi
 
   # Ship the user manual into the target's .agents/ (consistent with install_mam.sh)
@@ -275,9 +275,47 @@ else
 fi
 
 # --- 5. Generate Environment Template ---
-ENV_FILE=".env"
-ENV_EXAMPLE=".env.example"
-if [ ! -f "$ENV_FILE" ]; then
+ENV_FILE=".mam.env"
+ENV_EXAMPLE=".mam.env.example"
+
+# M-2: Evidence-based legacy env migration helper
+migrate_legacy_env() {
+  local manifest=".mam/install_manifest.txt"
+  [ -f ".mam.env" ] && return 0
+  [ -f ".env" ] || return 0
+  if [ "${MAM_LEGACY_ENV_OWNED:-0}" = "1" ] || { [ -f "$manifest" ] && grep -Fqx ".env" "$manifest" 2>/dev/null; }; then
+    mv -f ".env" ".mam.env"
+    chmod 0600 ".mam.env" 2>/dev/null || true
+    if [ -f "$manifest" ]; then
+      if grep -Fqx ".env" "$manifest" 2>/dev/null; then
+        python3 -c '
+import sys
+path = sys.argv[1]
+with open(path, "r") as f:
+    lines = f.readlines()
+with open(path, "w") as f:
+    for line in lines:
+        if line.strip() == ".env":
+            f.write(".mam.env\n")
+        else:
+            f.write(line)
+' "$manifest" 2>/dev/null || true
+      else
+        echo ".mam.env" >> "$manifest"
+      fi
+    fi
+    echo "ℹ️  Legacy MAM config migrated: .env -> .mam.env"
+  else
+    echo "ℹ️  Existing .env left untouched (ownership unproven)."
+    echo "    MAM will read it via the deprecated fallback."
+    echo "    To migrate explicitly: deploy/generate-env.sh --migrate-legacy"
+  fi
+}
+
+migrate_legacy_env
+
+# M-1: Shadowing prevention guard — only create new default config if no legacy env or update tmp exists
+if [ ! -f "$ENV_FILE" ] && [ ! -f ".env" ] && [ ! -f ".env.update-tmp" ]; then
   if [ -f "$ENV_EXAMPLE" ]; then
     echo "📝 Creating configuration from $ENV_EXAMPLE..."
     cp "$ENV_EXAMPLE" "$ENV_FILE"
@@ -297,14 +335,18 @@ MQTT_CLIENT_ID_PREFIX=mam-agent
 HERDR_SERVER_NAME=default
 EOF
   chmod 0600 "$ENV_FILE"
-  echo "✅ Config file .env initialized with chmod 0600."
+  echo "✅ Config file .mam.env initialized with chmod 0600."
   
-  # Record the newly created .env in the manifest
+  # Record the newly created .mam.env in the manifest
   mkdir -p .mam
   touch .mam/install_manifest.txt
   echo "$ENV_FILE" >> .mam/install_manifest.txt
 else
-  echo "ℹ️  $ENV_FILE already exists. Skipping config override."
+  if [ -f "$ENV_FILE" ]; then
+    echo "ℹ️  $ENV_FILE already exists. Skipping config override."
+  else
+    echo "ℹ️  Legacy environment detected. Preserved without shadowing."
+  fi
 fi
 
 echo "===================================================================="