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

package/README.md

@@ -1,38 +1,38 @@
 # @keepsnappy/agent
 
-The `keepsnappy` host CLI. It runs the customer's own test command several times, collects the perf-lab data the app wrote during each run, turns it into metrics, and asks `@keepsnappy/stats` for a verdict. v1 is local only and measure-only: no code changes in the customer app, no driver of our own (the test command is Maestro, Appium, XCUITest, anything that exits 0 on success).
+The `keepsnappy` host CLI. It runs the customer's own test command several times, collects the keepsnappy data the app wrote during each run, turns it into metrics, and asks `@keepsnappy/stats` for a verdict. v1 is local only and measure-only: no code changes in the customer app, no driver of our own (the test command is Maestro, Appium, XCUITest, anything that exits 0 on success).
 
 ## Commands
 
 ```sh
 bun install && bunx tsc --noEmit && bunx vitest run
-bun run build                      # dist/src/cli.js (bin: perflab)
+bun run build                      # dist/src/cli.js (bin: keepsnappy)
 
-perflab measure --repeat 10 \
+keepsnappy measure --repeat 10 \
   --arms A=/builds/base.app,B=/builds/candidate.app \
   --platform ios-sim [--device <udid>] [--bundle-id com.x.app] [--out runs/s1] [--timeout 600] \
   [--ri-capture observations.ndjson] [--mem-window chat.open] \
   -- maestro test flows/open-chat.yaml
-perflab verdict runs/s1 [--baseline A --candidate B]   # table + verdict.json
-perflab extract runs/s1 --ri-capture observations.ndjson   # re-derive metrics.csv (adds ri.* / mem.*)
-perflab aa runs/s1 [--reps 300 --boot 400]             # noise floor / MDE per metric
-perflab doctor                                         # xcrun, simctl, devicectl, maestro, appium, node, booted sims, devices
+keepsnappy verdict runs/s1 [--baseline A --candidate B]   # table + verdict.json
+keepsnappy extract runs/s1 --ri-capture observations.ndjson   # re-derive metrics.csv (adds ri.* / mem.*)
+keepsnappy aa runs/s1 [--reps 300 --boot 400]             # noise floor / MDE per metric
+keepsnappy doctor                                         # xcrun, simctl, devicectl, maestro, appium, node, booted sims, devices
 ```
 
 - `--arms`: `NAME=<.app/.ipa path>` (installed with `simctl install` / `devicectl device install app`, only when the arm changes) or `NAME=<bundle id>` (already installed). Without `--arms` there is one arm `A`: plain repetition, usable for `keepsnappy aa`.
-- `--arm-env 'A:KEY=VAL'` (repeatable): extra env for the test command on that arm's runs, also exported as `MAESTRO_KEY` (Maestro forwards only `MAESTRO_*` to flows). Used for same-binary arms that differ only in knobs, e.g. `--arms A=dev.perflab.reference,B=dev.perflab.reference --arm-env 'A:REF_KNOBS=…' --arm-env 'B:REF_KNOBS=…'`. The arms with their env are written to `<out>/arms.json`. Order stays ABBA.
+- `--arm-env 'A:KEY=VAL'` (repeatable): extra env for the test command on that arm's runs, also exported as `MAESTRO_KEY` (Maestro forwards only `MAESTRO_*` to flows). Used for same-binary arms that differ only in knobs, e.g. `--arms A=dev.keepsnappy.reference,B=dev.keepsnappy.reference --arm-env 'A:REF_KNOBS=…' --arm-env 'B:REF_KNOBS=…'`. The arms with their env are written to `<out>/arms.json`. Order stays ABBA.
 - `--platform ios-device` needs `--device <udid>`. The simulator default target is `booted`.
