feat(shorebird_cli): prepare for Flutter 3.44 libapp.so strip handover

packages/shorebird_cli/lib/src/commands/patch/patch_command.dart

@@ -462,10 +462,43 @@ Building with Flutter $flutterVersionString to determine the release version...
         '--obfuscate',
         '--extra-gen-snapshot-options='
             '--load-obfuscation-map=${obfuscationMapFile.path}',
-        // Strip unobfuscated DWARF debug info from the compiled snapshot so
-        // it doesn't leak identifiers that obfuscation was meant to hide.
-        '--extra-gen-snapshot-options=--strip',
       ]);
+
+      // On Android with Flutter 3.44+, AGP performs the strip on
+      // libapp.so as part of `stripReleaseDebugSymbols` and produces the
+      // matching `.sym` companion that flutter_tools'
+      // post-build verification requires. Passing --strip to gen_snapshot
+      // here would pre-strip the snapshot, leaving AGP nothing to strip,
+      // and flutter_tools would fail the patch build with "libapp.so.sym
+      // or libapp.so.dbg not present". On older Flutter we keep --strip
+      // because the post-build verification does not exist there.
+      //
+      // The version check uses release.flutterRevision (not the user's
+      // currently-installed pin) because the patch's gen_snapshot
+      // behavior must match the release's. See upstream PR
+      // https://github.com/flutter/flutter/pull/181275 (merged 2026-01-26)
+      // and https://github.com/shorebirdtech/_shorebird/issues/2150.
+      final isAndroid =
+          patcher.releaseType.releasePlatform == ReleasePlatform.android;
+      var shouldPreStripInGenSnapshot = true;
+      if (isAndroid) {
+        final releaseFlutterVersion = await shorebirdFlutter
+            .resolveFlutterVersion(release.flutterRevision);
+        final agpStripsLibapp = libappStrippedByAgpConstraint.isSatisfiedBy(
+          version:
+              releaseFlutterVersion ?? libappStrippedByAgpConstraint.minVersion,
+          revision: release.flutterRevision,
+        );
+        shouldPreStripInGenSnapshot = !agpStripsLibapp;
+      }
+
+      if (shouldPreStripInGenSnapshot) {
+        // Strip unobfuscated DWARF debug info from the compiled snapshot
+        // so it doesn't leak identifiers that obfuscation was meant to
+        // hide. On Android 3.44+ this is handled by AGP instead; see the
+        // block above.
+        extraBuildArgs.add('--extra-gen-snapshot-options=--strip');
+      }
     }
     // Flutter requires --split-debug-info with --obfuscate. Auto-add it
     // if --obfuscate will be in the build args (from the user or from

packages/shorebird_cli/lib/src/commands/release/aar_releaser.dart

