@keepsnappy/agent 0.1.0-alpha.15 → 0.1.0-alpha.17

package/README.md

@@ -70,7 +70,7 @@ Annotated example: `examples/keepsnappy.yml`. Every setting:
 
 Unknown settings and wrong types are errors, all listed together.
 
-Results and exit codes: results never change the exit code by default (ruling D9, no blocking PR checks): `0` also for "More work". `--fail-on-worse` (needs `--wait`) makes "More work" exit `3`. The CLI exits `2` for a configuration problem (bad or missing `keepsnappy.yml`, flags, a glob matching nothing, `--wait` without a branch or key) and `1` for an infrastructure problem (cannot read the device log, an API request failing; results stay in the out dir). Failed runs are marked invalid in `runs.ndjson` / `metrics.csv` and ignored by the statistics. The ending summary reads like:
+Results and exit codes: results never change the exit code by default (ruling D9, no blocking PR checks): `0` also for "More work". `--fail-on-worse` (needs `--wait`) fails the job (exit `3`) only when the verdict computed on that run set is Worse and blocking. Closing a run set never computes its verdict (decision 0031: the operator computes verdicts on demand), so with no computed verdict `--fail-on-worse` checks nothing: the CLI prints `Verdict not computed yet (computed on demand): --fail-on-worse checked nothing` and exits `0`. The CLI exits `2` for a configuration problem (bad or missing `keepsnappy.yml`, unknown or misspelt flags, a glob matching nothing, `--wait` without a branch or key) and `1` for an infrastructure problem (cannot read the device log, an API request failing, an API URL that does not answer as the KeepSnappy API, `--upload` that sent no run: "Blocked"; results stay in the out dir). Failed runs are marked invalid in `runs.ndjson` / `metrics.csv` and ignored by the statistics. The ending summary reads like:
 
 ```
 7/8 runs valid (dropped: 1 test-failed: exit 1)
@@ -103,10 +103,12 @@ keepsnappy farm open --api https://keepsnappy-api-….run.app --branch main --co
 keepsnappy farm close --state farm-run/keepsnappy-farm.json --bs-build farm-run/browserstack.ios.json --settle-seconds 60 --wait
 ```
 
-`keepsnappy farm run` does the whole night in one command (docs/plans/54a): resolve the app (`--app eas:<id>|file|bs://`), `farm open`, an optional BrowserStack Local tunnel (`--tunnel-for localhost:<port>`, repeatable), the device run (`--driver maestro` with `--suite-dir`/`--execute`, or `--driver appium --journey-module FILE` for the built-in Appium driver, `@keepsnappy/appium-driver`, docs/plans/54b; `--driver-script FILE` still runs your own driver), `farm close`, and cleanup (tunnel stopped, tokens file reset) whatever happened. `--env KEY=VALUE` values may use `{tunnel:<port>}`, `{run_id}`, `{out}`, `{tokens_js}`, `{run_set_id}`. Exit codes as `farm close`; a failed device run is 1. `--dry-run` prints the plan with no request. Needs `KEEPSNAPPY_KEY`, `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` (and `EXPO_TOKEN` for `eas:`).
+`keepsnappy farm run` does the whole night in one command (docs/plans/54a): resolve the app (`--app eas:<id>|file|bs://<id>|custom_id:<id>`), `farm open`, an optional BrowserStack Local tunnel (`--tunnel-for localhost:<port>`, repeatable), the device run (`--driver maestro` with `--suite-dir`/`--execute`, or `--driver appium --journey-module FILE` for the built-in Appium driver on iOS or Android, `@keepsnappy/appium-driver`, docs/plans/54b; `--driver-script FILE` still runs your own driver), `farm close`, and cleanup (tunnel stopped, tokens file reset) whatever happened. `--env KEY=VALUE` values may use `{tunnel:<port>}`, `{run_id}`, `{out}`, `{tokens_js}`, `{run_set_id}`. Pre-uploaded `bs://` and `custom_id:` app references pass through without a file upload. Appium uses `--timeout-minutes 80` by default: the driver receives SIGTERM at the timeout, then SIGKILL after `--kill-after-seconds 120` if it has not exited. A timeout is recorded in the failure message, including the terminating signal, and returns exit 1 even if the driver exits zero after SIGTERM. Exit codes as `farm close`; a failed device run is 1. `--dry-run` prints the plan with no request. Needs `KEEPSNAPPY_KEY`, `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` (and `EXPO_TOKEN` for `eas:`).
 
 Setup and completion (plan 51 stage 2): `--completion-marker` declares that the flow posts the step marker `run:complete` (end) at the end of every iteration, from the main flow and not from `onFlowComplete`; the API then marks a run without it invalid (`flow-incomplete`). `--driver-version`, `--app-build-id`, `--harness-version`, `--flag-set` go into every run's setup fingerprint; `farm close` adds the device farm's build id from `--bs-build`.
 
