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

package/dist/appium-driver.js

@@ -5,7 +5,7 @@ import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // packages/appium-driver/src/run.ts
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 
@@ -32,8 +32,9 @@ function linkArgs(args = "") {
   return [...fields].map(([k, v]) => `${k}=${v}`).join("&");
 }
 var activationLink = (scheme, token, args = "") => `${route(scheme)}?activate=1&${linkArgs(args)}&runToken=${token}`;
-var flushLink = (scheme) => `${route(scheme)}?flush=1&activate=0`;
+var flushLink = (scheme, ack) => `${route(scheme)}?flush=1&activate=0${ack === undefined ? "" : `&ack=${ack}`}`;
 var gcLink = (scheme, n) => `${route(scheme)}?cmd=gc&n=${n}`;
+var memReadLink = (scheme, n) => `${route(scheme)}?cmd=memread&n=${n}`;
 async function acceptAlert(driver, labels, waitMs) {
   const deadline = driver.now() + waitMs;
   for (;; ) {
@@ -347,6 +348,10 @@ class Driver {
     }
     return value;
   }
+  async attribute(el, name) {
+    const value = await this.cmd("GET", `/element/${el}/attribute/${name}`);
+    return value === this.platform.absentAttributeText ? null : value;
+  }
   async start(capabilities) {
     const value = await this.cmd("POST", "/session", { capabilities: { alwaysMatch: capabilities } });
     this.sessionId = value.sessionId;
@@ -426,7 +431,7 @@ class Driver {
           break;
         let resourceId;
         try {
-          resourceId = String(await this.cmd("GET", `/element/${el}/attribute/resource-id`));
+          resourceId = String(await this.attribute(el, "resource-id") ?? "");
         } catch (e) {
           if (e instanceof WdError && e.wdError === "stale element reference")
             continue;
@@ -510,9 +515,10 @@ var FLUSH_ID = "keepsnappy.flushed";
 var ACK_ID = "keepsnappy.ack";
 var GC_ANSWER_WAIT_MS = 1e4;
 var GC_POLL_MS = 100;
-function parseBroadcastAnswer(out, n) {
+var MEMREAD_ANSWER_WAIT_MS = 3000;
+function parseBroadcastAnswer(out, n, cmd = "gc") {
   const data = /data="([^"]*)"/.exec(String(out ?? ""))?.[1];
-  return data !== undefined && data.startsWith(`gc:${n} `) ? data : null;
+  return data !== undefined && data.startsWith(`${cmd}:${n} `) ? data : null;
 }
 var NO_WAIT_MS = 0;
 var NEW_COMMAND_TIMEOUT_S = 300;
@@ -528,31 +534,34 @@ var IOS = {
     "appium:newCommandTimeout": NEW_COMMAND_TIMEOUT_S,
     "appium:waitForIdleTimeout": NO_WAIT_MS
   }),
+  absentAttributeText: null,
   settings: { animationCoolOffTimeout: NO_WAIT_MS, waitForIdleTimeout: NO_WAIT_MS, shouldUseCompactResponses: true },
   locators: (sel) => [locator(sel)],
   keyboardShown: async (driver) => Boolean(await driver.findShown(id("Return"))),
   appArg: (bundleId) => ({ bundleId }),
   openLink: (driver, url, state) => openLink(driver, url, state),
   acceptAlert: (driver, labels, waitMs) => acceptAlert(driver, labels, waitMs),
-  flush: { lookup: { using: "accessibility id", value: FLUSH_ID }, statusAttribute: "label" },
+  flush: { lookup: { using: "accessibility id", value: FLUSH_ID }, statusAttribute: "label", detailAttribute: "value" },
   uploadFields: { ios_keychain_support: "true" },
-  async gcCommand(driver, n, scheme, state) {
-    await openLink(driver, gcLink(scheme, n), state);
-    const want = `type == "XCUIElementTypeStaticText" AND name == "${ACK_ID}" AND label BEGINSWITH "gc:${n} "`;
-    const deadline = driver.now() + GC_ANSWER_WAIT_MS;
-    for (;; ) {
-      const el = await driver.find("-ios predicate string", want);
-      if (el)
-        return driver.cmd("GET", `/element/${el}/attribute/label`).then(String).catch(() => {
-          driver.log.push({ ...driver.context, cmd: "gc-ack-label", t: driver.now(), ms: 0, status: 1 });
-          return `gc:${n} ok`;
-        });
-      if (driver.now() > deadline)
-        return null;
-      await driver.sleep(GC_POLL_MS);
-    }
-  }
+  gcCommand: (driver, n, scheme, state) => iosCommand(driver, gcLink(scheme, n), "gc", n, state, GC_ANSWER_WAIT_MS),
+  memReadCommand: (driver, n, scheme, state) => iosCommand(driver, memReadLink(scheme, n), "memread", n, state, MEMREAD_ANSWER_WAIT_MS)
 };
+async function iosCommand(driver, link, cmd, n, state, waitMs) {
+  await openLink(driver, link, state);
+  const want = `type == "XCUIElementTypeStaticText" AND name == "${ACK_ID}" AND label BEGINSWITH "${cmd}:${n} "`;
+  const deadline = driver.now() + waitMs;
+  for (;; ) {
+    const el = await driver.find("-ios predicate string", want);
+    if (el)
+      return driver.attribute(el, "label").then(String).catch(() => {
+        driver.log.push({ ...driver.context, cmd: `${cmd}-ack-label`, t: driver.now(), ms: 0, status: 1 });
+        return `${cmd}:${n} ok`;
+      });
+    if (driver.now() > deadline)
+      return null;
+    await driver.sleep(GC_POLL_MS);
+  }
+}
 var ANDROID = {
   name: "android",
   defaultDevice: "Google Pixel 7-13.0",
@@ -564,6 +573,7 @@ var ANDROID = {
     "appium:autoGrantPermissions": true,
     "appium:newCommandTimeout": NEW_COMMAND_TIMEOUT_S
   }),
+  absentAttributeText: "null",
   settings: { waitForIdleTimeout: NO_WAIT_MS, actionAcknowledgmentTimeout: NO_WAIT_MS, waitForSelectorTimeout: NO_WAIT_MS, enableMultiWindows: true, ignoreUnimportantViews: true },
   locators: androidLocators,
   appArg: (appId) => ({ appId }),
@@ -590,6 +600,7 @@ var ANDROID = {
   flush: {
     lookup: { using: "-android uiautomator", value: `new UiSelector().description("${FLUSH_ID}")` },
     statusAttribute: "text",
+    detailAttribute: "hint",
     fallback: { lookup: { using: "xpath", value: `//*[@content-desc="${FLUSH_ID}"]` }, setting: "allowInvisibleElements" }
   },
   async readScreen(driver) {
@@ -606,16 +617,18 @@ var ANDROID = {
   singleFindFirst: true,
   anyOfIds: androidAnyOfIds,
   uploadFields: {},
-  async gcCommand(driver, n) {
-    const out = await driver.execute("mobile: broadcast", {
-      action: `${driver.bundleId}.keepsnappy.COMMAND`,
-      package: driver.bundleId,
-      extras: [["s", "cmd", "gc"], ["i", "n", String(n)]],
-      flags: "0x10000000"
-    });
-    return parseBroadcastAnswer(out, n);
-  }
+  gcCommand: (driver, n) => androidCommand(driver, "gc", n),
+  memReadCommand: (driver, n) => androidCommand(driver, "memread", n)
 };
+async function androidCommand(driver, cmd, n) {
+  const out = await driver.execute("mobile: broadcast", {
+    action: `${driver.bundleId}.keepsnappy.COMMAND`,
+    package: driver.bundleId,
+    extras: [["s", "cmd", cmd], ["i", "n", String(n)]],
+    flags: "0x10000000"
+  });
+  return parseBroadcastAnswer(out, n, cmd);
+}
 var PLATFORMS = { ios: IOS, android: ANDROID };
 function platformOf(name) {
   if (!Object.hasOwn(PLATFORMS, name))
@@ -770,6 +783,16 @@ var SDK_FLUSH_WORST_CASE_MS = 315000;
 var FLUSH_MARGIN_MS = 30000;
 var FLUSH_WAIT_MS = SDK_FLUSH_WORST_CASE_MS + FLUSH_MARGIN_MS;
 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 FLUSH_UNREADABLE = "not acknowledged (unreadable answer)";
+var FLUSH_STATUSES = new Set(["ok", "error", "off"]);
+var UNREADABLE_POLLS = 3;
+var FLUSH_END_RUN_FAILED = "not acknowledged (end-run failed)";
+var ACK_ECHO = / ?ack=([A-Za-z0-9_-]+)$/;
+var FLUSH_ERROR = "error";
+var FLUSH_OFF = "off";
 var FLUSH_FALLBACK_EVERY = 10;
 var RESCUE_EVERY_MS = 3000;
 var noop = async () => {
@@ -790,6 +813,8 @@ class Session {
   endGc;
   gcN = 0;
   stepDepth = 0;
+  stepLog = [];
+  onStepChange = null;
   refinds = 0;
   get staleRefinds() {
     return this.refinds;
@@ -818,6 +843,18 @@ class Session {
     this.actionGc = answer === `gc:${n} unavailable` ? "unavailable" : "unsupported";
     return null;
   }
+  memReadOff = false;
+  async memRead(n) {
+    if (n === null || this.memReadOff || this.linkState.linkMode === "safari")
+      return false;
+    const start = this.now();
+    const answer = await this.driver.platform.memReadCommand(this.driver, n, this.scheme, this.linkState).catch(() => null);
+    const ok = answer === `memread:${n} ok`;
+    this.driver.log.push({ ...this.driver.context, cmd: "memread", t: this.now(), ms: this.now() - start, status: ok ? 0 : 1, ...answer !== null ? { answer } : {} });
+    if (!ok)
+      this.memReadOff = true;
+    return ok;
+  }
   now() {
     return this.driver.now();
   }
@@ -842,19 +879,30 @@ class Session {
   async step(name, action, checks = noop, once = noop) {
     await this.ready();
     this.driver.context = { ...this.driver.context, step: name };
+    const record = { journey: this.driver.context.journey, iteration: this.driver.context.iteration, name, depth: this.stepDepth, t: this.now(), ms: null };
+    this.stepLog.push(record);
     this.stepDepth++;
     try {
+      if (record.depth === 0)
+        this.onStepChange?.();
       const gcN = this.stepDepth === 1 ? await this.gc() : null;
+      record.t = this.now();
       this.marker(name, "start", gcN);
       await action();
       await checks();
       await once();
       this.marker(name, "end");
       await checks();
+    } catch (e) {
+      record.failed = true;
+      throw e;
     } finally {
+      record.ms = this.now() - record.t;
       this.stepDepth--;
       const { step: _done, ...rest } = this.driver.context;
       this.driver.context = rest;
+      if (record.depth === 0)
+        this.onStepChange?.();
     }
   }
   isVisible(sel) {
@@ -1141,26 +1189,77 @@ class Session {
     this.pendingReady = null;
     await this.relaunch();
     await this.waitVisible(home, 30000);
-    return this.openLink(activationLink(this.scheme, token, args));
+    const alert = await this.openLink(activationLink(this.scheme, token, args));
+    await this.driver.sleep(ACTIVATION_SETTLE_MS);
+    return alert;
   }
+  lastFlush = null;
+  flushSeq = 0;
   async endRun() {
     if (this.markers.some((m) => m.phase === "start"))
-      await this.gc(true);
+      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 this.openLink(flushLink(this.scheme));
+    const evidence = { linkAt: this.now(), resentAt: null, ackAt: null, gaveUpAt: null };
+    this.lastFlush = evidence;
+    const acks = new Set;
+    const link = () => {
+      const ack = String(++this.flushSeq);
+      acks.add(ack);
+      return flushLink(this.scheme, ack);
+    };
+    await this.openLink(link());
+    let answer = await this.waitFlushed(evidence.linkAt + FLUSH_RESEND_MS, acks);
+    if (answer === null || "unreadable" in answer) {
+      evidence.resentAt = this.now();
+      if (answer !== null)
+        acks.clear();
+      await this.openLink(link());
+      answer = await this.waitFlushed(evidence.resentAt + FLUSH_WAIT_MS, acks) ?? answer;
+    }
+    if (answer === null || "unreadable" in answer) {
+      evidence.gaveUpAt = this.now();
+      if (answer === null)
+        return FLUSH_NOT_ACKNOWLEDGED;
+      evidence.raw = answer.unreadable;
+      return FLUSH_UNREADABLE;
+    }
+    evidence.ackAt = this.now();
+    return answer.status;
+  }
+  async waitFlushed(deadline, acks) {
     const flush = this.driver.platform.flush;
-    const deadline = this.now() + FLUSH_WAIT_MS;
+    let unreadable = null;
+    let unreadableRun = 0;
     for (let poll = 1;this.now() < deadline; poll++) {
       let el = await this.driver.find(flush.lookup.using, flush.lookup.value);
       if (!el && flush.fallback && poll % FLUSH_FALLBACK_EVERY === 0)
         el = await this.findFallback(flush.fallback);
       if (el) {
-        const label = await this.driver.cmd("GET", `/element/${el}/attribute/${flush.statusAttribute}`).catch(() => null);
-        return label ?? "shown";
+        const label = await this.driver.attribute(el, flush.statusAttribute).catch(() => null);
+        const raw = await this.driver.attribute(el, flush.detailAttribute).then((value) => ({ value }), () => null);
+        const detail = typeof raw?.value === "string" ? raw.value : null;
+        const echoed = detail === null ? null : ACK_ECHO.exec(detail);
+        if (raw === null) {
+          unreadable = { status: label, detail: null };
+          if (++unreadableRun >= UNREADABLE_POLLS)
+            return { unreadable };
+        } else if (!echoed || acks.has(echoed[1])) {
+          if (this.lastFlush)
+            this.lastFlush.detail = detail === null ? null : detail.replace(ACK_ECHO, "");
+          if (typeof label === "string" && FLUSH_STATUSES.has(label))
+            return { status: label };
+          unreadable = { status: label, detail };
+          if (++unreadableRun >= UNREADABLE_POLLS)
+            return { unreadable };
+        } else {
+          unreadableRun = 0;
+        }
+      } else {
+        unreadableRun = 0;
       }
       await this.driver.sleep(FLUSH_POLL_MS);
     }
-    return null;
+    return unreadable ? { unreadable } : null;
   }
   async findFallback(f) {
     await this.driver.cmd("POST", "/appium/settings", { settings: { [f.setting]: true } });
@@ -1190,13 +1289,17 @@ function plan(journeys, repeat, tokens) {
 }
 
 // packages/appium-driver/src/run.ts
+var TERMINATION_BUDGET = { captureMs: 20000, endMs: 1e4, hardMs: 45000 };
+var EXIT_CODE = { SIGTERM: 143, SIGINT: 130 };
+var realProcessHooks = { on: (s, h) => void process.on(s, h), off: (s, h) => void process.off(s, h), exit: (c) => process.exit(c) };
 var realRunDeps = () => ({
   env: process.env,
   fetch,
   now: Date.now,
   sleep: realSleep,
   print: (l) => console.log(l),
-  error: (l) => console.error(l)
+  error: (l) => console.error(l),
+  process: realProcessHooks
 });
 var DRIVER_OPTIONS = {
   "journey-module": { type: "string" },
@@ -1222,6 +1325,16 @@ function parseDriverArgs(argv, module) {
 function journeyModulePath(argv) {
   return parseArgs({ args: [...argv], options: { "journey-module": { type: "string" } }, strict: false }).values["journey-module"];
 }
+function writeAtomic(file, text) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, 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);
+  await Promise.all([source, screen]);
+}
 async function runDriver(argv, module, deps = realRunDeps()) {
   const a = parseDriverArgs(argv, module);
   const user = deps.env.BROWSERSTACK_USERNAME;
@@ -1246,66 +1359,210 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   const auth = basicAuth(user, key);
   mkdirSync(out, { recursive: true });
   const { api, tokens } = parseTokensJs(readFileSync(String(a["tokens-js"]), "utf8"));
-  const appUrl = await resolveApp(String(a.app), String(a["app-custom-id"] ?? ""), auth, deps.fetch, platform);
-  deps.print(`app: ${appUrl}`);
   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" });
   const sessionName = module.sessionName ?? "keepsnappy (appium)";
   const device = String(a.device);
   const ctx = { fetch: deps.fetch, tokens, journeys, repeat, args: a };
-  const caps = sessionCaps({ appUrl, device, buildName: String(a["build-name"]), sessionName, appiumVersion: String(a["appium-version"]), platform, localIdentifier: a["local-identifier"] });
-  const startedAt = deps.now();
+  let startedAt = deps.now();
+  let endedAt = null;
+  let appUrl = null;
+  let buildId = null;
+  let status = "running";
+  let signal = null;
   let error = null;
+  let finalFlush = null;
+  let flushNotAcknowledged = [];
+  let flushError = [];
+  let flushOff = [];
   const iterations = [];
-  try {
-    await driver.start(caps);
-    deps.print(`session ${driver.sessionId}`);
-    await driver.cmd("POST", "/appium/settings", { settings: platform.settings }).catch(() => null);
-    await module.setup?.(t, ctx);
-    await runIterations(t, module, ctx, iterations);
-  } catch (e) {
-    error = e instanceof Error ? e : new Error(String(e));
-    deps.error(`::error::${error.message}`);
-    if (driver.sessionId) {
-      const source = await driver.cmd("GET", "/source").catch(() => null);
-      if (typeof source === "string")
-        writeFileSync(join(out, "failure-source.xml"), source);
-      const png = await driver.cmd("GET", "/screenshot").catch(() => null);
-      if (typeof png === "string")
-        writeFileSync(join(out, "failure-screen.png"), Buffer.from(png, "base64"));
+  let terminating = false;
+  const logFile = join(out, "driver-log.json");
+  const persist = () => {
+    const last = t.stepLog.at(-1);
+    const body = {
+      driver: "appium",
+      status,
+      device,
+      appUrl,
+      session: driver.sessionId,
+      buildId,
+      linkMode: t.linkState.linkMode ?? null,
+      actionGc: t.actionGc,
+      endGc: t.endGc,
+      linkError: t.linkState.linkError ?? null,
+      startedAt,
+      endedAt,
+      total_ms: (endedAt ?? deps.now()) - startedAt,
+      error: error?.message ?? null,
+      signal,
+      lastStep: last ? { name: last.name, t: last.t, journey: last.journey ?? null, iteration: last.iteration ?? null } : null,
+      flushNotAcknowledged,
+      flushError,
+      flushOff,
+      finalFlush,
+      steps: t.stepLog,
+      iterations,
+      commands: log
+    };
+    writeAtomic(logFile, `${JSON.stringify(body, null, 2)}
+`);
+  };
+  const progress = () => {
+    if (terminating)
+      return;
+    try {
+      persist();
+    } catch (e) {
+      deps.error(`::warning::driver-log.json not written: ${e instanceof Error ? e.message : String(e)}`);
     }
-  }
-  if (driver.sessionId) {
-    driver.context = { phase: "final-flush" };
-    await t.endRun().catch(() => null);
-    const reason = error ? error.message.slice(0, 250) : `${sessionName} done`;
-    await driver.execute(`browserstack_executor: ${JSON.stringify({ action: "setSessionStatus", arguments: { status: error ? "failed" : "passed", reason } })}`).catch(() => null);
-  }
-  const endedAt = deps.now();
-  await driver.end();
-  const detail = driver.sessionId ? await sessionDetail(driver.sessionId, auth, deps.fetch) : {};
-  const buildId = detail.build_hashed_id ?? null;
-  writeFileSync(join(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
+  };
+  let dashboard = null;
+  const writeBuild = (failure) => writeAtomic(join(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
     driver: "appium",
-    status: error ? "failed" : "passed",
+    status: failure === null ? "passed" : "failed",
     buildId,
-    dashboard: detail.public_url ?? detail.browser_url ?? null,
-    devices: [{ device, sessions: [{ id: driver.sessionId, ...error ? { error: { message: error.message } } : {} }] }]
+    dashboard,
+    devices: [{ device, sessions: [{ id: driver.sessionId, ...failure === null ? {} : { error: { message: failure } } }] }]
   }, null, 2)}
 `);
-  writeFileSync(join(out, "driver-log.json"), `${JSON.stringify({ driver: "appium", device, appUrl, session: driver.sessionId, buildId, linkMode: t.linkState.linkMode ?? null, actionGc: t.actionGc, endGc: t.endGc, linkError: t.linkState.linkError ?? null, startedAt, endedAt, total_ms: endedAt - startedAt, error: error?.message ?? null, iterations, commands: log }, null, 2)}
-`);
-  deps.print(`driver-log.json: ${log.length} commands, ${iterations.length} iterations, ${Math.round((endedAt - startedAt) / 1000)} s`);
-  for (const r of iterations)
-    deps.print(`  ${r.journey} #${r.iteration}: ${r.total_ms ?? "?"} ms, flushed=${r.flushed}`);
-  return error ? 1 : 0;
+  const readDetail = async () => {
+    const detail = driver.sessionId ? await sessionDetail(driver.sessionId, auth, deps.fetch) : {};
+    buildId = detail.build_hashed_id ?? null;
+    dashboard = detail.public_url ?? detail.browser_url ?? null;
+  };
+  const setSessionStatus = (failed, reason) => driver.execute(`browserstack_executor: ${JSON.stringify({ action: "setSessionStatus", arguments: { status: failed ? "failed" : "passed", reason } })}`).catch(() => null);
+  const proc = deps.process;
+  const budget = { ...TERMINATION_BUDGET, ...deps.term };
+  const timers = new Set;
+  const within = async (ms, work) => {
+    let timer;
+    await Promise.race([work.catch(() => null), new Promise((resolve) => timers.add(timer = setTimeout(resolve, ms)))]);
+    clearTimeout(timer);
+  };
+  const leave = (code) => {
+    for (const timer of timers)
+      clearTimeout(timer);
+    timers.clear();
+    proc?.exit(code);
+  };
+  const onSignal = (sig) => async () => {
+    if (terminating)
+      return leave(EXIT_CODE[sig]);
+    terminating = true;
+    signal = sig;
+    status = "terminated";
+    error ??= new Error("terminated");
+    endedAt = deps.now();
+    const stopped = t.stepLog.at(-1);
+    deps.error(`::error::terminated by ${sig}${stopped ? ` in step ${stopped.name}` : ""}`);
+    try {
+      persist();
+    } catch (e) {
+      deps.error(`::warning::driver-log.json not written: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    timers.add(setTimeout(() => leave(EXIT_CODE[sig]), budget.hardMs));
+    try {
+      if (driver.sessionId) {
+        await within(budget.captureMs, captureFailure(driver, out));
+        await within(budget.endMs, (async () => {
+          await setSessionStatus(true, `terminated by ${sig}`.slice(0, 250));
+          await driver.end();
+          await readDetail();
+        })());
+        writeBuild(`terminated by ${sig}`);
+      }
+      endedAt = deps.now();
+      persist();
+    } catch (e) {
+      deps.error(`::warning::termination cleanup failed: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      leave(EXIT_CODE[sig]);
+    }
+  };
+  const handlers = ["SIGTERM", "SIGINT"].map((sig) => [sig, onSignal(sig)]);
+  for (const [sig, handler] of handlers)
+    proc?.on(sig, handler);
+  t.onStepChange = progress;
+  progress();
+  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"] });
+    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 module.setup?.(t, ctx);
+      await runIterations(t, module, ctx, iterations, progress);
+    } catch (e) {
+      error = e instanceof Error ? e : new Error(String(e));
+      deps.error(`::error::${error.message}`);
+      progress();
+      if (driver.sessionId)
+        await captureFailure(driver, out);
+    }
+    if (driver.sessionId) {
+      driver.context = { phase: "final-flush" };
+      t.lastFlush = null;
+      progress();
+      try {
+        finalFlush = { flushed: await t.endRun(), flush: t.lastFlush };
+      } catch (e) {
+        const started = t.lastFlush ?? { linkAt: null, resentAt: null, ackAt: null, gaveUpAt: null };
+        finalFlush = { flushed: FLUSH_END_RUN_FAILED, flush: { ...started, gaveUpAt: deps.now(), error: e instanceof Error ? e.message : String(e) } };
+      }
+      progress();
+      await setSessionStatus(!!error, error ? error.message.slice(0, 250) : `${sessionName} done`);
+    }
+    const flushedAs = (flushStatus, tokenOnly = false) => [
+      ...iterations.filter((r) => r.flushed === flushStatus && (!tokenOnly || r.token)).map((r) => `${r.journey} #${r.iteration}`),
+      ...finalFlush?.flushed === flushStatus && (!tokenOnly || iterations.some((r) => r.token)) ? ["final flush"] : []
+    ];
+    flushNotAcknowledged = [...flushedAs(FLUSH_NOT_ACKNOWLEDGED), ...flushedAs(FLUSH_UNREADABLE), ...flushedAs(FLUSH_END_RUN_FAILED)];
+    flushError = flushedAs(FLUSH_ERROR);
+    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 (flushOff.length)
+      deps.error(`::error::flush answered off in a run with a token (upload not configured, nothing uploaded): ${flushOff.join(", ")}`);
+    endedAt = deps.now();
+    await driver.end();
+    await readDetail();
+    const failed = !!(error || flushNotAcknowledged.length || flushError.length || flushOff.length);
+    if (terminating)
+      return EXIT_CODE[signal ?? "SIGTERM"];
+    writeBuild(error?.message ?? null);
+    status = failed ? "error" : "done";
+    persist();
+    deps.print(`driver-log.json: ${log.length} commands, ${iterations.length} iterations, ${Math.round((endedAt - startedAt) / 1000)} s`);
+    for (const r of iterations)
+      deps.print(`  ${r.journey} #${r.iteration}: ${r.total_ms ?? "?"} ms, flushed=${r.flushed}`);
+    return failed ? 1 : 0;
+  } catch (e) {
+    if (!terminating) {
+      status = "error";
+      error ??= e instanceof Error ? e : new Error(String(e));
+      endedAt = deps.now();
+      progress();
+    }
+    throw e;
+  } finally {
+    for (const [sig, handler] of handlers)
+      proc?.off(sig, handler);
+  }
 }
-async function runIterations(t, module, ctx, iterations) {
+async function runIterations(t, module, ctx, iterations, progress) {
   const { driver } = t;
   for (const it of plan(ctx.journeys, ctx.repeat, ctx.tokens)) {
     const rec = { journey: it.journey, iteration: it.iteration, token: it.token !== "" };
     iterations.push(rec);
+    progress();
     driver.context = { journey: it.journey, iteration: it.iteration, phase: "begin" };
     const t0 = t.now();
     rec.alert = await t.beginRun({ token: it.token, home: module.home, ...module.sdkArgs ? { args: module.sdkArgs } : {} });
@@ -1321,8 +1578,10 @@ async function runIterations(t, module, ctx, iterations) {
     rec.ready = { n: waits.length, ms: waits.reduce((x, y) => x + y, 0) };
     driver.context = { ...driver.context, phase: "end" };
     rec.flushed = await t.endRun();
+    rec.flush = t.lastFlush;
     const t3 = t.now();
     Object.assign(rec, { t_start: t0, begin_ms: t1 - t0, journey_ms: t2 - t1, end_ms: t3 - t2, total_ms: t3 - t0 });
+    progress();
   }
 }