fix(android): actionable error when the snapshot helper is unavailable (#1284)

#1284 kept the hard-fail from #1217 (a silent stock-UIAutomator fallback
produced a materially different, app-window-only capture) but asked for
actionable hints on both failure modes:

- Artifact missing on disk: hint now names the exact `pnpm build:android`
  command, the full dist file set it produces, and notes packaged installs
  ship it via prepack.
- Artifact present but the device rejects the install (adb/OEM policy):
  the underlying adb error already surfaces in the message; the hint now
  explicitly frames this as a device-side failure distinct from a missing
  build artifact, tagged via a new androidSnapshotHelperInstallFailure
  detail set at the adb install call site.

Author: thymikee

src/platforms/android/__tests__/snapshot-helper.test.ts

@@ -204,6 +204,38 @@ test('ensureAndroidSnapshotHelper installs when missing and skips a newer versio
   assert.equal(skipped.reason, 'current');
 });
 
+test('ensureAndroidSnapshotHelper tags a device-side install rejection distinctly from artifact resolution', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-install-reject-'));
+  const apkPath = path.join(tmpDir, 'helper.apk');
+  await fs.writeFile(apkPath, 'helper-apk');
+  const adb: AndroidAdbExecutor = async (args) => {
+    if (args.includes('--show-versioncode')) {
+      return { exitCode: 1, stdout: '', stderr: 'not found' };
+    }
+    if (args[0] === 'install') {
+      return { exitCode: 1, stdout: '', stderr: 'Failure [INSTALL_FAILED_TEST_ONLY]' };
+    }
+    throw new Error(`unexpected adb call: ${args.join(' ')}`);
+  };
+
+  await assert.rejects(
+    () =>
+      ensureAndroidSnapshotHelper({
+        adb,
+        artifact: { apkPath, manifest: { ...manifest, sha256: sha256Text('helper-apk') } },
+      }),
+    (error) => {
+      assert.match((error as Error).message, /Failed to install Android snapshot helper/);
+      assert.equal(
+        (error as { details?: Record<string, unknown> }).details
+          ?.androidSnapshotHelperInstallFailure,
+        true,
+      );
+      return true;
+    },
+  );
+});
+
 test('ensureAndroidSnapshotHelper replaces same-version helper when APK bytes differ', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-identity-'));
   const apkPath = path.join(tmpDir, 'helper.apk');

src/platforms/android/__tests__/snapshot.test.ts

@@ -892,6 +892,56 @@ test('snapshotAndroid emits unavailable diagnostics when helper artifact is miss
   }
 });
 
+test('snapshotAndroid gives an actionable hint when the helper artifact is missing on disk', async () => {
+  const accessSpy = vi.spyOn(fs, 'access').mockRejectedValueOnce(new Error('helper missing'));
+
+  try {
+    await assert.rejects(
+      () => snapshotAndroid(device),
+      (error) => {
+        assert.match((error as Error).message, /the bundled helper artifact was not found/);
+        const hint = String((error as { details?: Record<string, unknown> }).details?.hint);
+        assert.match(hint, /pnpm build:android/);
+        assert.match(hint, /prepack/);
+        assert.match(hint, /\.apk\.idsig/);
+        assert.match(hint, /\.apk\.sha256/);
+        assert.match(hint, /\.manifest\.json/);
+        return true;
+      },
+    );
+  } finally {
+    accessSpy.mockRestore();
+  }
+});
+
+test('snapshotAndroid distinguishes a device-side install rejection from a missing build artifact', async () => {
+  const helperAdb: AndroidAdbExecutor = async (args) => {
+    if (args.includes('--show-versioncode')) {
+      // No installed package reported, so ensureAndroidSnapshotHelper treats the
+      // helper as missing and attempts a real install.
+      return { exitCode: 0, stdout: '', stderr: '' };
+    }
+    if (args[0] === 'install') {
+      return { exitCode: 1, stdout: '', stderr: 'Failure [INSTALL_FAILED_TEST_ONLY]' };
+    }
+    throw new Error(`unexpected adb args: ${args.join(' ')}`);
+  };
+
+  await assert.rejects(
+    () => snapshotAndroidWithHelper(helperAdb),
+    (error) => {
+      const message = (error as Error).message;
+      assert.match(message, /Android snapshot helper failed/);
+      assert.match(message, /Failed to install Android snapshot helper/);
+      assert.match(message, /INSTALL_FAILED_TEST_ONLY/);
+      const hint = String((error as { details?: Record<string, unknown> }).details?.hint);
+      assert.match(hint, /device-side install failure/);
+      assert.doesNotMatch(hint, /pnpm build:android/);
+      return true;
+    },
+  );
+});
+
 test('snapshotAndroid emits timeout diagnostics when helper capture times out', async () => {
   const helperAdb = createHelperAdb({
     instrument: async () => {

src/platforms/android/snapshot-helper-install.ts

@@ -151,6 +151,9 @@ export async function ensureAndroidSnapshotHelper(options: {
     throw androidAdbResultError('Failed to install Android snapshot helper', result, {
       packageName,
       versionCode,
+      // Distinguishes a device-side install rejection (adb/OEM policy) from an
+      // artifact-resolution failure so the capture-layer error can hint accordingly.
+      androidSnapshotHelperInstallFailure: true,
     });
   }
 

src/platforms/android/snapshot.ts

@@ -467,10 +467,13 @@ function androidSnapshotHelperCaptureError(error: unknown, reason: string): AppE
   const busy =
     isStructuredHelperTimeout(normalized.details?.helper, normalized.message) ||
     isKilledHelperInstrumentationFailure(normalized);
+  const installFailure = normalized.details?.androidSnapshotHelperInstallFailure === true;
   const hint = busy
     ? 'Android accessibility snapshots can be blocked by busy or continuously changing app UI. Use screenshot as visual truth after this timeout and report the busy UI if it persists.'
-    : (normalized.hint ??
-      'Retry once. If the helper still fails, run agent-device doctor and report the diagnostic log; agent-device does not substitute a second snapshot engine.');
+    : installFailure
+      ? `${normalized.hint ? `${normalized.hint} ` : ''}This is a device-side install failure (adb rejection or OEM policy) — the helper artifact itself is present, this is not a missing/unbuilt build.`
+      : (normalized.hint ??
+        'Retry once. If the helper still fails, run agent-device doctor and report the diagnostic log; agent-device does not substitute a second snapshot engine.');
   return new AppError(
     toAppErrorCode(normalized.code),
     `Android snapshot helper failed: ${reason}`,
@@ -545,7 +548,7 @@ function androidSnapshotHelperUnavailableError(errorReason: string | undefined):
   const reason = errorReason ?? 'the bundled helper artifact was not found';
   return new AppError('COMMAND_FAILED', `Android snapshot helper is unavailable: ${reason}`, {
     androidSnapshotHelperFailureReason: reason,
-    hint: 'For a source checkout, run pnpm build:android. For a packaged install, reinstall agent-device; the Android snapshot helper must ship with the package.',
+    hint: 'Run `pnpm build:android` to build the full helper dist (android/snapshot-helper/dist: the .apk, .apk.idsig, .apk.sha256, and .manifest.json) for a source checkout. Packaged installs ship this dist automatically via the prepack script — if it is missing from a packaged install, reinstall agent-device.',
   });
 }