-- The test command runs as argv (no shell) with `PERFLAB_RUN_ID`, `PERFLAB_ARM`, `PERFLAB_RUN_DIR`, `PERFLAB_MARKER_URL` and `MAESTRO_PERFLAB_MARKER_URL` / `MAESTRO_PERFLAB_RUN_ID` in its environment.
-- Declared steps (Maestro): call `maestro/perflab/step.yaml` with `STEP`/`PHASE` (start|end) from your flow; `measure` adds `step:<name>.*` rows (source=declared). `--no-markers` turns the endpoint off, `--clock-offset-ms` overrides the clock estimate. See docs/research/28-step-markers-prototype.md.
+- The test command runs as argv (no shell) with `KEEPSNAPPY_RUN_ID`, `KEEPSNAPPY_ARM`, `KEEPSNAPPY_RUN_DIR`, `KEEPSNAPPY_MARKER_URL` and `MAESTRO_KEEPSNAPPY_MARKER_URL` / `MAESTRO_KEEPSNAPPY_RUN_ID` in its environment.
+- Declared steps (Maestro): call `maestro/keepsnappy/step.yaml` with `STEP`/`PHASE` (start|end) from your flow; `measure` adds `step:<name>.*` rows (source=declared). `--no-markers` turns the endpoint off, `--clock-offset-ms` overrides the clock estimate. See docs/research/28-step-markers-prototype.md.
 
 ## `keepsnappy run` and `keepsnappy.yml` (customer entry point)
 
-`keepsnappy run` is the wrapper for the e2e command you already have (mode A in docs/research/23-execution-modes-and-data-flow.md). It runs the command N times, drops runs where it failed, pulls the app's perf-lab data after each run, derives metrics and writes the out dir. With `--baseline <earlier out dir>` it also says what changed. Nothing is built or installed by it: your CI supplies the build (with `PERFLAB=1`) and the device.
+`keepsnappy run` is the wrapper for the e2e command you already have (mode A in docs/research/23-execution-modes-and-data-flow.md). It runs the command N times, drops runs where it failed, pulls the app's keepsnappy data after each run, derives metrics and writes the out dir. With `--baseline <earlier out dir>` it also says what changed. Nothing is built or installed by it: your CI supplies the build (with `KEEPSNAPPY=1`) and the device.
 
 ```sh
-perflab run                                   # command built from keepsnappy.yml
-perflab run -- maestro test --include-tags perf e2e/flows/   # wrap your own command (config still gives bundle id, device, repetitions)
-perflab run --baseline main-out --upload      # compare with the baseline run, then send results to the ingest
+keepsnappy run                                   # command built from keepsnappy.yml
+keepsnappy run -- maestro test --include-tags perf e2e/flows/   # wrap your own command (config still gives bundle id, device, repetitions)
+keepsnappy run --baseline main-out --upload      # compare with the baseline run, then send results to the ingest
 ```
 
 Flags: `--config` (default `keepsnappy.yml`), `--repeat N`, `--out DIR`, `--baseline 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`.
@@ -55,18 +55,18 @@ 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 perf-lab log is read after each run. |
+| `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. |
 | `repetitions` | Runs of the whole flow set (default 5). |
 | `baseline_branch` | Branch the baseline comes from (default `main`). Recorded for CI; the CLI compares with the directory you pass to `--baseline`. |
 | `flows.runner` | `maestro` (build `maestro test ...`) or `command` (run `flows.command`). |
 | `flows.tags`, `flows.exclude_tags` | `--include-tags=` / `--exclude-tags=`. |
-| `flows.paths` | Files, directories or globs (`*`, `?`, `**`); expanded by perflab (no shell). With only tags the path defaults to `.`. An entry can also be `{path, title, description}` (one flow file): how the dashboard names the journey. |
+| `flows.paths` | Files, directories or globs (`*`, `?`, `**`); expanded by keepsnappy (no shell). With only tags the path defaults to `.`. An entry can also be `{path, title, description}` (one flow file): how the dashboard names the journey. |
 | `flows.command` | Any command that exits 0 on success (Appium, Detox, ...); text or list, run without a shell. |
 | `flows.maestro_version` | Note only: printed at the start of the run. |
 | `steps.rename` | `old: new` names applied to metrics (`old.dur_ms` becomes `new.dur_ms`, `step:old.*` too), so history keeps stable names. |
 | `steps.pin` | Names always listed in the summary. |
-| `output.dir` | Out dir (default `keepsnappy-out`): `runs.ndjson`, `metrics.csv`, `<run>/test.log`, `<run>/perf-lab.log`, `<run>/markers.ndjson`, and with a baseline `compare/metrics.csv` + `compare/verdict.json`. |
+| `output.dir` | Out dir (default `keepsnappy-out`): `runs.ndjson`, `metrics.csv`, `<run>/test.log`, `<run>/keepsnappy.log`, `<run>/markers.ndjson`, and with a baseline `compare/metrics.csv` + `compare/verdict.json`. |
 | `timeout_seconds` | Per run of the command. |
 
 Unknown settings and wrong types are errors, all listed together.
@@ -81,12 +81,12 @@ Top changes:
 More work: 1  Less work: 0  No change: 38  Not enough data yet: 3
 ```
 
