@keepsnappy/agent 0.1.0-alpha.23 → 0.1.0-alpha.25

package/README.md

@@ -37,7 +37,7 @@ keepsnappy run -- maestro test --include-tags perf e2e/flows/   # wrap your own
 keepsnappy run --upload --wait                   # send the results; the server judges them and the CLI prints its verdict
 ```
 
-Flags: `--config` (default `keepsnappy.yml`), `--repeat N`, `--out DIR`, `--upload [--ingest-url URL]`, `--wait`, `--fail-on-worse`, `--commit SHA` / `--branch NAME` (default `GITHUB_SHA` / `GITHUB_HEAD_REF` on a pull request, else `GITHUB_REF_NAME`), `--base-commit SHA`, `--device-model` / `--device-os` (default: read from the booted simulator), `--scenario NAME` (flow name for a command given after `--`), `--replay <out dir>[:ARM]` (repeatable: take recorded runs instead of running anything), `--no-markers`, `--clock-offset-ms`.
+Flags: `--config` (default `keepsnappy.yml`), `--repeat N`, `--out DIR`, `--upload [--ingest-url URL]`, `--wait`, `--fail-on-worse`, `--commit SHA` / `--branch NAME` (default `GITHUB_SHA` / `GITHUB_HEAD_REF` on a pull request, else `GITHUB_REF_NAME`), `--base-commit SHA`, `--device UDID` (the simulator or iPhone to run on; default `device:` in keepsnappy.yml, else the only booted simulator; with several booted and none named the run refuses and lists them; every Maestro command gets it as `maestro --device UDID`), `--device-model` / `--device-os` (default: read from that simulator), `--scenario NAME` (flow name for a command given after `--`), `--replay <out dir>[:ARM]` (repeatable: take recorded runs instead of running anything), `--no-markers`, `--clock-offset-ms`.
 
 Commit details: when a run set opens (`keepsnappy run --upload`, `keepsnappy farm open`), the CLI reads the subject, author
 name and committer date of `--commit` and `--base-commit` with `git log` in the checkout (argv only, 5 s timeout) and
@@ -60,7 +60,7 @@ Annotated example: `examples/keepsnappy.yml`. Every setting:
 | `project.key_env` | Name of the env var with the project key (default `KEEPSNAPPY_KEY`). Only read with `--upload`. |
 | `project.ingest_url` | KeepSnappy API base URL for `--upload` (or `--ingest-url`, or env `KEEPSNAPPY_API`). Defaults to the hosted KeepSnappy API. |
 | `app.bundle_id` | Required. App whose keepsnappy log is read after each run. |
-| `platform`, `device` | `ios-sim` (default; `device` = UDID or `booted`) or `ios-device` (UDID required). One device per invocation in v1. |
+| `platform`, `device` | `ios-sim` (default; `device` = UDID, or `booted` for the only booted simulator: with several booted, name one) or `ios-device` (UDID required). One device per invocation in v1. |
 | `repetitions` | Runs of the whole flow set (default 5). |
 | `flows.runner` | `maestro` (build `maestro test ...`) or `command` (run `flows.command`). |
 | `flows.tags`, `flows.exclude_tags` | `--include-tags=` / `--exclude-tags=`. |
@@ -223,12 +223,12 @@ What it does, in order:
 1. Reads the investigation package with the same client as the MCP tool `get_investigation` (stored results only).
 2. Checks that the commit ids in the package are 7–40 lowercase hex characters (anything else is refused before git is called), then creates a separate worktree of your repo (`git worktree add --detach`, in the system temp directory) at the commit the finding was measured at: the PR's commit, or main's commit for a main finding. Every git call the CLI makes on your repo runs with `-c core.hooksPath=/dev/null`, so the repo's hooks (a `post-checkout` that installs or generates things) never run for a PR's commit. Your working copy, branch and uncommitted files are never touched. The worktree is removed at the end, also after a failure, a timeout or Ctrl-C. The commit must be in your clone (`git fetch` first when it says it is not).
 3. Computes the range itself, because the agent has no shell: `git log` and `git diff` (fixed arguments, `--no-ext-diff --no-textconv`, output capped: log 20 KB, stat 20 KB, diff 100 KB, with a note when cut) from main's commit to the measured commit, put in the prompt after the package. Without a main commit in the package, or with one your clone does not have, the prompt says so.
-3b. **Checks for a false alarm first.** The area is the files the package names for the finding (the components' files, and the files in the place ids' screen, parent and target), kept only if they are plain repo-relative paths that exist at the measured commit. The CLI computes, with fixed arguments, hooks off, literal pathspecs after `--`, from the two measured trees (`git diff <main commit> <measured commit>`, not the PR's range since the fork: main may have changed the area after it, and then the PR builds the old code): a symmetric log (`<` a commit only main has, `>` one only the PR has), the stat and a capped diff (40 KB) of those files, and says `AREA DIFF EMPTY: yes | no | unknown`. It also reads the stored facts through the client the tools use (`main_sessions`, `main_vs_previous`, `place_trend`, and the package's noisy marks, threshold, measured-differently and setup notes, at most 12 KB) and puts them in the prompt as the false-alarm facts, so claude and codex see the same ones. If the area diff is empty the first hypothesis is `kind: no-area-change` ("likely false alarm") with `checked`; the CLI leaves out a false alarm its own check does not support (the area changed, could not be checked, another range or file) with its reason, and still submits the other hypotheses; only when nothing is left does it submit nothing. The server cannot check this: a `no-area-change` from the skill path (or any key holder) is stored on the agent's word. The last line of the log is `KEEPSNAPPY-STATUS <word> [n]`, which `keepsnappy watch` reads for its second notification.
-4. Runs the agent in that worktree, read-only, with the prompt every runner shares (`packages/mcp/src/investigate-prompt.ts`, version `investigate-v4`, the same rules as the skill) and the package as the answer layout prints it. The prompt goes on stdin, so a large package does not hit the argument limit. Nothing the user or the repo configures can widen what the agent may do:
+3b. **Checks for a false alarm first.** The area is the files the package names for the finding (the components' files, and the files in the place ids' screen, parent and target), kept only if they are plain repo-relative paths that exist at the measured commit. The CLI computes, with fixed arguments, hooks off, literal pathspecs after `--`, from the two measured trees (`git diff <main commit> <measured commit>`, not the PR's range since the fork: main may have changed the area after it, and then the PR builds the old code): a symmetric log (`<` a commit only main has, `>` one only the PR has), the stat and a capped diff (40 KB) of those files, and says `AREA DIFF EMPTY: yes | no | unknown`. It also reads the stored facts through the client the tools use (`main_sessions`, `main_vs_previous`, `place_trend`, and the package's noisy marks, threshold, measured-differently and setup notes, at most 12 KB) and puts them in the prompt as the false-alarm facts, so claude and codex see the same ones. If the area diff is empty and no cause is found, the answer is one `kind: no-area-change` ("likely false alarm") hypothesis with `checked`; with a cause, the cause carries the fact as one short evidence line, and the schema refuses a cause and a `no-area-change` in one answer (the repair turn fixes it). The CLI leaves out a false alarm its own check does not support (the area changed, could not be checked, another range or file) with its reason; when nothing is left it submits nothing. Rows stored by an earlier prompt that hold both are listed by `keepsnappy hypotheses` as the cause with the false alarm folded in as one line. The server cannot check this: a `no-area-change` from the skill path (or any key holder) is stored on the agent's word. The last line of the log is `KEEPSNAPPY-STATUS <word> [n]`, which `keepsnappy watch` reads for its second notification.
+4. Runs the agent in that worktree, read-only, with the prompt every runner shares (`packages/mcp/src/investigate-prompt.ts`, version `investigate-v7`, the same rules as the skill) and the package as the answer layout prints it. The prompt goes on stdin, so a large package does not hit the argument limit. Nothing the user or the repo configures can widen what the agent may do:
    - `claude -p --output-format stream-json --verbose --max-turns N --restricted --permission-mode dontAsk --permission-prompts none --tools Read,Grep,Glob --allowedTools <Read,Grep,Glob + the KeepSnappy read tools by name> --disallowedTools Bash,PowerShell,Edit,Write,… --disable-slash-commands --mcp-config <private file> --strict-mcp-config`. Which flag closes which hole: `--restricted` ignores the user's, the project's (a PR's committed `.claude/settings.json`, with its hooks and allow rules) and the local settings files and removes Bash; `--permission-mode dontAsk` and `--permission-prompts none` deny whatever is not allowed and ask nobody; `--tools` and `--allowedTools` give it Read, Grep, Glob and the read-only KeepSnappy tools only (`get_investigation`, `get_finding`, `list_findings`, `list_problems`, `compare_runs`, `window_history`, `commits_between`, `session_places`, `place_trend`, `main_sessions`, `main_changes`, `main_vs_previous`, `pr_status`, `explain_layers`; never `submit_hypotheses`, so a dry run cannot store, and never `recompute_with_new_rules`; no wildcard); `--strict-mcp-config` keeps your other MCP servers out; `--disable-slash-commands` keeps the repo's and your skills and commands out. The KeepSnappy key is in a mode 0600 file that is deleted afterwards, not in the arguments or the agent's environment. It relies on the `result`, `is_error` and `subtype` fields of the last `result` event of the stream (the stream is read line by line; the events before it are where a run that never ends has its usage). All these flags are in `claude --help` of 2.1.308 (`--max-turns` is not listed there; the prompt's own tool-call budget does not depend on it). The repo's CLAUDE.md can still be read as text by the agent; it can run and write nothing.
    - `codex exec --json [-m <codexModel>] --ignore-user-config --ignore-rules --ephemeral -c default_permissions="ks" -c 'permissions.ks.filesystem={":minimal"="read","<worktree>"="read","/private/tmp"="none","/tmp"="none"}' -c approval_policy="never" -c project_doc_max_bytes=0 --color never -o <file> -`. **Codex's read scope is the worktree and the system minimum, with `/tmp` and `/private/tmp` denied by name (the minimum includes `/tmp`, which holds other tools' output); its shell can write nothing and reach no network, and git cannot run in it, so the prompt carries the log, stat and diff.** The permission profile replaces `--sandbox read-only`, which reads every file you can (`~/.zshenv`, `~/.ssh`): with it, a PR's text could make codex quote a secret into a hypothesis that is then stored on the server. Checked with `codex sandbox` and the same `-c` values (no model; the test `investigate.test.ts` runs it when `codex` is installed): the worktree reads (also under `/tmp`); a sibling file, `/tmp` and the home directory do not. **Not checked: that `codex exec` applies the profile the same way in a live run** (that needs a model). `project_doc_max_bytes=0` keeps the repo's `AGENTS.md` out of the prompt (checked with `codex debug prompt-input`). Whether `codex exec --ignore-user-config` still loads a repo's `.codex/config.toml` or hooks is not checked against a live run either; trust for a project lives in the user config it ignores. `--ignore-user-config` keeps your configured MCP servers and approval reviewer out.
 5. Budget: `--max-turns` (default 26: 25 tool calls and the answer) and `--max-minutes` (default 15). At the time limit the agent and every process it started are killed, and it says `no result within N min`. More than 5 MB of output stops it too.
-6. Validates the answer with the one hypothesis schema (`@keepsnappy/dashboard-contract/hypotheses`), after filling `runner: cli`, the agent (the model name claude reports, else `claude` / `codex`), `prompt_version` and the package's `package_digest`. An invalid answer is shown with the schema's paths and is not submitted. An answer of no hypothesis stores nothing.
+6. Validates the answer with the one hypothesis schema (`@keepsnappy/dashboard-contract/hypotheses`), after filling `runner: cli`, the agent (the model name claude reports, else `claude` / `codex`), `prompt_version` and the package's `package_digest`. An invalid answer is shown with the schema's paths and is not submitted; before that the agent gets **one repair turn** (a second, short run: at most 2 turns and 5 minutes, same read-only tools) in which it is sent the exact errors, the limits and its refused answer, and the corrected answer goes through the same schema. The tokens of both runs are in the usage. Still refused, not JSON, or no answer: the run ends as refused (`outcome: invalid`, `KEEPSNAPPY-STATUS schema`). The refused answers (and an answer that is no JSON) are kept as `<output.dir>/investigate/<finding-id>-<time>.json` (default `keepsnappy-out`, mode 0600, the agent's text and the errors only; never uploaded); the path is in the log and in `--json` as `rejected_answer`. An answer of no hypothesis stores nothing.
 7. Submits with the same client as the MCP tool `submit_hypotheses` and prints `N hypotheses, open`, then each one: component, files, expected change. `--json` prints one document `{ finding_id, outcome, submission, stored, usage }` (`stored` is null on a dry run). Progress and errors go to stderr.
 8. **Records what the run used**, for every end of a run that started the agent (see "What a run used" below), and ends with one line: `used 68k tokens (~$0.07, agent reported ~$0.07)`.
 
@@ -292,6 +292,8 @@ investigate:
 
 Where the agent is: `--agent claude|codex` picks it (default claude), then `--claude-path FILE` / `--codex-path FILE` (keys `investigate.claudePath` / `investigate.codexPath`) say which executable runs; without a path the name is looked up on `PATH`, as before. Order: flag, then `keepsnappy.yml` (or `--config FILE`), then your own config file, then `PATH`. `~/` is your home. Before anything starts (before the worktree, before the API is asked) the path of the agent in use must exist, be a regular file (symlinks are followed) and be executable by you; if not, the command stops with `--claude-path /x/claude: not found` (or `not a regular file`, `not executable`), or `investigate.claudePath /x/claude: not found (in <file>)` when the path came from a file, and exits 2. The path of the agent that is not in use is not looked at. The Mac app sets these from its settings.
 
+Which account the agent runs on: `--claude-config-dir DIR` / `--codex-home DIR` (keys `investigate.claudeConfigDir` / `investigate.codexHome`, same order as the path: flag, `keepsnappy.yml` or `--config`, your config file) start the agent with `CLAUDE_CONFIG_DIR` / `CODEX_HOME` set to that folder, so an investigation uses the login kept there instead of the default one. The folder must exist (`--claude-config-dir /x: not found`, or `investigate.claudeConfigDir /x: not found (in <file>)`, exit 2); `~/` is your home; only the agent in use is looked at. `--preflight` asks `--version` the same way, `keepsnappy doctor` shows the folder in its `agent` and `agent-login` steps and asks `claude auth status` / `codex login status` with it set, and `--save` keeps it. Not set: nothing is added to the agent's environment, so a wrapper script used as `claudePath` that sets `CLAUDE_CONFIG_DIR` itself keeps working. `keepsnappy watch` forwards both flags; its `--auto-on-worse` runs `keepsnappy investigate --agent claude`, which reads `claudePath` and `claudeConfigDir` from the forwarded `--config` and from your config file.
+
 Your own config file is `$XDG_CONFIG_HOME/keepsnappy/config.yml`, else `~/.config/keepsnappy/config.yml` (created on first write: directory 0700, file 0600). It has the same `investigate:` section as `keepsnappy.yml`; `keepsnappy investigate` and `keepsnappy watch` read it, a project's `keepsnappy.yml` (or `--config FILE`) wins over it key by key:
 
 ```sh
