fix: surface stderr excerpts from hand-rolled exec failure wraps

src/kernel/errors.ts

@@ -104,6 +104,8 @@ export function normalizeError(
   };
 }
 
+const GENERIC_EXIT_MESSAGE = /^\S+ exited with code -?\d+$/;
+
 function maybeEnrichCommandFailedMessage(
   code: string,
   message: string,
@@ -114,7 +116,12 @@ function maybeEnrichCommandFailedMessage(
   const stderr = typeof details?.stderr === 'string' ? details.stderr : '';
   const excerpt = firstStderrLine(stderr);
   if (!excerpt) return message;
-  return excerpt;
+  // Generic "<tool> exited with code N" wraps carry no context of their own,
+  // so the stderr excerpt replaces them outright. Curated wrap messages keep
+  // the specific failure description and gain the excerpt as a suffix.
+  if (GENERIC_EXIT_MESSAGE.test(message)) return excerpt;
+  if (message.includes(excerpt)) return message;
+  return `${message}: ${excerpt}`;
 }
 
 function firstStderrLine(stderr: string): string | null {

src/platforms/android/app-helpers.ts

@@ -1,4 +1,5 @@
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import { resolveAppsFilter, type AppsFilter } from '../../contracts/app-inventory.ts';
 import type { AndroidAdbExecutor } from './adb-executor.ts';
 import {
@@ -101,11 +102,11 @@ function parseAndroidLaunchablePackageOutput(stdout: string): string[] {
 async function listAndroidUserInstalledPackagesWithAdb(adb: AndroidAdbExecutor): Promise<string[]> {
   const result = await adb(['shell', 'pm', 'list', 'packages', '-3'], { allowFailure: true });
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to list Android user-installed apps', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to list Android user-installed apps',
+      execFailureDetails(result),
+    );
   }
   return parseAndroidUserInstalledPackages(result.stdout);
 }

src/platforms/android/app-lifecycle.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveFileOverridePath, runCmd, whichCmd } from '../../utils/exec.ts';
+import { execFailureDetails, resolveFileOverridePath, runCmd, whichCmd } from '../../utils/exec.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { sleep } from '../../utils/timeouts.ts';
 import type { AppsFilter } from '../../contracts/app-inventory.ts';
@@ -726,11 +726,11 @@ async function uninstallAndroidApp(device: DeviceInfo, app: string): Promise<{ p
   if (result.exitCode !== 0) {
     const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
     if (!output.includes('unknown package') && !output.includes('not installed')) {
-      throw new AppError('COMMAND_FAILED', `adb uninstall failed for ${resolved.value}`, {
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-      });
+      throw new AppError(
+        'COMMAND_FAILED',
+        `adb uninstall failed for ${resolved.value}`,
+        execFailureDetails(result),
+      );
     }
   }
   return { package: resolved.value };

src/platforms/android/device-input-state.ts

@@ -1,4 +1,5 @@
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import type { DeviceInfo } from '../../kernel/device.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { isClipboardShellUnsupported, sleep } from './adb.ts';
@@ -84,11 +85,11 @@ export async function getAndroidKeyboardStatusWithAdb(
     allowFailure: true,
   });
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to query Android keyboard state', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to query Android keyboard state',
+      execFailureDetails(result),
+    );
   }
   return parseAndroidKeyboardState(result.stdout);
 }
@@ -326,11 +327,11 @@ async function runAndroidClipboardShellCommand(
     );
   }
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', `Failed to ${operation} Android clipboard text`, {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      `Failed to ${operation} Android clipboard text`,
+      execFailureDetails(result),
+    );
   }
   return result.stdout;
 }

src/platforms/android/devices.ts

@@ -1,4 +1,4 @@
-import { runCmd, runCmdDetached, whichCmd } from '../../utils/exec.ts';
+import { execFailureDetails, runCmd, runCmdDetached, whichCmd } from '../../utils/exec.ts';
 import type { ExecResult } from '../../utils/exec.ts';
 import { sleep } from '../../utils/timeouts.ts';
 import { AppError, asAppError } from '../../kernel/errors.ts';