-`--upload` (off by default) needs a project key with `run` scope in the env var named by `project.key_env` (default `KEEPSNAPPY_KEY`); the API URL defaults to the hosted KeepSnappy API. With a branch it opens a run set (`POST /v1/run-sets`) before measuring, so a wrong key fails before device time is spent; then sends each valid run: `POST /v1/runs` (header `x-perflab-key`, `meta.scenario`, `meta.run_set_id`), `POST /v1/windows` with the run's own `PERF_LAB window` log lines (run token, 200 per batch, deterministic batch ids so a retry is safe), `POST /v1/markers` with its declared step markers, `POST /v1/runs/:id/finish`. A 429 is retried after `retry-after`. Then it closes the run set:
+`--upload` (off by default) needs a project key with `run` scope in the env var named by `project.key_env` (default `KEEPSNAPPY_KEY`); the API URL defaults to the hosted KeepSnappy API. With a branch it opens a run set (`POST /v1/run-sets`) before measuring, so a wrong key fails before device time is spent; then sends each valid run: `POST /v1/runs` (header `x-keepsnappy-key`, `meta.scenario`, `meta.run_set_id`), `POST /v1/windows` with the run's own `KEEPSNAPPY window` log lines (run token, 200 per batch, deterministic batch ids so a retry is safe), `POST /v1/markers` with its declared step markers, `POST /v1/runs/:id/finish`. A 429 is retried after `retry-after`. Then it closes the run set:
 
 - with `--wait`: `POST /v1/run-sets/:id/complete` computes the verdicts inline and the CLI prints them in plain words (More work / Less work / No change / Not enough data yet per journey and device, the top changed checks, "Few runs — result may be noisy" when the server flags it) plus a dashboard link that opens the comparison;
 - without `--wait`: the set is closed with `verdicts: on-read` and the CLI exits 0 at once, printing the dashboard link; the verdicts are computed when someone looks.
 
-On the baseline branch (`main` by default, set per app on the server) the runs grow each journey's history; on any other branch they are compared with it. Without a branch the runs are uploaded as before, without a run set and without a verdict. The CLI writes `<out>/perflab-result.json` (`run_set_id`, `dashboard_url`, `state`, summary) and `<out>/perflab-run.json` (device, branch), and on GitHub Actions appends the result to `$GITHUB_STEP_SUMMARY`. Ready workflow: `examples/github-actions.yml`.
+On the baseline branch (`main` by default, set per app on the server) the runs grow each journey's history; on any other branch they are compared with it. Without a branch the runs are uploaded as before, without a run set and without a verdict. The CLI writes `<out>/keepsnappy-result.json` (`run_set_id`, `dashboard_url`, `state`, summary) and `<out>/keepsnappy-run.json` (device, branch), and on GitHub Actions appends the result to `$GITHUB_STEP_SUMMARY`. Ready workflow: `examples/github-actions.yml`.
 
 `keepsnappy verdict <out> --baseline remote [--branch main] [--limit N]` compares each flow's local runs with the server baseline of the same flow and device (`GET /v1/baselines`: the history of the baseline branch, inside the same window the dashboard uses), for the metrics the server judges.
 