@@ -85,7 +85,7 @@ class AarReleaser extends Releaser {
     final base64PublicKey = await getEncodedPublicKey();
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
     await artifactBuilder.buildAar(
       buildNumber: buildNumber,
       targetPlatforms: architectures,

packages/shorebird_cli/lib/src/commands/release/android_releaser.dart

@@ -113,7 +113,7 @@ Please comment and upvote ${link(uri: Uri.parse('https://github.com/shorebirdtec
     final base64PublicKey = await getEncodedPublicKey();
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
     final aab = await artifactBuilder.buildAppBundle(
       flavor: flavor,
       target: target,

packages/shorebird_cli/lib/src/commands/release/ios_framework_releaser.dart

@@ -76,7 +76,7 @@ class IosFrameworkReleaser extends Releaser with AppleReleaserMixin {
     final base64PublicKey = await getEncodedPublicKey();
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
     await artifactBuilder.buildIosFramework(
       args: buildArgs,
       base64PublicKey: base64PublicKey,

packages/shorebird_cli/lib/src/commands/release/ios_releaser.dart

@@ -101,7 +101,7 @@ If left checked, Xcode will rewrite the build number in the uploaded IPA, so the
 
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
 
     await artifactBuilder.buildIpa(
       codesign: codesign,

packages/shorebird_cli/lib/src/commands/release/linux_releaser.dart

@@ -75,7 +75,7 @@ To change the version of this release, change your app's version in your pubspec
     final base64PublicKey = await getEncodedPublicKey();
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
     await artifactBuilder.buildLinuxApp(
       target: target,
       args: buildArgs,

packages/shorebird_cli/lib/src/commands/release/macos_releaser.dart

@@ -71,7 +71,7 @@ class MacosReleaser extends Releaser with AppleReleaserMixin {
 
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
 
     await artifactBuilder.buildMacos(
       codesign: codesign,

packages/shorebird_cli/lib/src/commands/release/releaser.dart

@@ -121,18 +121,59 @@ abstract class Releaser {
 
   /// Adds obfuscation-related gen_snapshot options to [buildArgs].
   ///
-  /// When obfuscation is enabled, passes --save-obfuscation-map to capture the
-  /// mapping and --strip to remove unobfuscated DWARF debugging information
-  /// from the compiled snapshot (the DWARF sections would otherwise leak
-  /// identifiers that obfuscation was meant to hide).
-  void addObfuscationMapArgs(List<String> buildArgs) {
+  /// When obfuscation is enabled, passes --save-obfuscation-map to capture
+  /// the mapping. Conditionally passes --strip to remove unobfuscated DWARF
+  /// debugging information from the compiled snapshot, since the DWARF
+  /// sections would otherwise leak identifiers that obfuscation was meant
+  /// to hide.
+  ///
+  /// On Android, --strip is only passed for Flutter versions older than
+  /// 3.44. From 3.44 onward, upstream Flutter PR
+  /// https://github.com/flutter/flutter/pull/181275 (merged 2026-01-26)
+  /// made AGP responsible for stripping `libapp.so` and emitting the
+  /// matching `.sym` companion into the AAB's BUNDLE-METADATA. Passing
+  /// --strip to gen_snapshot on 3.44+ pre-strips the snapshot, leaving AGP
+  /// with nothing to strip. flutter_tools then fails the build with
+  /// "libapp.so.sym or libapp.so.dbg not present when checking final
+  /// appbundle for debug symbols." Letting AGP do the stripping preserves
+  /// the obfuscation protection in the user-shipped APK (AGP uses
+  /// `llvm-strip --strip-unneeded`, which removes the same DWARF sections
+  /// that gen_snapshot --strip would have), while restoring the `.sym`
+  /// companion that 3.44 requires. The `.sym` file containing the
+  /// pre-strip DWARF is only retained in BUNDLE-METADATA, which Play
+  /// strips before delivery to end-user devices, so the only readers are
+  /// the developer's own Play Console crash dashboard.
+  ///
+  /// On non-Android platforms (iOS, macOS, Linux, Windows, iOS framework,
+  /// AAR), AGP is not in the pipeline, so --strip is always passed
+  /// regardless of Flutter version.
+  ///
+  /// Tracked in https://github.com/shorebirdtech/_shorebird/issues/2150.
+  Future<void> addObfuscationMapArgs(List<String> buildArgs) async {
     if (!useObfuscation) return;
     final mapDir = Directory(p.dirname(obfuscationMapPath));
     if (!mapDir.existsSync()) mapDir.createSync(recursive: true);
-    buildArgs.addAll([
+    buildArgs.add(
       '--extra-gen-snapshot-options=--save-obfuscation-map=$obfuscationMapPath',
-      '--extra-gen-snapshot-options=--strip',
-    ]);
+    );
+
+    final isAndroid = releaseType.releasePlatform == ReleasePlatform.android;
+    var shouldPreStripInGenSnapshot = true;
+    if (isAndroid) {
+      final revision = shorebirdEnv.flutterRevision;
+      final version = await shorebirdFlutter.resolveFlutterVersion(revision);
+      final agpStripsLibapp = libappStrippedByAgpConstraint.isSatisfiedBy(
+        version: version ?? libappStrippedByAgpConstraint.minVersion,
+        revision: revision,
+      );
+      // On Flutter 3.44+ AGP performs the strip. Passing --strip here
+      // would pre-strip and trip flutter_tools' post-build verification.
+      shouldPreStripInGenSnapshot = !agpStripsLibapp;
+    }
+
+    if (shouldPreStripInGenSnapshot) {
+      buildArgs.add('--extra-gen-snapshot-options=--strip');
+    }
   }
 
   /// Platform subdirectory for the supplement directory (e.g. 'android',

packages/shorebird_cli/lib/src/commands/release/windows_releaser.dart

@@ -78,7 +78,7 @@ To change the version of this release, change your app's version in your pubspec
     final base64PublicKey = await getEncodedPublicKey();
     final buildArgs = [...argResults.forwardedArgs];
     addSplitDebugInfoDefault(buildArgs);
-    addObfuscationMapArgs(buildArgs);
+    await addObfuscationMapArgs(buildArgs);
     final result = await artifactBuilder.buildWindowsApp(
       target: target,
       args: buildArgs,

packages/shorebird_cli/lib/src/doctor.dart

@@ -19,6 +19,7 @@ class Doctor {
   /// Validators that verify shorebird will work on Android.
   final List<Validator> androidCommandValidators = [
     AndroidInternetPermissionValidator(),
+    LegacyKeepDebugSymbolsValidator(),
   ];
 
   /// Validators that verify shorebird will work on iOS.
@@ -41,6 +42,7 @@ class Doctor {
   List<Validator> initAndDoctorValidators = [
     ShorebirdVersionValidator(),
     AndroidInternetPermissionValidator(),
+    LegacyKeepDebugSymbolsValidator(),
     XcodeprojFlutterOverrideValidator(),
     MacosEntitlementsValidator(),
     ShorebirdYamlAssetValidator(),

packages/shorebird_cli/lib/src/flutter_version_constraints.dart

@@ -93,3 +93,23 @@ final buildTraceSupportConstraint = FlutterSupportConstraint(
     '3b10eecea184bb381f1045a878eeff36548ed11e',
   },
 );
+
+/// Flutter versions where the Android Gradle Plugin (AGP) is the entity
+/// responsible for stripping `libapp.so` and emitting the matching
+/// `libapp.so.sym` companion into the AAB's BUNDLE-METADATA.
+///
+/// Background: upstream Flutter PR
+/// https://github.com/flutter/flutter/pull/181275 (merged 2026-01-26, first
+/// shipped in 3.44) inverted the strip responsibility. Before 3.44, Flutter
+/// stripped `libapp.so` itself before bundling. From 3.44 onward, Flutter
+/// leaves debug symbols in `libapp.so` and expects AGP's
+/// `stripReleaseDebugSymbols` task to strip them and produce a `.sym`
+/// companion file used by Play Console for native crash symbolication.
+/// flutter_tools adds a post-build verification that fatal-errors when the
+/// `.sym` companion is missing.
+///
+/// Shorebird-side fallout tracked in
+/// https://github.com/shorebirdtech/_shorebird/issues/2150.
+final libappStrippedByAgpConstraint = FlutterSupportConstraint(
+  minVersion: Version(3, 44, 0),
+);

packages/shorebird_cli/lib/src/validators/legacy_keep_debug_symbols_validator.dart

@@ -0,0 +1,116 @@
+import 'dart:io';
+
+import 'package:path/path.dart' as p;
+import 'package:shorebird_cli/src/flutter_version_constraints.dart';
+import 'package:shorebird_cli/src/shorebird_env.dart';
+import 'package:shorebird_cli/src/shorebird_flutter.dart';
+import 'package:shorebird_cli/src/validators/validators.dart';
+
+/// Warns when `android/app/build.gradle.kts` (or its Groovy sibling) contains
+/// a legacy `packaging.jniLibs.keepDebugSymbols.add("**/libapp.so")` line on
+/// projects that target Flutter 3.44 or newer.
+///
+/// Background:
+///
+/// Upstream Flutter PR https://github.com/flutter/flutter/pull/181275 (merged
+/// 2026-01-26, first shipped in 3.44) inverted the responsibility for
+/// stripping `libapp.so`. Before 3.44 Flutter stripped the AOT shared library
+/// itself, so users (and the e2e test fixture) added the AGP-level
+/// `keepDebugSymbols` exclusion to keep `libapp.so` byte-stable for Shorebird
+/// patch diffing. From 3.44 onward, Flutter expects the Android Gradle Plugin
+/// (AGP) to strip the library and produce the matching `libapp.so.sym`
+/// companion in the AAB's BUNDLE-METADATA, and flutter_tools adds a
+/// post-build verification that fatal-errors when that companion is missing.
+///
+/// The legacy line tells AGP to skip stripping `libapp.so`, which prevents
+/// the `.sym` from being produced and causes the new verification to fail.
+/// On 3.44+ the line is unnecessary as well as actively harmful, so we surface
+/// a warning that points the user at the exact file and substring to remove.
+///
+/// On older Flutter versions the line is still appropriate and this validator
+/// is a no-op.
+///
+/// Tracked in https://github.com/shorebirdtech/_shorebird/issues/2150.
+class LegacyKeepDebugSymbolsValidator extends Validator {
+  /// The substring we treat as a match. Catches `add(...)` and `+=` forms,
+  /// single-quoted and double-quoted, with arbitrary whitespace around the
+  /// `(` or `+=`, since users may have hand-edited the line.
+  static final _legacyKeepDebugSymbolsPattern = RegExp(
+    r'''keepDebugSymbols\s*(?:\.add\s*\(|\+=)\s*['"][^'"]*\*\*/libapp\.so['"]''',
+  );
+
+  @override
+  String get description =>
+      'android/app/build.gradle(.kts) does not contain a legacy '
+      'keepDebugSymbols line for libapp.so';
+
+  @override
+  bool canRunInCurrentContext() {
+    if (_androidAppDirectory == null) return false;
+    return _gradleFiles.any((f) => f.existsSync());
+  }
+
+  // coverage:ignore-start
+  @override
+  String? get incorrectContextMessage =>
+      'No android/app directory was found, so this validator does not apply.';
+  // coverage:ignore-end
+
+  @override
+  Future<List<ValidationIssue>> validate() async {
+    final flutterRevision = shorebirdEnv.flutterRevision;
+    final flutterVersion = await shorebirdFlutter.resolveFlutterVersion(
+      flutterRevision,
+    );
+    final agpStripsLibapp = libappStrippedByAgpConstraint.isSatisfiedBy(
+      // Treat unknown versions as satisfying the constraint so users who
+      // are pinned to a development revision (where resolveFlutterVersion
+      // returns null) still get the migration nudge. False positives on
+      // unrelated dev branches are preferable to silently missing a real
+      // breakage on the upgrade path.
+      version: flutterVersion ?? libappStrippedByAgpConstraint.minVersion,
+      revision: flutterRevision,
+    );
+    if (!agpStripsLibapp) return [];
+
+    final issues = <ValidationIssue>[];
+    for (final gradleFile in _gradleFiles) {
+      if (!gradleFile.existsSync()) continue;
+      final contents = gradleFile.readAsStringSync();
+      if (!_legacyKeepDebugSymbolsPattern.hasMatch(contents)) continue;
+      final relativePath = p.relative(
+        gradleFile.path,
+        from: shorebirdEnv.getFlutterProjectRoot()!.path,
+      );
+      issues.add(
+        ValidationIssue(
+          severity: ValidationIssueSeverity.warning,
+          message:
+              '$relativePath contains a legacy '
+              '`packaging.jniLibs.keepDebugSymbols.add("**/libapp.so")` '
+              'line. Flutter 3.44 (PR flutter/flutter#181275) requires '
+              'AGP to strip libapp.so and emit a `libapp.so.sym` '
+              'companion. The legacy line blocks AGP from stripping, '
+              'which causes builds to fail or skips Play Console crash '
+              'symbols for Dart code. Remove the line.',
+        ),
+      );
+    }
+    return issues;
+  }
+
+  Directory? get _androidAppDirectory {
+    final root = shorebirdEnv.getFlutterProjectRoot();
+    if (root == null) return null;
+    return Directory(p.join(root.path, 'android', 'app'));
+  }
+
+  List<File> get _gradleFiles {
+    final appDir = _androidAppDirectory;
+    if (appDir == null) return const [];
+    return [
+      File(p.join(appDir.path, 'build.gradle.kts')),
+      File(p.join(appDir.path, 'build.gradle')),
+    ];
+  }
+}

packages/shorebird_cli/lib/src/validators/validators.dart

@@ -6,6 +6,7 @@ import 'package:shorebird_cli/src/shorebird_process.dart';
 
 export 'android_internet_permission_validator.dart';
 export 'flavor_validator.dart';
+export 'legacy_keep_debug_symbols_validator.dart';
 export 'macos_network_entitlement_validator.dart';
 export 'shorebird_version_validator.dart';
 export 'shorebird_yaml_asset_validator.dart';