@@ -303,7 +305,7 @@ keepsnappy config list                                                # the thre
 keepsnappy config set investigate.codexPath /opt/codex/bin/codex --config ./my.yml   # --config FILE: another file instead of your own
 ```
 
-`set` and `unset` accept only `investigate.agent`, `investigate.claudePath`, `investigate.codexPath` and `investigate.repos.<app>` (the folder of an app's git repository; it must exist; anything else is refused with the list) and edit the file line by line, so comments, other keys and other sections stay as they are (a key written in quotes, `"tapin":`, is the same key as `tapin:` and keeps its quotes; a `repos` map left without an entry is removed with `unset`); a file that is not valid YAML, or whose `investigate:` is written inline (`investigate: {}`), is refused and left untouched. `keepsnappy investigate --save` does the same `set` for the agent and the path that run used (only those; the path only when one was given by a flag or a file, not when `PATH` found the agent).
+`set` and `unset` accept only `investigate.agent`, `investigate.claudePath`, `investigate.codexPath`, `investigate.claudeConfigDir`, `investigate.codexHome` (an account folder; it must exist; stored absolute, `~/` stays) and `investigate.repos.<app>` (the folder of an app's git repository; it must exist; anything else is refused with the list) and edit the file line by line, so comments, other keys and other sections stay as they are (a key written in quotes, `"tapin":`, is the same key as `tapin:` and keeps its quotes; a `repos` map left without an entry is removed with `unset`); a file that is not valid YAML, or whose `investigate:` is written inline (`investigate: {}`), is refused and left untouched. `keepsnappy investigate --save` does the same `set` for the agent and the path that run used (only those; the path only when one was given by a flag or a file, not when `PATH` found the agent).
 
 Exit codes: 0 stored (or a dry run, or no hypothesis), 1 no usable answer (timeout, agent error, invalid output), 2 wrong flags or settings, 130 Ctrl-C. Needs a key with read scope, like the MCP tools.
 

package/dist/appium-driver.js

@@ -428,8 +428,17 @@ class Driver {
       return r.x >= 0 && r.y >= 0 && r.x + r.width <= w.width && r.y + r.height <= w.height;
     return r.x < w.width && r.y < w.height && r.x + r.width > 0 && r.y + r.height > 0;
   }
-  async findShown(sel, full = false) {
-    let parent;
+  async findShown(sel, full = false, under, anyShown = false) {
+    try {
+      return await this.findShownOnce(sel, full, under, anyShown);
+    } catch (e) {
+      if (sel.childOf === undefined || !(e instanceof WdError) || e.wdError !== "stale element reference")
+        throw e;
+      return this.findShownOnce(sel, full, under, anyShown);
+    }
+  }
+  async findShownOnce(sel, full, under, anyShown) {
+    let parent = under;
     if (sel.childOf !== undefined) {
       const p = await this.findShown(id(sel.childOf));
       if (!p)
@@ -445,7 +454,7 @@ class Driver {
           return first;
       }
       const all = await this.findAll(using, value, parent);
-      const probed = all.length > PROBE_FROM ? await this.probeShown(all, full) : undefined;
+      const probed = all.length > PROBE_FROM ? await this.probeShown(all, full, anyShown) : undefined;
       if (probed)
         return probed;
       for (const el of all) {
@@ -455,7 +464,7 @@ class Driver {
     }
     return null;
   }
-  async probeShown(els, full) {
+  async probeShown(els, full, anyShown = false) {
     const w = await this.screen();
     let lo = 0;
     let hi = els.length - 1;
@@ -463,6 +472,8 @@ class Driver {
       const mid = lo + hi >> 1;
       const el = els[mid];
       if (await this.onScreen(el, full)) {
+        if (anyShown)
+          return el;
         let first = mid;
         while (first > 0 && await this.onScreen(els[first - 1], full))
           first--;
@@ -535,7 +546,6 @@ class Driver {
         }
       ]
     });
-    await this.cmd("DELETE", "/actions").catch(() => null);
   }
   async stroke(from, points, note) {
     const safe = await this.safeBottomY();
@@ -651,7 +661,7 @@ async function iosCommand(driver, link, cmd, n, state, waitMs) {
 }
 var ANDROID = {
   name: "android",
-  defaultDevice: "Google Pixel 7-13.0",
+  defaultDevice: "Google Pixel 9 Pro-15.0",
   caps: (device) => ({
     platformName: "Android",
     "appium:automationName": "UiAutomator2",
@@ -926,7 +936,7 @@ async function rowsInList(t, spec, c) {
   const android = t.driver.platform.name === "android";
   const call = spec.field === "description" ? /descriptionMatches/ : /textMatches/;
   const own = android && spec.field ? all.filter((l) => call.test(l.value)) : all;
-  const attr = sel.text !== undefined ? android ? spec.field === "description" ? "content-desc" : "text" : "label" : android ? "resource-id" : "name";
+  const attr = rowAttr(t, sel, spec.field);
   const frames = [];
   const inside = [];
   const parent = spec.scoped ?? true ? c.at.el : undefined;
@@ -952,6 +962,10 @@ async function rowsInList(t, spec, c) {
     ids.push(String(await t.driver.attribute(el, attr).catch(() => null) ?? ""));
   return { ids, frames, list };
 }
+var rowAttr = (t, sel, field) => {
+  const android = t.driver.platform.name === "android";
+  return sel.text !== undefined ? android ? field === "description" ? "content-desc" : "text" : "label" : android ? "resource-id" : "name";
+};
 function room(t, { frames, list }, toward) {
   if (frames.length === 0)
     return false;
@@ -1051,7 +1065,7 @@ async function drawnRowDrag(t, { list, row, above, missingMessage = "no drawn ro
 }
 async function firstDrawn(t, row, listEl, field, scopedOrField) {
   if (!scopedOrField) {
-    return t.driver.findShown(toSelector(row));
+    return t.driver.findShown(toSelector(row), false, undefined, true);
   }
   const { childOf: _list, ...inList } = toSelector(row);
   const all = t.driver.platform.locators(inList);
@@ -1129,7 +1143,7 @@ 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.23";
+  const built = "0.1.0-alpha.25";
   if (built)
     return built;
   let dir = dirname(fileURLToPath(import.meta.url));
@@ -1259,6 +1273,8 @@ 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 ACTIVATION_CHECK_N = 999999;
+var HOME_READY_MS = 30000;
 var FLUSH_NOT_ACKNOWLEDGED = "not acknowledged (re-sent once)";
 var flushLoss = (detail) => {
   if (!detail)
@@ -1321,6 +1337,7 @@ class Session {
   capture;
   gcN = 0;
   stepDepth = 0;
+  beforeLaunchOpen = false;
   stepLog = [];
   defects = { gestureRetry: 0, navStuck: 0, navCatchUp: 0, items: [] };
   navigating = false;
@@ -1339,6 +1356,7 @@ class Session {
     this.capture = o.capture;
   }
   async gc(atEnd = false) {
+    this.notInBeforeLaunch("GC command");
     if (this.actionGc !== "step" && !(atEnd && this.endGc && this.actionGc === "off"))
       return null;
     if (this.linkState.linkMode === "safari") {
@@ -1356,6 +1374,7 @@ class Session {
   }
   memReadOff = false;
   async memRead(n) {
+    this.notInBeforeLaunch("memory read");
     if (n === null || this.memReadOff || this.linkState.linkMode === "safari")
       return false;
     const start = this.now();
@@ -1385,6 +1404,7 @@ class Session {
     return took;
   }
   async navigation(fn) {
+    this.notInBeforeLaunch("navigation pass");
     if (this.stepDepth > 0)
       throw new Error("a navigation pass cannot run inside a measured step");
     if (this.navigating)
@@ -1406,10 +1426,16 @@ class Session {
   declaresSteps() {
     return this.markers.some((m) => m.phase === "start" && m.step !== NAV_STEP);
   }
+  notInBeforeLaunch(what) {
+    if (this.beforeLaunchOpen)
+      throw new Error(`no step or marker in beforeLaunch (${what}): it runs before the measured launch`);
+  }
   marker(step, phase, gcN = null) {
+    this.notInBeforeLaunch(`marker ${step}:${phase}`);
     this.markers.push({ token: this.token, step, phase, t_host: this.now(), ...gcN !== null ? { gc_n: gcN } : {} });
   }
   async step(name, action, checks = noop, once = noop) {
+    this.notInBeforeLaunch(`step ${name}`);
     if (this.navigating)
       throw new Error("a measured step cannot start inside a navigation pass");
     await this.ready();
@@ -1730,18 +1756,39 @@ class Session {
   activate() {
     return this.driver.activate();
   }
-  async beginRun({ token, args = "", home }) {
+  async beginRun({ token, args = "", home, beforeLaunch }) {
     this.token = token;
     if (token)
       this.opened.add(token);
     this.runFrom = { commands: this.driver.log.length, gestureRetries: this.defects.gestureRetry, navStuck: this.defects.navStuck, navCatchUp: this.defects.navCatchUp };
     this.pendingReady = null;
     await this.relaunch();
-    await this.waitVisible(home, 30000);
+    await this.waitVisible(home, HOME_READY_MS);
     const alert = await this.openLink(activationLink(this.scheme, token, args));
     await this.driver.sleep(ACTIVATION_SETTLE_MS);
+    if (beforeLaunch) {
+      this.beforeLaunchOpen = true;
+      try {
+        await beforeLaunch();
+      } finally {
+        this.beforeLaunchOpen = false;
+      }
+    }
+    await this.relaunch();
+    await this.waitVisible(home, HOME_READY_MS);
+    if (token && this.linkState.linkMode !== "safari")
+      await this.confirmActive();
     return alert;
   }
+  async confirmActive() {
+    const n = ACTIVATION_CHECK_N;
+    const start = this.now();
+    const answer = await this.driver.platform.memReadCommand(this.driver, n, this.scheme, this.linkState).catch(() => null);
+    const ok = answer?.startsWith(`memread:${n} `) ?? false;
+    this.driver.log.push({ ...this.driver.context, cmd: "activation-check", t: this.now(), ms: this.now() - start, status: ok ? 0 : 1, ...answer !== null ? { answer } : {} });
+    if (!ok)
+      throw new Error(`SDK did not activate: the launch after the activation link answered no command (memread:${n}${answer === null ? ", no answer" : `, got ${answer}`})`);
+  }
   opened = new Set;
   told = new Set;
   runFrom = null;
@@ -2134,11 +2181,22 @@ async function runIterations(t, module, ctx, iterations, progress) {
     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 } : {} });
+    const itCtx = { ...ctx, journey: it.journey, iteration: it.iteration };
+    const hook = module.beforeLaunch;
+    const beforeLaunch = hook && (async () => {
+      driver.context = { ...driver.context, phase: "before-launch" };
+      try {
+        await hook(t, itCtx);
+      } catch (e) {
+        throw new Error(`beforeLaunch failed (${it.journey} #${it.iteration}): ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+      }
+      driver.context = { ...driver.context, phase: "begin" };
+    });
+    rec.alert = await t.beginRun({ token: it.token, home: module.home, ...module.sdkArgs ? { args: module.sdkArgs } : {}, ...beforeLaunch ? { beforeLaunch } : {} });
     const t1 = t.now();
     driver.context = { ...driver.context, phase: "journey" };
     const waitsBefore = t.readyWaits.length;
-    await module.journeys[it.journey](t, { ...ctx, journey: it.journey, iteration: it.iteration });
+    await module.journeys[it.journey](t, itCtx);
     await t.ready();
     const t2 = t.now();
     t.marker("run:complete", "end");