@@ -97,12 +97,12 @@ app (SDK activated per iteration with a run token) pushes its windows to the API
 markers there directly. Ready workflow and Maestro flows: `examples/farm/`.
 
 ```sh
-perflab farm open --api https://perflab-api-….run.app --branch main --commit "$APP_COMMIT" \
+keepsnappy farm open --api https://keepsnappy-api-….run.app --branch main --commit "$APP_COMMIT" \
   --device-model 'iPhone 15 Pro' --device-os 17 --device-provider browserstack \
   --journeys e2e-community-and-live-chat --repeat 5 \
-  --tokens-js farm-run/perflab-tokens.js --state farm-run/perflab-farm.json
-# ... the farm session runs (browserstack-run.mjs --suite-overlay "flows/perflab/tokens.js:farm-run/perflab-tokens.js")
-perflab farm close --state farm-run/perflab-farm.json --bs-build farm-run/browserstack.ios.json --settle-seconds 60 --wait
+  --tokens-js farm-run/keepsnappy-tokens.js --state farm-run/keepsnappy-farm.json
+# ... the farm session runs (browserstack-run.mjs --suite-overlay "flows/keepsnappy/tokens.js:farm-run/keepsnappy-tokens.js")
+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:`).
@@ -117,14 +117,14 @@ it, not by what the phone reports) and one run per journey per iteration, ahead
 runner. It writes:
 
 - `--tokens-js`: the only file holding run tokens. BrowserStack caps env values at 100 characters, so the tokens travel
-  inside the uploaded suite; the dispatcher overlays this file at `e2e/flows/perflab/tokens.js` for one upload. ES5,
+  inside the uploaded suite; the dispatcher overlays this file at `e2e/flows/keepsnappy/tokens.js` for one upload. ES5,
   for Maestro's `runScript`:
   ```js
-  output.perflabApi = "https://perflab-api-….run.app";
-  output.perflabRunSet = "<run set id>";
-  output.perflabTokens = {"<journey>": ["pl_rt_…", …one per iteration]};
+  output.keepsnappyApi = "https://keepsnappy-api-….run.app";
+  output.keepsnappyRunSet = "<run set id>";
+  output.keepsnappyTokens = {"<journey>": ["pl_rt_…", …one per iteration]};
   ```
-  `next-token.js` (examples) hands out `keepsnappyTokens[JOURNEY][i]` as `output.perflabToken` for iteration i.
+  `next-token.js` (examples) hands out `keepsnappyTokens[JOURNEY][i]` as `output.keepsnappyToken` for iteration i.
 - `--state`: JSON for `farm close`, no token and no key (safe to upload as an artifact): `version`, `api`, `run_set_id`,
   `dashboard_url`, `branch`, `commit`, `base_commit`, `device`, `journeys`, `repeat`, `tokens_js`, `opened_at`,
   `expires_at`, `runs[]` (`order`, `journey`, `iteration`, `run_id`, `external_id`), then `closed_at` and `result`.
@@ -138,7 +138,7 @@ runner. It writes:
    is never blamed; a Maestro failure stops the session, so later iterations have no data;
 3. finishes every run not yet finished (a run without a single batch is reported as "no data", never judged), closes the
    set (`--wait`: verdicts inline; else on read) and prints the iterations and the same plain-words verdict as
