feat(core): explicit runtime field gates maestro-screenshot self-hosted detection (R2)

[Sriram567]

Summary

Stacks on #2261. Promotes the self-hosted-vs-BrowserStack discriminator in the /percy/maestro-screenshot relay handler from an implicit signal (sessionId absence, introduced by #2261) to an explicit one — runtime: "selfhosted" | "browserstack" in the SDK payload. The sessionId-absent fallback stays for backward compatibility with SDKs that predate the runtime field.

Companion SDK change ships the field in a future @percy/maestro-app release (tracked under percy-maestro/docs/plans/2026-06-02-001-feat-explicit-runtime-field-plan.md Unit 1, blocked behind percy-maestro-app#7). The relay works correctly today with older SDKs via the backward-compat fallback.

Why now

cli#2261's relay handler infers the runtime from a field's absence:

let { name, sessionId } = req.body || {};
let selfHosted = !sessionId;

This works today (R7 verified on BS canary builds #22 and #23). The brittleness: if BS ever omits sessionId in a future code path — a new session type, a retry that doesn't re-inject — the self-hosted branch activates accidentally → wrong file-find scope → 404. Moving the declaration to the SDK (where the knowledge originates — the SDK knows whether PERCY_SESSION_ID was injected) eliminates that future-proofing risk.

The field is also semantically clearer for code review: today sessionId in this handler means "BS App Automate session" but in sibling Appium SDKs it means "Appium driver session UUID" (which exists in both runtimes). Adding runtime makes the wire contract self-documenting.

What changes

packages/core/src/api.js:

let { name, sessionId, runtime } = req.body || {};

// Type validation — but unknown values are NOT rejected (fall back to sessionId).
if (runtime !== undefined && typeof runtime !== 'string') {
  throw new ServerError(400, 'Invalid runtime: must be a string');
}

// Prefer explicit declaration; fall back to sessionId-absent for older SDKs.
let selfHosted = (runtime === 'selfhosted') || (!runtime && !sessionId);

// Diagnostic surface for inconsistencies (debug-only, never breaks the request).
if (runtime === 'browserstack' && !sessionId) {
  percy.log.debug('maestro-screenshot: runtime=browserstack but sessionId missing — trusting runtime field');
}
if (runtime === 'selfhosted' && sessionId) {
  percy.log.debug('maestro-screenshot: runtime=selfhosted but sessionId present — trusting runtime field');
}

The selfHosted boolean propagates through the existing handler logic unchanged — only its source-of-truth shifts from implicit to explicit.

Testing

9 new scenarios under a new describe('runtime field gating') block. Covers the 8-way matrix of (runtime ∈ {undefined, "selfhosted", "browserstack", "unknown-value"}) × (sessionId ∈ {present, absent}) plus the type-validation 400. Pre-existing /percy/maestro-screenshot tests are unchanged.

runtime	sessionId	Expected branch	Verification
"selfhosted"	absent	self-hosted	400 Missing required env: PERCY_MAESTRO_SCREENSHOT_DIR
"selfhosted"	present	self-hosted (trust runtime)	400 same (with debug log)
"browserstack"	present	BS	200 success
"browserstack"	absent	BS (trust runtime)	404 (debug log fires)
"unknown-value"	absent	falls back to self-hosted	400 same
"unknown-value"	present	falls back to BS	200 success
missing	present	BS (back-compat)	200 success
missing	absent	self-hosted (back-compat)	400 same
non-string	—	reject early	400 Invalid runtime: must be a string

R7 (BS regression) preserved — the explicit runtime: "browserstack" + sessionId path runs byte-identically to today's sessionId-only path.

Origin

• Brainstorm: percy-maestro/docs/brainstorms/2026-06-02-selfhosted-followup-bundle-requirements.md (R2)
• Plan: percy-maestro/docs/plans/2026-06-02-001-feat-explicit-runtime-field-plan.md (Unit 2)

Stacking

• Base: feat/self-hosted-maestro-percy-v1 (cli#2261). Rebase to master once feat(cli): self-hosted (non-BrowserStack) Maestro + Percy support — V1 #2261 merges.

Post-Deploy Monitoring & Validation

• What to monitor
  • The two new percy.log.debug lines — they appear when SDK declarations and sessionId presence disagree. Non-zero rate in production would indicate a customer misconfiguration or an upstream BS bug.
  • [BROWSERSTACK_TESTSUITE_PARSE_ERROR] or Screenshot not found rate post-deploy. Should be unchanged.
• Validation checks
  • BS canary regression on both Android (183.177.55.134) and iOS (103.234.68.130) Maestro v2 hosts. Expected: snapshots produce identically pre/post deploy.
  • Self-hosted Pixel + iPhone simulator quickstart from the example repo. Expected: unchanged behavior (SDK ships no runtime field yet; relay falls back to sessionId-absent path).
• Expected healthy signals
  • Zero new [percy] Screenshot not found errors on BS or self-hosted builds compared to baseline.
  • Debug log lines remain quiet in production (no SDK is sending the new field yet).
• Failure signal / rollback trigger
  • Any BS App Automate Maestro build that previously passed reports Snapshot command was not called post-deploy → revert immediately (back-compat path broken).
  • Self-hosted runs that previously worked now 404 → revert (sessionId-absent fallback broken).
• Validation window & owner
  • Window: 7 days post-merge. Owner: Arumulla Sri Ram (arumulla@browserstack.com) + the Percy team.

🤖 Generated with Claude Opus 4.7 via Claude Code + Compound Engineering v2.54.0