@@ -311,12 +311,13 @@ async function listAndroidAvdNames(): Promise<string[]> {
     timeoutMs: ANDROID_BOOT_PROP_TIMEOUT_MS,
   });
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to list Android emulator AVDs', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-      hint: 'Verify Android emulator tooling is installed and available in PATH.',
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to list Android emulator AVDs',
+      execFailureDetails(result, {
+        hint: 'Verify Android emulator tooling is installed and available in PATH.',
+      }),
+    );
   }
   return parseAndroidAvdList(result.stdout);
 }

src/platforms/android/logcat.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import type { AndroidAdbExecutor, AndroidAdbProcess, AndroidAdbProvider } from './adb-executor.ts';
 
 export type AndroidLogcatCaptureOptions = {
@@ -28,11 +29,11 @@ export async function captureAndroidLogcatWithAdb(
     signal: options.signal,
   });
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to capture Android logcat', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to capture Android logcat',
+      execFailureDetails(result),
+    );
   }
   return result.stdout;
 }

src/platforms/android/multitouch-helper.ts

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { AppError, normalizeError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import { emitDiagnostic, withDiagnosticTimer } from '../../utils/diagnostics.ts';
 import { findProjectRoot, readVersion } from '../../utils/version.ts';
 import type { DeviceInfo } from '../../kernel/device.ts';
@@ -396,12 +397,11 @@ export async function runAndroidMultiTouchHelperGesture(options: {
     );
   }
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Android multi-touch helper failed', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-      helper: output,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Android multi-touch helper failed',
+      execFailureDetails(result, { helper: output }),
+    );
   }
   return output;
 }
@@ -528,13 +528,11 @@ export async function ensureAndroidMultiTouchHelper(options: {
     timeoutMs: ANDROID_MULTITOUCH_HELPER_INSTALL_TIMEOUT_MS,
   });
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to install Android multi-touch helper', {
-      packageName,
-      versionCode,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to install Android multi-touch helper',
+      execFailureDetails(result, { packageName, versionCode }),
+    );
   }
   installedMultiTouchHelpers.add(cacheKey);
   return {

src/platforms/android/perf.ts

@@ -2,6 +2,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import type { DeviceInfo } from '../../kernel/device.ts';
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import { splitNonEmptyTrimmedLines } from '../../utils/parsing.ts';
 import { resolveAndroidAdbExecutor, type AndroidAdbExecutor } from './adb-executor.ts';
 import { parseNumericToken } from './perf-parsing.ts';
@@ -133,16 +134,13 @@ export async function captureAndroidHeapSnapshot(
       throw new AppError(
         'COMMAND_FAILED',
         `Failed to capture Android heap dump for ${packageName}`,
-        {
+        execFailureDetails(dumpResult, {
           kind: 'android-hprof',
           package: packageName,
           pid,
           remotePath,
-          exitCode: dumpResult.exitCode,
-          stdout: dumpResult.stdout,
-          stderr: dumpResult.stderr,
           hint: resolveAndroidHeapDumpHint(dumpResult.stdout, dumpResult.stderr),
-        },
+        }),
       );
     }
 
@@ -152,17 +150,18 @@ export async function captureAndroidHeapSnapshot(
     });
     if (pullResult.exitCode !== 0) {
       await cleanupLocalArtifact(outPath, hadLocalArtifact);
-      throw new AppError('COMMAND_FAILED', `Failed to pull Android heap dump for ${packageName}`, {
-        kind: 'android-hprof',
-        package: packageName,
-        pid,
-        remotePath,
-        path: outPath,
-        exitCode: pullResult.exitCode,
-        stdout: pullResult.stdout,
-        stderr: pullResult.stderr,
-        hint: 'Verify the daemon can write the requested --out path and retry. The heap dump stays on-device only until cleanup runs.',
-      });
+      throw new AppError(
+        'COMMAND_FAILED',
+        `Failed to pull Android heap dump for ${packageName}`,
+        execFailureDetails(pullResult, {
+          kind: 'android-hprof',
+          package: packageName,
+          pid,
+          remotePath,
+          path: outPath,
+          hint: 'Verify the daemon can write the requested --out path and retry. The heap dump stays on-device only until cleanup runs.',
+        }),
+      );
     }
 
     const stat = await fs.stat(outPath).catch(() => null);

