refactor: split Android native perf collector

[thymikee]

Summary

Split Android native perf from one 741-line collector into focused modules for process/tool resolution, artifact lifecycle, error hint classification, Simpleperf, Perfetto, compact summary shaping, and shared native perf types. The public perf-native.ts surface remains a small facade so existing callers keep the same imports.

Rebased onto latest main after #772. The branch does not touch command-surface files; the merged #772 layout keeps perf/debug/log/network under src/commands/observability, with debug symbols in the same family. Focused command-family tests confirm this PR is compatible with that shape.

Closes #785.

Touched files: 8.

Validation

Focused Android perf/session and command-family coverage passed after rebase: pnpm exec vitest run src/platforms/android/tests/perf.test.ts src/daemon/tests/request-router-android-perf.test.ts src/daemon/handlers/tests/session-observability.test.ts src/commands/observability/index.test.ts src/commands/tests/command-surface-metadata.test.ts src/utils/tests/args.test.ts (6 files, 162 tests). pnpm check:quick passed lint and typecheck. pnpm build passed before the rebase. git diff --check passed after rebase.

Before/after evidence: before, src/platforms/android/perf-native.ts mixed native process resolution, collectors, artifact handling, hints, and summary shaping in one 741-line file. After, the facade is 18 lines and each focused Android native perf module is <=215 LOC while preserving compact artifact-path output and unavailable hints.

pnpm check:unit was rerun twice before the rebase and still failed outside this change area in mocked install/runtime/device/screenshot tests, e.g. src/platforms/tests/install-source.test.ts, src/platforms/android/tests/devices.test.ts, src/platforms/android/tests/index.test.ts, and src/platforms/ios/tests/index.test.ts.

Live emulator smoke was blocked: node bin/agent-device.mjs devices --platform android --json returned an empty device list, and apps --platform android returned DEVICE_NOT_FOUND. Positive Simpleperf capture still requires a booted Android emulator/device, an opened debuggable/profileable app, and a device image that permits perf_event_open; otherwise the expected result is the explicit unavailable/actionable hint path.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	-8 B
JS gzip	409.5 kB	409.5 kB	-43 B
npm tarball	542.6 kB	542.5 kB	-33 B
npm unpacked	1.8 MB	1.8 MB	-8 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.2 ms	27.5 ms	+0.3 ms
CLI --help	52.9 ms	52.4 ms	-0.5 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/2415.js	-8 B	-43 B

[thymikee]

I reran the Android live smoke from an isolated review worktree because the PR body currently says emulator validation was blocked.

Validation passed on a real headless emulator:

• branch: codex/android-native-perf-modules at afc31906c
• build: pnpm build
• focused tests: pnpm exec vitest run src/platforms/android/__tests__/perf.test.ts src/daemon/__tests__/request-router-android-perf.test.ts src/daemon/handlers/__tests__/session-observability.test.ts -> 3 files, 39 tests passed
• emulator: Pixel_9_Pro_XL_API_37, serial emulator-5554
• session: review-788, state dir /private/tmp/agent-device-pr-788-state
• opened com.android.settings successfully
• perf metrics --json: compact startup/fps/memory/cpu result with bounded top memory consumers and worst windows
• perf frames --json: compact frame-health result
• perf trace start --kind perfetto --out /private/tmp/agent-device-pr-788.perfetto-trace --json: started for com.android.settings, app PID 3810, artifact path only
• perf trace stop --kind perfetto --json: stopped successfully, wrote /private/tmp/agent-device-pr-788.perfetto-trace, sizeBytes: 3835964, compact summary plus artifact path
• perf cpu profile start --kind simpleperf --json: preserved the expected unavailable path on this emulator with perf_event_open permission denied and the actionable profileable/permissive-image hint
• cleanup: agent-device close succeeded and emulator was stopped with adb emu kill

Please update the PR body to replace the blocked-live-smoke note with this evidence before merge. I am continuing the code review separately.

[thymikee]

CI has one real blocker:

• Fallow Code Quality fails on an unused export: src/platforms/android/perf-native-errors.ts:41 buildAndroidNativePerfHint

This looks like a simple refactor cleanup: keep buildAndroidNativePerfHint file-local unless another module truly needs it. The rest of the focused validation and live emulator smoke passed in my review comment above.

[thymikee]

I pushed the Fallow cleanup as f999f0d75:

• made buildAndroidNativePerfHint file-local in src/platforms/android/perf-native-errors.ts
• reran ./node_modules/.bin/fallow audit --base origin/main after rebasing onto the latest PR head -> clean

CI should rerun on the new head.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-12 12:28 UTC