+The model a phone is stored under is the hardware code the OS reports (`SM-S911B`, `iPhone17,1`); the marketing name is only shown. With `--platform android|ios`, `--device-provider local|usb|customer|simulator|emulator` (the default `browserstack` needs an explicit model: a farm's phone is not on this machine) and no `--device-model`, `farm open` reads it from the device: Android `adb [-s <serial>] shell getprop ro.product.model`, an iPhone's machine id from `xcrun devicectl list devices`, a simulator's name from `xcrun simctl list devices` (kept with its "Simulator" word, so it never joins a real phone's row). With `--platform ios` and a `--device-id` that `xcrun simctl` lists as a simulator, `farm open` opens the run set as a simulator whatever provider and model were typed: provider `simulator`, the model with the "Simulator" word. It reads nothing it cannot pin to exactly one device (`--device-id` picks one); then `--device-model` is required. A typed `--device-model` is for a device this machine cannot ask (a farm's phone) and is sent as given.
+
 `farm open` also sends `journeys[]`: with `--config keepsnappy.yml` and/or `--flows <files|dirs|globs,...>` each `--journeys` name is matched to the flow file named like it (title, description, source path as for `keepsnappy run`); without them, keys only.
 
 `farm open` makes a run set (`source: farm`, the device of `--device-model/--device-os`: the journey history is keyed by
@@ -143,7 +145,8 @@ runner. It writes:
 
 Running it again is safe: finished runs are left alone, the set is not reprocessed, the same result is printed. A batch
 that arrives after a run was finished is added by the server and the run re-processed at once. Exit codes: `0` for any
-result, `3` with `--fail-on-worse` on "More work", `2` for configuration, `1` when the API fails or nothing could be
+result, `3` with `--fail-on-worse` when the verdict computed on that run set is Worse and blocking (with no computed
+verdict it checks nothing and says so, exit `0`), `2` for configuration, `1` when the API fails or nothing could be
 judged ("Blocked": no iteration sent any data).
 
 Slack: set `KEEPSNAPPY_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close --wait` posts the
@@ -176,25 +179,31 @@ same words (`packages/mcp/README.md`).
 ```sh
 export KEEPSNAPPY_KEY=pl_rk_…        # a project key with read scope (a CI key with run scope works too)
 keepsnappy findings --branch feat/keepsnappy-integration     # what got worse or better on a PR, worst first
+keepsnappy status --branch feat/keepsnappy-integration       # is my PR ok? one answer: blocked / nothing blocks / ok, per journey × phone, ids of the worst findings, links
 keepsnappy findings --main --journey live-ui --phone "iPhone 15"
 keepsnappy findings --state all --json                    # also the resolved and not judged ones, as the API's JSON
 keepsnappy findings --state all --offset 200              # the next page (at most 200 per answer)
 keepsnappy finding f_0123456789abcdef                     # one finding with its evidence
 keepsnappy finding f_0123456789abcdef --prompt | pbcopy   # only the hand-off for a coding agent, ending with its id and page
 keepsnappy compare <runA> <runB>                          # two runs (ids or external ids), window by window, no statistics
-keepsnappy history live-ui "Tap: live chat send"          # one window on main, run by run (id or name)
+keepsnappy history live-ui press:live.chat.send           # one window on main, run by run (exact place id)
 keepsnappy commits a1b2c3d c3d4e5f [--branch main]        # the measured commits between two points
+keepsnappy places --journey live-ui --phone "iPhone 15"   # every place of the newest main session from its stored statistics, no verdict
+keepsnappy places --run-set <id> --measure commit_max_ms --sort p90 --limit 10
 keepsnappy layers                                         # which layer answers which question, and its certificate
+keepsnappy findings --branch feat/x --short               # the short form: what decides, no evidence detail (also status, finding, history, places, main, trend)
+keepsnappy trend live-ui Tap: live chat send --phone "iPhone 15"   # the words after the journey are one window name; more windows with repeated --window
 ```
 
-Flags: `--api URL` (or `KEEPSNAPPY_API`, default the hosted API), `--key-env NAME` (default `KEEPSNAPPY_KEY`), `--json`.
+Flags: `--api URL` (or `KEEPSNAPPY_API`, default the hosted API), `--key-env NAME` (default `KEEPSNAPPY_KEY`), `--json`, `--short`.
+`--short` prints the same text with the evidence detail left out (the MCP tools' `form: "short"`); its last line says what was left out, and the MCP tool descriptions list it per answer. `--json` is the same with or without it.
 A finding's id is stable: the same window, measure, journey and phone model keep the id across commits and PRs, so
 `keepsnappy finding <id>` after a fix tells whether it is resolved. `--state` (default `present`) filters on the state on
 the asked branch: `present` (in the newest run set), `resolved` (the newest run set judged the measure: No change, or the
 other way), `not-judged` (the newest run set did not judge it: not measured, unstable, not enough data; it may still be
 there). A list starts with whether and when the branch was measured ("No KeepSnappy measurement on branch X", or the
 newest measured commit, its word and runs), so an empty list on an unmeasured branch does not read as clean. `commits`
-lists each measured commit once, with how many sessions measured it. Words come from the one word table (Worse / Warning / Better …), "Worse (not blocking)" when the
+lists each measured commit once, with how many sessions measured it. `places` lists the places of one session (a run set, or the newest closed one of a journey on a phone and branch) with each measure's median, spread and the components with the most own time, ranked by `--measure` and `--sort`; a session without stored statistics says `not computed`, never zero. Words come from the one word table (Worse / Warning / Better …), "Worse (not blocking)" when the
 branch was measured differently from main.
 
 ## Output layout
@@ -257,3 +266,24 @@ Memory slopes (Theil-Sen over the cycle index, 3+ cycles of `--mem-window`, defa
 verdicts, profile-analysis, mcp), so both work from a clean checkout.
 
 Only `keepsnappy` and `keepsnappy.yml` / `keepsnappy.yaml` are supported. Configure `KEEPSNAPPY_*` variables. Explicit `--key-env`, `project.key_env`, and `--config` remain arbitrary user-supplied names and paths.
+
+### Source maps from an EAS build
+
+In an `eas-build-on-success` hook, run:
+
+```sh
+npx @keepsnappy/agent sourcemaps upload --eas
+```
+
+`--eas` runs only when `EAS_BUILD_PROFILE=e2e`. It uses `EAS_BUILD_GIT_COMMIT_HASH` as the build commit and `EAS_BUILD_PLATFORM` to select the map relative to the working directory:
+
+| Platform | Map | Kind |
+| --- | --- | --- |
+| `ios` | `main.jsbundle.packager.map` | `packager` |
+| `android` | `android/app/build/generated/sourcemaps/react/release/index.android.bundle.map` | `hermes` |
+
+The iOS packager map preserves the positions used by CPU profiles; Android profiles use the composed Hermes map. The upload flavour defaults to `e2e`.
+
+Set `KEEPSNAPPY_KEY` or `KEEPSNAPPY_CI_KEY` and `KEEPSNAPPY_API` or `EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL`. The usual key/API names take precedence over the EAS hook names. Explicit `--key-env`, `--api`/`--ingest-url`, `--build`, `--platform`, `--kind`, `--flavour` and map files override these defaults. An explicit `--key-env` uses only that variable.
+
+A missing key, API URL, commit or map, an unsupported platform, or a profile other than `e2e` produces one skip line and exits 0. There is no default API URL in EAS mode. Upload, map parsing and argument failures also exit 0 with a generic failure line so the application build stays successful and error details cannot expose credentials. Ordinary `sourcemaps upload` keeps its existing validation and failure behavior. Source text (`sourcesContent`) is stripped before upload in both modes.

package/dist/appium-driver.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // packages/appium-driver/src/load.ts
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // packages/appium-driver/src/run.ts
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
 import { parseArgs } from "node:util";
 
 // packages/appium-driver/src/browserstack.ts
@@ -303,6 +303,10 @@ class WdError extends Error {
     this.wdError = wdError;
   }
 }
+var IOS_BOTTOM_INSET_PT = 34;
+var GESTURE_ZONE_MARGIN_PT = 16;
+var ANDROID_NAV_BAR_FALLBACK_DP = 48;
+var GESTURE_ZONE_MARGIN_DP = 16;
 
 class Driver {
   bundleId;
@@ -314,8 +318,11 @@ class Driver {
   now;
   sleep;
   sessionId = null;
+  deviceUnit;
   context = {};
   viewport = null;
+  pxPerDp = null;
+  bottomLimit = null;
   rects = new Map;
   constructor(o) {
     this.bundleId = o.bundleId;
@@ -355,6 +362,7 @@ class Driver {
   async start(capabilities) {
     const value = await this.cmd("POST", "/session", { capabilities: { alwaysMatch: capabilities } });
     this.sessionId = value.sessionId;
+    this.deviceUnit = [value.capabilities?.udid, value.capabilities?.deviceUDID].find((unit) => typeof unit === "string" && unit.length > 0);
     return value;
   }
   execute(script, arg) {
@@ -379,6 +387,29 @@ class Driver {
     this.viewport ??= await this.cmd("GET", "/window/rect");
     return this.viewport;
   }
+  async density() {
+    if (this.pxPerDp === null) {
+      const dpi = Number(await this.execute("mobile: getDisplayDensity"));
+      if (!(dpi > 0))
+        throw new Error(`mobile: getDisplayDensity answered ${dpi}, not a density`);
+      this.pxPerDp = dpi / 160;
+    }
+    return this.pxPerDp;
+  }
+  async safeBottomY() {
+    if (this.bottomLimit === null) {
+      const { height } = await this.screen();
+      if (this.platform.name === "ios") {
+        this.bottomLimit = height - IOS_BOTTOM_INSET_PT - GESTURE_ZONE_MARGIN_PT;
+      } else {
+        const dp = await this.density();
+        const bar = await this.execute("mobile: getSystemBars").then((b) => Number(b?.navigationBar?.height), () => NaN);
+        const inset = bar > 0 ? bar : ANDROID_NAV_BAR_FALLBACK_DP * dp;
+        this.bottomLimit = Math.round(height - inset - GESTURE_ZONE_MARGIN_DP * dp);
+      }
+    }
+    return this.bottomLimit;
+  }
   async onScreen(el, full = false) {
     let r;
     try {
@@ -477,6 +508,7 @@ class Driver {
     await this.cmd("DELETE", "/actions").catch(() => null);
   }
   async drag(from, to, durationMs) {
+    to = { x: to.x, y: Math.min(to.y, await this.safeBottomY()) };
     await this.cmd("POST", "/actions", {
       actions: [
         {
@@ -641,7 +673,7 @@ var HUB = "https://hub-cloud.browserstack.com/wd/hub";
 var BS_API = "https://api-cloud.browserstack.com/app-automate";
 var basicAuth = (user, key) => `Basic ${Buffer.from(`${user}:${key}`).toString("base64")}`;
 async function resolveApp(app, customId, auth, fetchImpl, platform = IOS) {
-  if (app.startsWith("bs://"))
+  if (app.startsWith("bs://") || app.startsWith("custom_id:"))
     return app;
   const headers = { Authorization: auth };
   if (customId) {
@@ -674,7 +706,10 @@ function sessionCaps(i) {
       sessionName: i.sessionName,
       ...tunnel,
       idleTimeout: 300,
-      appiumVersion: i.appiumVersion
+      appiumVersion: i.appiumVersion,
+      video: i.capture ?? false,
+      deviceLogs: i.capture ?? false,
+      networkLogs: false
     }
   };
 }
@@ -685,6 +720,29 @@ async function sessionDetail(sessionId, auth, fetchImpl) {
   return (await res.json()).automation_session ?? {};
 }
 
+// packages/appium-driver/src/version.ts
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var DRIVER_NAME = "appium";
+function driverVersion() {
+  const built = "0.1.0-alpha.17";
+  if (built)
+    return built;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0;i < 3; i++, dir = dirname(dir)) {
+    const file = join(dir, "package.json");
+    if (!existsSync(file))
+      continue;
+    try {
+      const pkg = JSON.parse(readFileSync(file, "utf8"));
+      if (pkg.name === "@keepsnappy/appium-driver" && pkg.version)
+        return pkg.version;
+    } catch {}
+  }
+  return null;
+}
+
 // packages/appium-driver/src/session.ts
 var MARKERS_PER_REQUEST = 500;
 var MARKER_TRIES = 3;
@@ -740,6 +798,9 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
   }
   const base = api.replace(/\/+$/, "");
   const url = `${base}/v1/markers`;
+  const version = (opts.driverVersion ?? driverVersion)();
+  const reported = opts.reported ?? new Set;
+  const driverField = { driver: { name: DRIVER_NAME, ...version ? { version } : {}, ...opts.deviceUnit ? { unit: opts.deviceUnit.slice(0, 200) } : {} } };
   let sent = 0;
   for (const [token, list] of byToken) {
     const trips = [];
@@ -748,7 +809,9 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
       return carried.length ? { ...body, clock: carried } : body;
     };
     const send = async (body) => {
-      const answer = await postWithRetry(fetchImpl, url, token, withClock(body), sleep, now);
+      const answer = await postWithRetry(fetchImpl, url, token, { ...withClock(body), ...reported.has(token) ? {} : driverField }, sleep, now);
+      if (answer && answer.status < 300)
+        reported.add(token);
       if (answer?.trip)
         trips.push(answer.trip);
       return answer;
@@ -777,6 +840,14 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
     if (trips.length)
       await post(fetchImpl, `${base}/v1/clock`, token, { source: "host", samples: trips.splice(0) }, now);
   }
+  for (const token of opts.tokens ?? []) {
+    if (byToken.has(token) || reported.has(token) || !token || !api)
+      continue;
+    const answer = await postWithRetry(fetchImpl, `${base}/v1/clock`, token, { source: "host", samples: [], ...driverField }, sleep, now);
+    reported.add(token);
+    if (!answer || answer.status >= 300)
+      opts.note?.(`driver report for a run not accepted (${answer?.status ?? "no answer"}); not tried again`);
+  }
   return sent;
 }
 var SDK_FLUSH_WORST_CASE_MS = 315000;
@@ -786,6 +857,26 @@ var FLUSH_POLL_MS = 500;
 var FLUSH_RESEND_MS = 90000;
 var ACTIVATION_SETTLE_MS = 2000;
 var FLUSH_NOT_ACKNOWLEDGED = "not acknowledged (re-sent once)";
+var flushLoss = (detail) => {
+  if (!detail)
+    return "no detail";
+  const count = (re) => Number(re.exec(detail)?.[1] ?? 0);
+  const lost = [];
+  const rejected = count(/^rejected \d+: (\d+) batch/);
+  if (!detail.startsWith("batches=") && !rejected && !detail.startsWith("lines of the run dropped before sending")) {
+    lost.push(`lines not sent (${detail.replace(/ (?:dropped|artifacts)=.*$/, "")})`);
+  }
+  if (count(/ dropped=(\d+)/))
+    lost.push(`lines dropped=${count(/ dropped=(\d+)/)}`);
+  if (rejected)
+    lost.push(`line batches rejected=${rejected}`);
+  const files = /failed=(\d+) pending=(\d+) local=(\d+) rejected=(\d+)/.exec(detail);
+  if (files)
+    lost.push(`profile files not uploaded=${files.slice(1).reduce((n, x) => n + Number(x), 0)}`);
+  if (count(/ lost stream=(\d+)/))
+    lost.push(`stream segments lost=${count(/ lost stream=(\d+)/)}`);
+  return lost.length ? lost.join(", ") : detail;
+};
 var FLUSH_UNREADABLE = "not acknowledged (unreadable answer)";
 var FLUSH_STATUSES = new Set(["ok", "error", "off"]);
 var UNREADABLE_POLLS = 3;
@@ -1186,6 +1277,8 @@ class Session {
   }
   async beginRun({ token, args = "", home }) {
     this.token = token;
+    if (token)
+      this.opened.add(token);
     this.pendingReady = null;
     await this.relaunch();
     await this.waitVisible(home, 30000);
@@ -1193,12 +1286,14 @@ class Session {
     await this.driver.sleep(ACTIVATION_SETTLE_MS);
     return alert;
   }
+  opened = new Set;
+  told = new Set;
   lastFlush = null;
   flushSeq = 0;
   async endRun() {
     if (this.markers.some((m) => m.phase === "start"))
       await this.memRead(await this.gc(true));
-    await sendMarkers(this.fetch, this.api, this.markers, { sleep: (ms) => this.driver.sleep(ms), now: () => this.now() });
+    await sendMarkers(this.fetch, this.api, this.markers, { sleep: (ms) => this.driver.sleep(ms), now: () => this.now(), deviceUnit: this.driver.deviceUnit, tokens: [...this.opened], reported: this.told, note: (line) => this.driver.log.push({ ...this.driver.context, cmd: "driver-report", t: this.now(), ms: 0, status: 1, answer: line }) });
     const evidence = { linkAt: this.now(), resentAt: null, ackAt: null, gaveUpAt: null };
     this.lastFlush = evidence;
     const acks = new Set;
@@ -1315,7 +1410,8 @@ var DRIVER_OPTIONS = {
   out: { type: "string", default: "farm-run" },
   platform: { type: "string", default: "ios" },
   "action-gc": { type: "string", default: "off" },
-  "end-gc": { type: "string", default: END_GC_DEFAULT ? "on" : "off" }
+  "end-gc": { type: "string", default: END_GC_DEFAULT ? "on" : "off" },
+  capture: { type: "string", default: "off" }
 };
 function parseDriverArgs(argv, module) {
   const values = parseArgs({ args: [...argv], options: { ...module.options ?? {}, ...DRIVER_OPTIONS } }).values;
@@ -1331,8 +1427,8 @@ function writeAtomic(file, text) {
   renameSync(tmp, file);
 }
 async function captureFailure(driver, out) {
-  const source = driver.cmd("GET", "/source").then((s) => void (typeof s === "string" && writeFileSync(join(out, "failure-source.xml"), s)), () => null);
-  const screen = driver.cmd("GET", "/screenshot").then((png) => void (typeof png === "string" && writeFileSync(join(out, "failure-screen.png"), Buffer.from(png, "base64"))), () => null);
+  const source = driver.cmd("GET", "/source").then((s) => void (typeof s === "string" && writeFileSync(join2(out, "failure-source.xml"), s)), () => null);
+  const screen = driver.cmd("GET", "/screenshot").then((png) => void (typeof png === "string" && writeFileSync(join2(out, "failure-screen.png"), Buffer.from(png, "base64"))), () => null);
   await Promise.all([source, screen]);
 }
 async function runDriver(argv, module, deps = realRunDeps()) {
@@ -1355,10 +1451,13 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     throw new Error("--action-gc must be on or off");
   if (a["end-gc"] !== "on" && a["end-gc"] !== "off")
     throw new Error("--end-gc must be on or off");
+  if (a.capture !== "on" && a.capture !== "off")
+    throw new Error("--capture must be on or off");
+  const capture = a.capture === "on";
   const out = String(a.out);
   const auth = basicAuth(user, key);
   mkdirSync(out, { recursive: true });
-  const { api, tokens } = parseTokensJs(readFileSync(String(a["tokens-js"]), "utf8"));
+  const { api, tokens } = parseTokensJs(readFileSync2(String(a["tokens-js"]), "utf8"));
   const log = [];
   const driver = new Driver({ hub: HUB, log, headers: { Authorization: auth }, bundleId: module.app.bundleId, platform, fetch: deps.fetch, now: deps.now, sleep: deps.sleep });
   const t = new Session({ driver, scheme: module.app.scheme, fetch: deps.fetch, api, actionGc: a["action-gc"] === "on", endGc: a["end-gc"] === "on" });
@@ -1378,13 +1477,15 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   let flushOff = [];
   const iterations = [];
   let terminating = false;
-  const logFile = join(out, "driver-log.json");
+  const logFile = join2(out, "driver-log.json");
   const persist = () => {
     const last = t.stepLog.at(-1);
     const body = {
       driver: "appium",
       status,
       device,
+      unit: driver.deviceUnit ?? null,
+      capture,
       appUrl,
       session: driver.sessionId,
       buildId,
@@ -1419,7 +1520,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     }
   };
   let dashboard = null;
-  const writeBuild = (failure) => writeAtomic(join(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
+  const writeBuild = (failure) => writeAtomic(join2(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
     driver: "appium",
     status: failure === null ? "passed" : "failed",
     buildId,
@@ -1489,13 +1590,14 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   try {
     appUrl = await resolveApp(String(a.app), String(a["app-custom-id"] ?? ""), auth, deps.fetch, platform);
     deps.print(`app: ${appUrl}`);
-    const caps = sessionCaps({ appUrl, device, buildName: String(a["build-name"]), sessionName, appiumVersion: String(a["appium-version"]), platform, localIdentifier: a["local-identifier"] });
+    const caps = sessionCaps({ appUrl, device, buildName: String(a["build-name"]), sessionName, appiumVersion: String(a["appium-version"]), platform, localIdentifier: a["local-identifier"], capture });
     startedAt = deps.now();
     try {
       await driver.start(caps);
       deps.print(`session ${driver.sessionId}`);
       progress();
       await driver.cmd("POST", "/appium/settings", { settings: platform.settings }).catch(() => null);
+      await driver.safeBottomY().catch(() => null);
       await module.setup?.(t, ctx);
       await runIterations(t, module, ctx, iterations, progress);
     } catch (e) {
@@ -1527,8 +1629,13 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     flushOff = flushedAs(FLUSH_OFF, true);
     if (flushNotAcknowledged.length)
       deps.error(`::error::flush not acknowledged (no answer after the re-send, an unreadable answer, or a failed end-run): ${flushNotAcknowledged.join(", ")}`);
-    if (flushError.length)
-      deps.error(`::error::flush answered error (data not uploaded): ${flushError.join(", ")}`);
+    if (flushError.length) {
+      const losses = [
+        ...iterations.filter((r) => r.flushed === FLUSH_ERROR).map((r) => `${r.journey} #${r.iteration} (${flushLoss(r.flush?.detail)})`),
+        ...finalFlush?.flushed === FLUSH_ERROR ? [`final flush (${flushLoss(finalFlush.flush?.detail)})`] : []
+      ];
+      deps.error(`::error::flush answered error, data lost: ${losses.join(", ")}`);
+    }
     if (flushOff.length)
       deps.error(`::error::flush answered off in a run with a token (upload not configured, nothing uploaded): ${flushOff.join(", ")}`);
     endedAt = deps.now();
@@ -1587,7 +1694,7 @@ async function runIterations(t, module, ctx, iterations, progress) {
 
 // packages/appium-driver/src/load.ts
 async function loadJourneyModule(path, cwd = process.cwd()) {
-  const file = isAbsolute(path) ? path : resolve(cwd, path);
+  const file = isAbsolute(path) ? path : resolve2(cwd, path);
   const mod = await import(pathToFileURL(file).href);
   const m = mod.default ?? mod;
   if (!m.app?.bundleId || !m.app.scheme)