-   `keepsnappy run --upload --wait`, plus `$GITHUB_STEP_SUMMARY` and `<out>/perflab-result.json` (`--out`, default the
+   `keepsnappy run --upload --wait`, plus `$GITHUB_STEP_SUMMARY` and `<out>/keepsnappy-result.json` (`--out`, default the
    state's directory);
 4. puts the empty stub back into the tokens file, also when a step above failed. The example workflow also deletes the
    file before uploading `$OUT_DIR`.
@@ -148,23 +148,23 @@ that arrives after a run was finished is added by the server and the run re-proc
 result, `3` with `--fail-on-worse` on "More work", `2` for configuration, `1` when the API fails or nothing could be
 judged ("Blocked": no iteration sent any data).
 
-Slack: set `PERFLAB_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close --wait` posts the
+Slack: set `KEEPSNAPPY_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close --wait` posts the
 result: a pull request only when something got worse (a table of the 3 biggest changes, main vs PR), main only when
-something changed (`PERFLAB_SLACK_ALWAYS=1` also posts "no change"), and a measurement that sent no data always. The
+something changed (`KEEPSNAPPY_SLACK_ALWAYS=1` also posts "no change"), and a measurement that sent no data always. The
 commit's title and author come from `git log` in the checkout. A Slack failure is printed and never changes the exit code.
 
-Declared steps on the farm: `maestro/perflab/step.yaml` / `step.js` / `send-markers.js` (copy them into the suite).
+Declared steps on the farm: `maestro/keepsnappy/step.yaml` / `step.js` / `send-markers.js` (copy them into the suite).
 With a token set, `step.js` only records the marker; `send-markers.js`, run in `end-run.yaml` after each iteration,
-posts them to `<output.perflabApi or KEEPSNAPPY_API_URL>/v1/markers` with `Authorization: Bearer <run token>`, so the test
+posts them to `<output.keepsnappyApi or KEEPSNAPPY_API_URL>/v1/markers` with `Authorization: Bearer <run token>`, so the test
 never waits on the network between actions (and sends the host's clock round trips, plan 51 G1.4). A failed iteration
-never reaches `end-run.yaml`, so the example `run-perflab.yaml` also runs `send-markers.js` from `onFlowComplete`; such a
+never reaches `end-run.yaml`, so the example `run-keepsnappy.yaml` also runs `send-markers.js` from `onFlowComplete`; such a
 run is invalid through its missing completion marker, and its markers stay for diagnosis. The example folder
-(`examples/farm/flows/perflab/`) ships its own copy of `send-markers.js`. Without a token, `step.js` posts to the local
+(`examples/farm/flows/keepsnappy/`) ships its own copy of `send-markers.js`. Without a token, `step.js` posts to the local
 CLI endpoint at once; there a step started but never ended invalidates its run (`unclosed-steps`).
 
-Detox (Jest): `packages/detox` (`@keepsnappy/detox`) gives `step(name, fn)` / `stepStart` / `stepEnd`, posting the same markers: to the local endpoint from `PERFLAB_MARKER_URL` + `PERFLAB_RUN_ID` (set by `keepsnappy run`/`measure`), or on the farm to `KEEPSNAPPY_API_URL/v1/markers` with `PERFLAB_RUN_TOKEN` as the bearer token. Optional per-test step names via `@keepsnappy/detox/auto-steps`. See its README.
+Detox (Jest): `packages/detox` (`@keepsnappy/detox`) gives `step(name, fn)` / `stepStart` / `stepEnd`, posting the same markers: to the local endpoint from `KEEPSNAPPY_MARKER_URL` + `KEEPSNAPPY_RUN_ID` (set by `keepsnappy run`/`measure`), or on the farm to `KEEPSNAPPY_API_URL/v1/markers` with `KEEPSNAPPY_RUN_TOKEN` as the bearer token. Optional per-test step names via `@keepsnappy/detox/auto-steps`. See its README.
 
-Farm e2e against a local API: `KEEPSNAPPY_KEY=… PERFLAB_INGEST_KEY=… e2e/farm/run.sh <new out dir>` (fake session using
+Farm e2e against a local API: `KEEPSNAPPY_KEY=… KEEPSNAPPY_INGEST_KEY=… e2e/farm/run.sh <new out dir>` (fake session using
 the SDK push client, one late batch, one empty iteration).
 
 ## `keepsnappy findings` and friends (read-only questions)
@@ -177,16 +177,16 @@ 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)
-perflab findings --branch feat/perflab-integration     # what got worse or better on a PR, worst first
-perflab findings --main --journey live-ui --phone "iPhone 15"
-perflab findings --state all --json                    # also the resolved and not judged ones, as the API's JSON
-perflab findings --state all --offset 200              # the next page (at most 200 per answer)
-perflab finding f_0123456789abcdef                     # one finding with its evidence
-perflab finding f_0123456789abcdef --prompt | pbcopy   # only the hand-off for a coding agent, ending with its id and page
-perflab compare <runA> <runB>                          # two runs (ids or external ids), window by window, no statistics
-perflab history live-ui "Tap: live chat send"          # one window on main, run by run (id or name)
-perflab commits a1b2c3d c3d4e5f [--branch main]        # the measured commits between two points
-perflab layers                                         # which layer answers which question, and its certificate
+keepsnappy findings --branch feat/keepsnappy-integration     # what got worse or better on a PR, worst first
+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 commits a1b2c3d c3d4e5f [--branch main]        # the measured commits between two points
+keepsnappy layers                                         # which layer answers which question, and its certificate
 ```
 
 Flags: `--api URL` (or `KEEPSNAPPY_API`, default the hosted API), `--key-env NAME` (default `KEEPSNAPPY_KEY`), `--json`.
@@ -205,7 +205,7 @@ branch was measured differently from main.
 <out>/arms.json              arms of a `measure` (name, target, per-arm env)
 <out>/runs.ndjson            one record per run: run_id, arm, block, t0, t1, exit_code, valid, invalid_reason
 <out>/<run_id>/test.log      stdout/stderr of the test command
-<out>/<run_id>/perf-lab.log  Documents/perf-lab/log.txt pulled from the app
+<out>/<run_id>/keepsnappy.log  Documents/keepsnappy/log.txt pulled from the app
 <out>/metrics.csv            long format: run_id,arm,block,metric,value,valid,invalid_reason
 <out>/verdict.json           written by verdict / aa
 ```
@@ -226,7 +226,7 @@ Pure core (`schedule`, `window-log`, `metrics`, table formatting) plus thin adap
 
 ## How measure-only works
 
-1. The customer's build already contains the perf-lab SDK, which appends `<wall ms> PERF_LAB window {json}` lines to `Documents/perf-lab/log.txt` for every window it observes (screen opens, interactions).
+1. The customer's build already contains the keepsnappy SDK, which appends `<wall ms> KEEPSNAPPY window {json}` lines to `Documents/keepsnappy/log.txt` for every window it observes (screen opens, interactions).
 2. After each run the log is pulled and the windows whose start (`wall - durMs`) lies in `[t0, t1]` of that run are kept. Anything older is leftover from earlier runs.
 3. Per window name, the run's value is the median over its cycles of: `dur_ms`, `commits`, `renders`, `mounts`, `longtask_ms`, `gc_count`, `gc_ms`, `alloc_mb`, `touch_max_ms`; plus `n`, `timeouts` (windows ending in `timeout` are excluded from medians) and `retained_mb_per_cycle` (Theil-Sen slope of heap after GC across cycles, needs 3+ cycles). Metric names are `<window>.<field>`, kept as-is (e.g. `screen:(app)/community/[handle]/(tabs).dur_ms`) and quoted in the CSV when needed.
 4. A failed test, an install or log-pull failure, or a run with no windows is written as invalid with a reason. Invalid runs stay in `metrics.csv` (a `run.status` row when they have no metrics) and the stats engine drops them whole.
@@ -258,4 +258,4 @@ Memory slopes (Theil-Sen over the cycle index, 3+ cycles of `--mem-window`, defa
 `bun run typecheck` and `bun run test` first build the workspace packages the CLI imports (`bun run deps`: stats, derive,
 verdicts, profile-analysis, mcp), so both work from a clean checkout.
 
-The `perflab` command and `perflab.yml` / `perflab.yaml` remain supported. Without `--config`, configuration is read in this order: `keepsnappy.yml`, `keepsnappy.yaml`, `perflab.yml`, `perflab.yaml`. `KEEPSNAPPY_*` variables take precedence over matching `PERFLAB_*` variables, including explicit empty values. Explicit `--key-env` or `project.key_env` names are read exactly.
+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.

package/dist/appium-driver.js

@@ -17,7 +17,7 @@ import { basename } from "node:path";
 var ALERT_POLL_MS = 250;
 var RUN_DEFAULTS = { ttl: 3600, profile: 1, diag: 1 };
 var END_GC_DEFAULT = true;
-var route = (scheme) => `${scheme}devtools/perf-lab`;
+var route = (scheme) => `${scheme}devtools/keepsnappy`;
 function parseSdkArgs(args) {
   return args.split("&").filter(Boolean).map((kv) => {
     const i = kv.indexOf("=");
@@ -448,9 +448,12 @@ class Driver {
   }
   async tapElement(el) {
     const r = this.rects.get(el) ?? await this.cmd("GET", `/element/${el}/rect`);
+    await this.tapPoint({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+  }
+  async tapPoint(p) {
     const w = await this.screen();
-    const x = Math.round(Math.min(Math.max(r.x + r.width / 2, 1), w.width - 1));
-    const y = Math.round(Math.min(Math.max(r.y + r.height / 2, 1), w.height - 1));
+    const x = Math.round(Math.min(Math.max(p.x, 1), w.width - 1));
+    const y = Math.round(Math.min(Math.max(p.y, 1), w.height - 1));
     await this.cmd("POST", "/actions", {
       actions: [
         {
@@ -503,8 +506,8 @@ class Driver {
 // packages/appium-driver/src/platform.ts
 var modelOf = (device) => device.replace(/-[^-]*$/, "");
 var versionOf = (device) => device.replace(/^.*-/, "");
-var FLUSH_ID = "perflab.flushed";
-var ACK_ID = "perflab.ack";
+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) {
@@ -605,7 +608,7 @@ var ANDROID = {
   uploadFields: {},
   async gcCommand(driver, n) {
     const out = await driver.execute("mobile: broadcast", {
-      action: `${driver.bundleId}.perflab.COMMAND`,
+      action: `${driver.bundleId}.keepsnappy.COMMAND`,
       package: driver.bundleId,
       extras: [["s", "cmd", "gc"], ["i", "n", String(n)]],
       flags: "0x10000000"
@@ -653,7 +656,7 @@ function sessionCaps(i) {
     ...(i.platform ?? IOS).caps(i.device),
     "appium:app": i.appUrl,
     "bstack:options": {
-      projectName: "perflab",
+      projectName: "keepsnappy",
       buildName: i.buildName,
       sessionName: i.sessionName,
       ...tunnel,
@@ -674,6 +677,13 @@ var MARKERS_PER_REQUEST = 500;
 var MARKER_TRIES = 3;
 var HOST_CLOCK_TRIPS = 6;
 var RETRY_BASE_MS = 1000;
+var FLING_MS = 80;
+var FLING_FROM = 0.8;
+var FLING_TO = 0.3;
+var FLING_TIMEOUT_MS = 30000;
+var STALE_REFINDS = 3;
+var FRAME_POLL_MS = 50;
+var sameRect = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
 var RETRY_AFTER_CAP_MS = 30000;
 async function post(fetchImpl, url, token, body, now) {
   const t0 = now();
@@ -780,6 +790,10 @@ class Session {
   endGc;
   gcN = 0;
   stepDepth = 0;
+  refinds = 0;
+  get staleRefinds() {
+    return this.refinds;
+  }
   constructor(o) {
     this.driver = o.driver;
     this.scheme = o.scheme;
@@ -992,6 +1006,118 @@ class Session {
       await this.swipe([50, 50], direction === "down" ? [50, 10] : [50, 90], durationMs);
     }
   }
+  async frameOf(sel, el) {
+    for (let refinds = 0;; refinds++) {
+      try {
+        return { el, rect: await this.driver.cmd("GET", `/element/${el}/rect`) };
+      } catch (e) {
+        if (!(e instanceof WdError && e.wdError === "stale element reference"))
+          throw e;
+        const what = describeSelector(toSelector(sel));
+        if (refinds >= STALE_REFINDS)
+          throw new Error(`${what} went stale ${refinds + 1} times in a row (${refinds} re-finds): ${e.message}`);
+        this.refinds++;
+        try {
+          el = await this.waitVisible(sel);
+        } catch (lost) {
+          throw new Error(`${what} went stale and was not found again: ${lost instanceof Error ? lost.message : String(lost)}`);
+        }
+      }
+    }
+  }
+  async settledFrame(sel, timeoutMs) {
+    const start = this.now();
+    let at = await this.frameOf(sel, await this.waitVisible(sel));
+    for (;; ) {
+      await this.driver.sleep(FRAME_POLL_MS);
+      const now = await this.frameOf(sel, at.el);
+      if (sameRect(at.rect, now.rect))
+        return now;
+      if (this.now() - start > timeoutMs)
+        throw new Error(`${describeSelector(toSelector(sel))} did not stop moving within ${timeoutMs} ms`);
+      at = now;
+    }
+  }
+  async flingIn(r, toward, durationMs) {
+    const [from, to] = toward === "end" ? [FLING_FROM, FLING_TO] : [FLING_TO, FLING_FROM];
+    const x = Math.round(r.x + r.width / 2);
+    await this.driver.drag({ x, y: Math.round(r.y + r.height * from) }, { x, y: Math.round(r.y + r.height * to) }, durationMs);
+  }
+  async flingTimes(list, times, toward, { durationMs = FLING_MS, timeoutMs = FLING_TIMEOUT_MS } = {}) {
+    if (!Number.isInteger(times) || times < 1)
+      throw new Error(`flingTimes needs a whole number of flings >= 1, got ${times}`);
+    await this.ready();
+    const start = this.now();
+    const refindsBefore = this.refinds;
+    let flings = 0;
+    let status = 1;
+    try {
+      const { rect } = await this.settledFrame(list, timeoutMs);
+      for (;flings < times; flings++)
+        await this.flingIn(rect, toward, durationMs);
+      status = 0;
+    } finally {
+      this.driver.log.push({ ...this.driver.context, cmd: `fling-${toward}-times`, t: this.now(), ms: this.now() - start, status, flings, refinds: this.refinds - refindsBefore });
+    }
+  }
+  async flingUntil(list, target, toward, { blind = 0, durationMs = FLING_MS, timeoutMs = FLING_TIMEOUT_MS } = {}) {
+    await this.ready();
+    const start = this.now();
+    const refindsBefore = this.refinds;
+    let flings = 0;
+    let checks = 0;
+    let status = 1;
+    try {
+      let at = await this.settledFrame(list, timeoutMs);
+      const fling = async () => {
+        if (flings > 0)
+          at = await this.frameOf(list, at.el);
+        await this.flingIn(at.rect, toward, durationMs);
+        flings++;
+      };
+      while (flings < blind)
+        await fling();
+      const sel = toSelector(target);
+      while (checks++, !await this.driver.findShown(sel, true)) {
+        if (this.now() - start > timeoutMs)
+          throw new Error(`the ${toward} of the list did not show within ${timeoutMs} ms (${flings} flings)`);
+        await fling();
+      }
+      status = 0;
+      return flings;
+    } finally {
+      this.driver.log.push({ ...this.driver.context, cmd: `fling-to-${toward}`, t: this.now(), ms: this.now() - start, status, flings, checks, blind, refinds: this.refinds - refindsBefore });
+    }
+  }
+  async stableCentres(sels, timeoutMs = FLING_TIMEOUT_MS) {
+    await this.ready();
+    const start = this.now();
+    const els = [];
+    for (const sel of sels)
+      els.push(await this.waitVisible(sel));
+    const frames = async () => {
+      const out = [];
+      for (let i = 0;i < sels.length; i++) {
+        const f = await this.frameOf(sels[i], els[i]);
+        els[i] = f.el;
+        out.push(f.rect);
+      }
+      return out;
+    };
+    for (let before = await frames();; ) {
+      await this.driver.sleep(FRAME_POLL_MS);
+      const now = await frames();
+      if (now.every((r, i) => sameRect(r, before[i])))
+        return now.map((r) => ({ x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }));
+      if (this.now() - start > timeoutMs)
+        throw new Error(`the elements did not stop moving within ${timeoutMs} ms`);
+      before = now;
+    }
+  }
+  async tapAt(point) {
+    await this.ready();
+    await this.driver.tapPoint(point);
+  }
   async type(sel, value) {
     await this.ready();
     const el = await this.waitVisible(sel);
@@ -1052,7 +1178,7 @@ function parseTokensJs(text) {
     const m = text.match(new RegExp(`output\\.${name}\\s*=\\s*(.+);\\s*$`, "m"));
     return m ? JSON.parse(m[1]) : undefined;
   };
-  return { api: pick("perflabApi") ?? "", tokens: pick("perflabTokens") ?? {} };
+  return { api: pick("keepsnappyApi") ?? "", tokens: pick("keepsnappyTokens") ?? {} };
 }
 function plan(journeys, repeat, tokens) {
   const out = [];
@@ -1081,7 +1207,7 @@ var DRIVER_OPTIONS = {
   repeat: { type: "string", default: "1" },
   device: { type: "string" },
   "local-identifier": { type: "string" },
-  "build-name": { type: "string", default: "perflab-appium" },
+  "build-name": { type: "string", default: "keepsnappy-appium" },
   "appium-version": { type: "string", default: "2.19.0" },
   out: { type: "string", default: "farm-run" },
   platform: { type: "string", default: "ios" },
@@ -1125,7 +1251,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   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 ?? "perflab (appium)";
+  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"] });