fix(core): let BS hosts inject a complete Maestro scope root

[rishigupta1599]

Summary

Follow-up to #2353. That PR assumed the App Automate tmp-dir relocation only moved the root while preserving the {root}/{sessionId}{_test_suite} layout beneath it. That holds on Android but not on iOS.

	Relocated path	What the CLI composes	PERCY_APP_AUTOMATE_TMP_DIR enough?
Android	<aa-tmp>/<device>/test-suites/<sid>_test_suite/logs/*/screenshots/	{TMP}/{sid}_test_suite/logs/*/screenshots/	✅
iOS	<aa-tmp>/<device>/logs/maestro_debug_*/	{TMP}/{sid}/*_maestro_debug_*/	❌

The iOS layout drops the sessionId path segment entirely — the CLI appends it, so no tmp-root value can absorb <device>/logs — and drops the <device>_ prefix that the *_maestro_debug_* glob keys on. Lookups there 404 no matter what PERCY_APP_AUTOMATE_TMP_DIR is set to.

What this adds

PERCY_MAESTRO_BS_SCOPE_ROOT, for layouts the convention can no longer express. When set, the value is the scope root:

• the relay globs {root}/**/{name}.png with no layout assumption
• the manual-walker fallback recurses the same root instead of the platform convention
• the realpath containment check anchors on it

The security boundary is relocated, never widened — an out-of-root filePath still 404s. Non-absolute values are ignored so a malformed injection falls back to the composed convention rather than producing a cwd-relative root. Android (PERCY_APP_AUTOMATE_TMP_DIR) and self-hosted (PERCY_MAESTRO_SCREENSHOT_DIR) are untouched.

No existence pre-check on the override, unlike self-hosted: this is host config, not customer config, so a stale root should surface as the same 404 the containment check emits rather than a 400 aimed at the customer.

Host side

• browserstack/realmobile — injects PERCY_MAESTRO_BS_SCOPE_ROOT (needs this PR released)
• browserstack/mobile — injects PERCY_APP_AUTOMATE_TMP_DIR, fixed by fix(core): follow BS App Automate tmp dir relocation for Maestro screenshots #2353 alone

Both host PRs pin 1.32.5 today; realmobile needs a second bump once this ships.

Test plan

8 new specs in packages/core/test/api.test.js: locating a screenshot the platform convention can't reach, android under the same override, override winning over PERCY_APP_AUTOMATE_TMP_DIR, trailing-slash tolerance, non-absolute fallback, filePath containment re-anchored on the override (in-root resolves, out-of-root 404s), missing root 404, plus direct trim/null assertions on the exported helper.

Local run caveat, stated plainly: every real-fs-fixture spec in api.test.js fails on my machine with ENOTEMPTY from the afterEach rmSync, including blocks this PR doesn't touch. Measured baseline on clean master: 15 failures, all ENOTEMPTY. With this PR: 23 — a delta of exactly the 8 new specs, same environmental cause, no new failure mode. Those blocks need CI to actually be exercised.

Because of that, I verified the logic directly against the real filesystem using the exact relocated layouts — 7/7: helper trim/absolute semantics, #2353-alone still 404ing on the realmobile layout, explicit root locating the file, out-of-root filePath rejected, in-root accepted; plus a separate check that the Android glob still composes correctly from PERCY_APP_AUTOMATE_TMP_DIR.

ESLint clean on all three changed files. (yarn lint for the whole package fails environmentally here — 54 identical "No Babel config file detected" errors across every test file, untouched ones included.)

Ref: PER-10040, AAP-18965

🤖 Generated with Claude Code