Android capture: stock-UIAutomator fallback removed collaterally in #1217 — decide intended behavior (hard-fail vs disclosed degradation)

[thymikee]

Summary — filing this as a product decision, not a regression report

#1217 (refactor: replace Maestro compat with typed direct engine) removed captureStockUiHierarchy, the
stock-UIAutomator fallback for Android snapshot capture. Behavior change:

	Before #1217	Merged main
helper artifact missing/unbuilt	warn + degrade to stock UIAutomator dump (captures)	hard COMMAND_FAILED — no capture

Verified: captureStockUiHierarchy is gone from src/** entirely (not relocated); pre-#1217 daemons log
"Android snapshot helper unavailable; using stock UIAutomator dump" and capture fine, merged main errors.
Repro: pnpm build (without pnpm build:android) → any Android snapshot → Android snapshot helper is unavailable: the bundled helper artifact was not found.

The hard-fail is arguably the RIGHT behavior — that's why this is a decision, not a bug

The stock fallback was not a harmless degradation. It silently produced a materially different
capture: app-window-only, no systemui/IME, different ordering. That silent difference caused real
confusion repeatedly in the last week's investigations — it was a documented footgun in the E4 work, and it
interacts directly with the chrome filter, divergence screen.refs, and #1264's capture-scope semantics.
Silent degradation to a weaker observation is exactly the failure class this repo has been systematically
eliminating. So failing loudly is defensible on the merits.

But it still needs a deliberate call

The removal happened collaterally inside a Maestro-engine refactor — there's no sign it was a
deliberated product decision, and the deciding case wasn't considered: runtime helper failure on real
devices (OEMs that reject the APK install, permission quirks). Packaged users are fine until they
aren't — and when they aren't, they now lose Android capture entirely instead of degrading.

Options

(a) Keep hard-fail, add an actionable hint. Dev builds: "run pnpm build:android". Packaged: version-
mismatch guidance. Loud, honest, no silent weak observations.

(b) Disclosed degradation. Fall back to stock but stamp the response — backend: "stock-uiautomator" plus a capture-quality marker — so nothing downstream (chrome filter, divergence refs,
capture-scope) can mistake it for a full capture.

(c) Explicit opt-in flag for the stock path.

Recommendation: (a) as the default, plus investigate real-device helper install-failure rates before
deciding whether (b) is warranted as a safety net.

Connection

#1275 / #1281 (Android automation-helper consolidation — one persistent helper owning
snapshot + viewport + injection) make the helper load-bearing platform infrastructure, which weakens the
case for any stock fallback long-term. This decision should be made consistently with that direction.

[thymikee]

Decision record — resolving as option (a): hard-fail with actionable diagnostics, no second snapshot engine, connected to #1301 which closes this on merge.

Where each piece landed:

• (a) actionable hint — shipped in fix(android): actionable error when the snapshot helper is unavailable (#1284) #1285 (merged): source checkouts get run pnpm build:android, packaged installs get reinstall guidance. Verified live during fix(android): return meaningful occluding system surfaces instead of failing the snapshot #1301 validation: a wiped dist produced exactly that error and the hint was sufficient to self-serve recovery.
• The policy is codified in agent-facing text: content-classified failures now carry the hint "…agent-device does not substitute a second snapshot engine", so the decision is legible at the point of failure, not just in ADRs. ADR 0002/0013 amendments from feat(android): one persistent automation helper owning snapshot + viewport + canonical injection #1281 document the single-helper model this issue anticipated in its Connection section.
• The one case where hard-fail was genuinely wrong — the helper faithfully capturing an occluding system surface (notification shade / quick settings) and the classifier rejecting it — is fixed by fix(android): return meaningful occluding system surfaces instead of failing the snapshot #1301: those captures are returned with systemSurfaceOnly + an agent-facing disclosure threaded through direct snapshot AND selector/find/wait routes (including sessionless). That removes the strongest remaining argument for (b): the fallback's real value was masking classifier over-rejection, not surviving missing artifacts.
• (b)/(c) declined: with Android: one persistent automation helper owning snapshot + viewport + canonical injection #1275/feat(android): one persistent automation helper owning snapshot + viewport + canonical injection #1281 making the helper load-bearing for snapshot + viewport + injection, a stock path could only ever serve snapshots — a second, materially different observation engine for one command class, which is the footgun class this issue itself documented.
• Residual rider kept from the issue's recommendation: real-device helper install-failure rates (MDM/Knox-restricted hardware) remain unmeasured. Evidence so far — local emulators and a hosted Limrun Android instance install and run the helper cleanly (Limrun smoke on fix(android): return meaningful occluding system surfaces instead of failing the snapshot #1301). If field data ever shows a meaningful install-failure class, the right response is per-device install diagnostics, not resurrecting the stock engine.

🤖 Addressed by Claude Code