src/platforms/android/settings.ts

@@ -1,4 +1,5 @@
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import type { DeviceInfo } from '../../kernel/device.ts';
 import { requireLocationCoordinates } from '../../utils/location-coordinates.ts';
 import {
@@ -252,11 +253,11 @@ async function resolveAndroidAppearanceTarget(
     allowFailure: true,
   });
   if (currentResult.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Failed to read current Android appearance', {
-      stdout: currentResult.stdout,
-      stderr: currentResult.stderr,
-      exitCode: currentResult.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to read current Android appearance',
+      execFailureDetails(currentResult),
+    );
   }
   const current = parseAndroidAppearance(currentResult.stdout, currentResult.stderr);
   if (!current) {

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

@@ -1,4 +1,5 @@
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import type { SnapshotOptions } from '../../kernel/snapshot.ts';
 import {
   parseInstrumentationRecords,
@@ -58,12 +59,11 @@ export async function captureAndroidSnapshotWithHelper(
     await removeHelperOutputFile(options.adb, resolved.outputPath);
   }
   if (result.exitCode !== 0) {
-    throw new AppError('COMMAND_FAILED', 'Android snapshot helper failed', {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-      helper: output.metadata,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Android snapshot helper failed',
+      execFailureDetails(result, { helper: output.metadata }),
+    );
   }
   return output;
 }

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

@@ -1,4 +1,5 @@
 import { AppError } from '../../kernel/errors.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import {
   readAndroidSnapshotHelperInstallOptions,
   verifyAndroidSnapshotHelperArtifact,
@@ -117,13 +118,11 @@ export async function ensureAndroidSnapshotHelper(options: {
   );
   if (result.exitCode !== 0) {
     forgetInstalledSnapshotHelper(installCacheKey);
-    throw new AppError('COMMAND_FAILED', 'Failed to install Android snapshot helper', {
-      packageName,
-      versionCode,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Failed to install Android snapshot helper',
+      execFailureDetails(result, { packageName, versionCode }),
+    );
   }
 
   rememberInstalledSnapshotHelper(installCacheKey, versionCode);

src/platforms/android/snapshot.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { withRetry } from '../../utils/retry.ts';
+import { execFailureDetails } from '../../utils/exec.ts';
 import { AppError, normalizeError, toAppErrorCode } from '../../kernel/errors.ts';
 import { emitDiagnostic, withDiagnosticTimer } from '../../utils/diagnostics.ts';
 import type { DeviceInfo } from '../../kernel/device.ts';
@@ -682,12 +683,11 @@ async function dumpUiHierarchyOnce(adb: AndroidAdbExecutor): Promise<string> {
   });
   const reportedPath = readDumpPath(dumpResult.stdout, dumpResult.stderr);
   if (dumpResult.exitCode !== 0 && !reportedPath) {
-    throw new AppError('COMMAND_FAILED', 'uiautomator dump did not return XML', {
-      stdout: dumpResult.stdout,
-      stderr: dumpResult.stderr,
-      exitCode: dumpResult.exitCode,
-      reason: 'missing_fresh_dump',
-    });
+    throw new AppError(
+      'COMMAND_FAILED',
+      'uiautomator dump did not return XML',
+      execFailureDetails(dumpResult, { reason: 'missing_fresh_dump' }),
+    );
   }
   const actualPath = reportedPath ?? dumpPath;