correctness fixes from the first real folio dispatch, and spec authoring skills (#82)

* docs: add the apache 2.0 license text

package.json has declared Apache-2.0 since the first release and .goreleaser.yaml
globs LICENSE* into the archives, so that glob has been matching nothing. npm
only picks up a license from the package directory, hence the copy under
pkg/spec.

* fix(sidecar): close the soft keyboard after typing on android

* test(sidecar): pin the guarded ime dismissal

* fix(sidecar): treat a failed ime probe as no keyboard open

* ci(folio): let the ios leg clear state for itself

* ci(folio): drop the stale frontboard note from the ios job

* docs(ci): record what the ios calibration assumes and where it was measured

* fix(ios): replace the session when a launch blows its bound

a launch the simulator refuses is never reported: xctest records it as a test
failure the runner cannot see, then holds the session's main thread for about
four minutes on a diagnostic chain. so the only signal is the expired bound,
and every later call queues behind the same wedge. restart the session once and
launch again, bounded so the launch path stays inside testrun's backstop.

* test(ios): cover the session replacement a wedged launch needs

* fix(ios): share one deadline across the restart and the second launch

the recovery a blown bound triggers now costs at most launchRecoveryTimeout
whatever it spends it on, so the launch path tops out at 150s and testrun's
three minute backstop stays a backstop.

* test(ios): the restart a blown launch triggers has to be bounded

* docs(ci): the ios leg does not convict on the runner, and a seed cannot fix it

seed 28 reproduced its walk on macos-15 and reached the bug at the step it
convicts at locally. it still could not be judged: the run did not return
home between step 19 and step 136, so the counting invariant saw a rise of
15 against a window of 37 submits.

* docs(sidecar): record why the stale ime flag stays out of reach

* test(folio): add commonTest source sets to core and shared

* fix(folio): reject amounts parseCents cannot represent

* fix(folio): cap a transaction at one million dollars

* test(spec): give the fake dom a real tree and a walking querySelectorAll

* style(sidecar): make ktlint clean, formatting only

ktlint -F over every kotlin file except DriverBackend.kt, then hand
fixes where the reflow read worse and for the long lines ktlint cannot
break. No behaviour changes.

DriverBackend.kt is left untouched to avoid a conflict with concurrent
work; its three over-long lines still fail fmt-kotlin.

* fix(spec): deepQueryAll returns matches in document order

* ci(folio): say what the android gate found, not why

The gate proves only that AddTransactionScreen is absent from the trace.
Claiming the run never got past login was an inference it cannot make: the
run that produced it had logged in and was stuck on the new account screen.
Name the routes the trace does record instead.

* test(runner): a relaunch must not convict the submit counting property

* test(browser): compare ax.find across both hosts on one page

* test(spec): name the shadow match in the grammar both hosts parse

* ci: move every action off the node20 runtime

checkout v4->v7, setup-go v5->v7, setup-node v4->v7, setup-java v4->v5,
upload-artifact v4->v7, cache v4->v6, upload-pages-artifact v3->v5,
deploy-pages v4->v5, setup-chrome v1->v2, setup-android v3->v4,
goreleaser-action v6->v7. setup-bun and android-emulator-runner are
already node24; buf-setup-action stays on its deliberate SHA pin.

setup-chrome v2 resolves stable from Chrome for Testing rather than the
official installer, so the ci.yml comment about the action's default no
longer held.

* feat(verifier): report a relaunch on state.lastAction

* test(verifier): pin the relaunch field on both hosts

* fix(runner): keep the action the app was relaunched after

* test: pin that a nested undefined does not survive the wire

* fix(folio): uninstall before installing in just ios

folio's signed-in session lives in the data container, which an install
over the top keeps, so a local run started right after just ios opened on
the previous run's Home screen and diverged at step 1. On CI's fresh
simulator the uninstall is a no-op, so the ios leg is unchanged.

* style(sidecar): bring the last three lines under the line limit

* fix(ios): the runner must not answer ok for a launch that failed

XCTest records a refused launch as a test issue that never throws, so the
companion returned ok for an app that never started. Check the state the
app actually reached and report the refusal instead.

* test(ios): a refusal the runner names costs no session restart

The session restart is for a launch that never answers. A launch that
reports the app's state has already said what a fresh session would.

* fix(folio): attribute a created account by its whole key, not a suffix

createdAccountHasNonZeroBalance matched the created card with endsWith, so
an older account whose name ends with the typed one ("Emergency Fund" for a
typed "Fund") was judged instead whenever the new card was clipped out of
the reading. Build both keys the card can carry, the plain name and web's
initials + name, and compare them whole.

* fix(hierarchy): object selectors resolve by the same rule as string ones

* test(verifier): both ax.find selector forms resolve the same element

* test(browser): the cross-host fixture uses the object selector form

* fix(replay-ui): wrap the tab strip so its last tabs stay clickable

* test(replay-ui): drive the fuzzer onto a violating step with a panel

* feat(folio): judge a submit against the account's own balance

The counting invariant can only close its window on Home, and the iOS run
in #78 went 117 steps between two Home readings: 37 submits against a rise
of 15 transactions is no evidence about the double tap sitting inside it.
The ledger and the add-transaction screen both show the account's own
balance, and an accepted submit pops back to the ledger, so a window
bounded by those readings holds one action.

The bound is an upper one: a balance that has not moved is a commit still
in flight, a rejected submit or a tap that never landed, and none of those
is a violation. Moving by more than the one submit in the window typed is.

* test(runner): an overlay dismissal must not convict the counting property

* docs(runner): point the guard comment at the renamed test

* docs(replay-ui): name the viewport the tab overflow was measured at

* feat(folio): close the submit window on the account's own screens

submitCommitsOneTransactionPerAction now states its rule over two windows:
the Home counts it already compared, and the account balance the ledger and
the add-transaction screen redraw on nearly every frame of the transaction
flow. Same rule, and the second window is usually one action wide.

* fix(sidecar): reach the adb server the environment names

buildDadb hardcoded localhost:5037, so a serial-addressed device always
resolved through this machine's adb server and ADB_SERVER_SOCKET was
ignored. Read the endpoint the way the adb CLI does instead.

Fixes #79

* test(sidecar): pin the adb server endpoint parsing

* fix(sidecar): close a keyboard standing in the snapshot

A tap on a text field raises the keyboard and nothing closed it, so the
tree the picker chooses from was missing every app node underneath it,
the submit control included. Close it before the read rather than after
the tap: the picker only ever sees snapshots, and the keyboard is still
on its way up when the tap returns.

Fixes #78

* test(sidecar): pin the tree-guarded keyboard dismissal

* chore(make): a target that runs folio's unit tests

* chore(folio): a just recipe for the unit tests

* ci: run folio's unit tests on every pr

* ci: switch to jdk 21 only for the folio step

* docs(sidecar): put the measured read cost in the dismissal bound

* fix(folio): decline the two demanding properties across a relaunch

The runner now keeps lastAction and marks it relaunched: true where it used
to report nothing at all, so the two properties that demand an effect judge
a step whose process may have died before the write landed.
submitChangesBalanceByTypedAmount and createdAccountHasNonZeroBalance both
decline there. The counting bound does not: a relaunch cannot manufacture a
transaction, and the submit is counted, so declining would throw away the
detection the runner fix restored.

* docs(folio): say why the merged card key cannot be made injective

Folio rejects a duplicate account name, so the twin the drop rule guards
against is two names the web key cannot tell apart, not two accounts
sharing a name. State what closing the rest would cost and what the tree
would have to carry to close it properly.

* test(folio): pin that two accounts can render the same card text

The proof behind the comment: "Travel1" holding 25 transactions and
"Travel12" holding 5 merge to the same string, so no identity key read off
a web card can tell them apart.

* fix(sidecar): bound the diagnostic adb reads

adbOutput and readLogcat read to EOF and then waited with no timeout, so
a wedged adb held the step for as long as it liked; one stall over a
remote adb server measured ~100s. The bound has to sit on the read, not
on waitFor: a wedged adb never reaches EOF, so a bounded waitFor after
the read is a line that never runs.

* test(sidecar): pin the bound on a wedged adb read

* fix(sidecar): an unreadable animation count is not idle

Defaulting the count to zero made a dumpsys that said nothing mean
nothing is animating, so a degraded link broke out of the settle early
and handed the runner a frame caught mid-animation. Unknown now waits,
inside the deadline waitForIdle already holds.

* test(sidecar): unknown animation state must not read as idle

* fix(folio): stop spending the submit budget on taps the app refused

The window is an upper bound on the transactions an interval could hold, and
a bound inflated by taps that commit nothing is a bound the app can never
exceed: #78 read a rise of 15 transactions against 37 submits. TxnSubmit is
clickable(enabled = amount.isNotBlank()) and parseCents refuses anything its
regex misses, so a tap whose landing frame shows a refused amount cannot have
committed. Over four recorded android runs that is 19, 11, 25 and 25 of 35,
26, 42 and 42 submit taps.

A relaunch is excepted: a fresh process draws an empty field whatever was
submitted.

* feat(folio): read the amount field into every submit window

Each of the three windows asks whether the tap could have committed, off the
field as the landing frame shows it.

* fix(sidecar): a foreground read that fails degrades the typing guard

An unreadable dumpsys passed a null owner to typeChunks, which switches
the mid-type focus guard off outright and lets the rest of the string
spray into whatever holds the foreground. Fall back to the launched
bundle instead: the guard stays armed, typing still happens, and the
degradation is said out loud rather than assumed away.

* test(sidecar): pin the degraded typing guard both ways

* test(runner): answer Snapshot and Hierarchy off one tree in the fakes

* feat(runner): skip a step whose tree changed between two reads

* test(runner): cover the reread's cost to the existing snapshot rules

* fix(ios): clear app state before the automation session attaches

New performs the clear-state reset, so the uninstall and reinstall no
longer land underneath a live XCTest session that is already bound to
the app. Launch refuses a clear-state request the driver was not built
for rather than reinstalling under its own session.

* fix(ios): the device path clears before its runner session too

* fix(testrun): thread clear-data into the ios drivers

* test(runner): a skipped step must not swallow the action before it

* fix(runner): hold the action back on a step nothing verified

* refactor(runner): drop the empty branch from the hold path

* docs(runner): describe both modes of the composing test driver

* fix(sidecar): erase a field by selecting it, not one delete per character

maestro's eraseText sends one delete per character through its
instrumentation, measured 29.6 ms/char on the API 34 emulator. The
4096-character string the corpus types cost ~121s to clear, a fifth of a
20 minute run spent on one step, and it recurred every time that field
was typed into again.

Select the content and delete the selection instead: two key events at
any length, measured 0.15s to 1.16s for 4096 characters across API 34,
35 and 36. The result is read back off the tree, and a field that is not
empty, or that the tree cannot report on, is finished off per character
in batches rather than assumed clear.

Fixes #80

* test(sidecar): pin the constant-cost erase and its residue check

* fix(sidecar): find the erased field by class, past the keyboard's own focus

The check that decides whether the select-all worked looked for an
"editable" attribute maestro's tree does not carry, so it answered
"cannot tell" every time and every erase paid the per-character
fallback. Worse, an open keyboard puts a second focused node in the
tree, one of the IME's own keys, carrying no text: taking the first
focused node would read a field still holding 4096 characters as empty,
which is the one answer that stops the erase early.

Match the text field by class instead. Measured against the real
backend, 4096 characters now clear in 385ms on API 34, 409ms on API 35
and 870ms on API 36, verified empty, where the fallback took ~4s.

* test(sidecar): use the tree the device really returns

* docs(ci): the android step number describes a local emulator, not ci

the leg disables animations and the number was measured with them on. the
first real dispatch carries 4 transitional steps over 200, so the cross-fade
wait does still fire in ci, just far less often.

* fix(android): say what the sdk lookup checked, not just to set ANDROID_HOME

* fix(doctor): resolve adb and emulator the way a run does

* docs(cli): the android doctor checks are not path-only

* fix(testrun): preflight resolves adb through the sdk, not just PATH

* docs(skills): add a spec review skill and the skills index

* fix(testrun): report a sidecar that dies at startup as the exit it was

* test(testrun): cover the sidecar shutdown path after an early exit

* docs(skills): add a property patterns catalogue skill

* fix(folio): bound the total-balance move instead of demanding it exactly

The write finishes before AddTransactionViewModel navigates, but nothing
establishes that Home's total has re-rendered before the frame is read, and
an equality convicts a healthy app for a total one frame behind. A delta of
zero is exactly the shape nine of the eleven measured android false
convictions had. 2x still exceeds x, so all four recorded convictions
survive, checked against the traces.

The trade is real: a balance that moves by LESS than the amount typed is no
longer judged anywhere in this spec.

* docs(folio): say what property 2 demands now that it is a bound

* docs(skills): add a spec authoring skill

covers hooks, extractors, selectors, properties, actions and the order to write them in, with a complete sample spec that typechecks against the real export surface.

* docs(skills): ground the property patterns catalogue in the merged specs

* docs(skills): name the selector keys that still substring match

* docs(skills): add a setup skill for adopting sanderling

* docs(skills): add a run triage skill

* docs(skills): point the setup skill at its siblings

* docs(manual): correct the flags the cli reference gets wrong

--launcher-activity does not exist in cmd/sanderling/main.go. --device,
--android-app-path and --arm do and were undocumented. runs.md still listed
--max-steps and --exit-on-violation as unshipped, and described --clear-data
as opt-in when the default is already true, contradicting itself ten lines on.

* test(folio): pin that a commit stays in the window until Home reads it

The interaction that keeps a stale Home card list from ever banking counts
the budget has already forgotten: a submit lands on the ledger, so the
reading that resets the window is a whole action later and the submit is
still in it. Characterization, not a regression: no code changed and it
cannot go red first.

* docs(folio): record why a banked card reading can be trusted as current

The freshness rule rests on the app popping one entry back to the ledger,
not on anything the frame carries, so the assumption and the measurements
behind it belong next to it.

* refactor(folio): name the balance property for the bound it asserts

it stopped being an equality and became |delta| <= typed, so the old name
demanded more than the property does. renamed with the ci gate's
GATED_PROPERTIES in the same commit so the gate never sees a name it does
not know.

* fix(android): a refused uninstall must not pass for clear-state

adb uninstall answers Failure [DELETE_FAILED_INTERNAL_ERROR] both when the package was never installed and when it refuses to remove one, so the failure text cannot say which happened and the old code installed over the top either way, keeping the data clear-state was asked to drop. Ask pm path instead, and fall back to pm clear when the app is still there.

* fix(ios): a failed simctl uninstall must fail the reinstall

simctl install over an installed app carries its data container across, so discarding the uninstall error reported a clear-state that never happened. Uninstalling an app that is not installed exits 0 on a booted simulator, so every failure here is a real one.

* fix(ios): a failed devicectl uninstall must fail the reinstall

same hole as the simulator path: devicectl install over an app keeps its data, and the discarded uninstall error hid it. Uninstalling a bundle id that is not installed exits 0 with 'App uninstalled.' on a paired iPhone, so a failure here is always real.

* docs(android): say why the uninstall text cannot be read

* test(android): name the uninstall failure for what it says, not why

* docs(ci): the ios leg convicts on the runner now, and why it did not before

* docs(ci): the cross-fade wait does not fire on ci, say so

* fix(runner): a bounded hold puts the swallow back one step later

the hold carries one action; letting the runner act again while the verifier
is still skipped overwrites it, so the carried action reaches no spec. hold
for as long as the verifier is skipped, and settle on a held step so the
reread pair is not tighter than the window the detector was measured over.

* test(runner): pin what the two reads are compared on

structuralShape excluding text and bounds is the decision separating this
feature from a run that verifies nothing, and only prose held it. adding
either field back now turns a case red.

* fix(ci): close shell injection into the npm publish job

A refname is attacker-controlled and git permits backtick, $, (, ; and |
in it. Three sites substituted it into a run: block, and NODE_AUTH_TOKEN
sat at job level, so a pushed tag ran arbitrary commands with the publish
credential in reach.

The tag now goes through env:, is validated against an anchored version
pattern before anything consumes it, and reaches the other jobs as a job
output. The token is scoped to the publish step. release-npm declares
contents: read instead of inheriting the repo default.

* fix(ios): recognise every shape a blown launch bound arrives in

The runner transport reports a blown budget two ways, its own comment says
so: the context's error once cancellation has landed, and the connection's
i/o timeout when the deadline armed from that context fires first. The
legacy transport reports it as a gRPC status. errors.Is against
context.DeadlineExceeded only matches the first, so the session restart
never fired for the other two and a wedged session stayed wedged.

* test(ios): drive the launch recovery with what the transports return

The wedged-session fake answered with ctx.Err() raw, which is the one
shape the guard already matched. The recovery now runs against the error
each transport really produces for the same expiry, taken from a runner
and a legacy companion that never answer.

* test(runner): pin both guard writes to what the spec reads

deleting lastAction.Relaunched or lastAction.Applied left the whole suite
green, so the only producer of the two fields every spec-side guard reads
had nothing holding it. both now assert the value out of the trace.

* fix(testrun): a run that judged nothing is not a green run

every step skipped means no property ever evaluated, so no violations is the
absence of a verdict rather than a clean one. the hold makes that reachable
now, so the run says it instead of exiting 0.

* fix(ios): stop the app before clearing its state

Launch terminated and then cleared; the clear moved to construction and
left nothing stopping the app first. The container wipe deletes files a
live app still holds open, and the CI ios leg passes no app path so the
wipe is the path it takes. simctl stops it, since the clear now runs
before any automation session exists. On a device the uninstall that is
its only clear takes the running app with it.

* test(ios): pin the stop that has to precede a clear

The ordering probe now records the stop, and a scripted xcrun holds what
reaches the tool: terminate before get_app_container, with the previous
run's files gone after. A simctl terminate that finds nothing to stop
still leaves the clear a success.

* docs(spec): an unbounded eventually is violated at run end

* docs(skills): an unreached eventually convicts at run end

* docs(skills): noUncaughtExceptions only fires on web

* fix(ios): a device clear-state that cannot happen must fail

--clear-data on a physical device with no --ios-app-path warned and then
ran anyway, so the run started on the previous run's data while the flag
said it started clean. There is no data-container wipe on a device, so
there is nothing to fall back to.

* test(ios): a device clear-state without an app path ends the run

* docs(skills): the stock properties each cover one platform

* docs(ci): the balance property demands a bound, not an equality

* fix(ios): the clear-state guard checks the bundle that was cleared

A bool only said that something was cleared, so Launch(ctx, otherBundle,
clearState=true) passed the guard and reported a reset that had reached a
different app. Record what was cleared and compare against the bundle
being launched.

* test(ios): a clear-state launch for an uncleared bundle is refused

* docs(manual): the flagship property is a bound, and say what that costs

* fix(ios): one address picker for every bring-up

bringUpRunner reads the picker from a field, and NewDevice only ever set
the device one, so a device driver that reached bringUpRunner would call
nil. The two fields held the same function; keeping one leaves no path
that can be wired without it.

* test(ios): a device driver can bring a runner up

* docs(skills): both shipped balance forms are bounds now

* docs(skills): name the balance predicate that still exists

* docs(skills): quote the doctor the binary actually prints

* docs(skills): screen= is the chrome driver's url, web only

* docs(skills): substring selector matching is native only

* docs(skills): web selectors are exact, native ones are substrings

* fix(ci): a run that wrote no trace is not evidence about folio

run_dir is empty when the run produced no output directory, and the
fallback made trace ./trace.jsonl. A stray trace in the working directory
was then read as this run's, so a run that wrote nothing reported 'found
the submit bug' and exited 0, defeating the missing-trace check below it.

* fix(ci): fail folio when a gated property is not in the spec

Nothing tied GATED_PROPERTIES to the spec it gates. Renaming a property
left the classifier matching nothing: ios and web blamed the spec for
finding a different bug, and android silently reclassified a real
conviction as 'judging health only' and stayed green.

replay-ui-summary.sh already makes this check for its own list. The spec
path becomes SPEC-overridable the same way, so the check is testable.

* test(ci): cover the folio classifier's verdicts

21 cases through a stubbed sanderling: every exit path, the drift check,
a missing trace, a zero-byte trace, an empty glob and a truncated line.
Asserts the flags that reached the binary, not just the exit code.

Invoked as bash -eo pipefail -c, which is what a run: block does. Running
folio-run.sh itself under -e would kill it at the first non-zero
sanderling test, which is the exit code it exists to read.

* docs(skills): defaultActions bundles five of the eight generators

* test(ios): name the picker test for what it covers

* docs(skills): three of the replay-ui properties are cross-panel

* docs(manual): state.exceptions is web only and reportError does not exist

* fix(folio): the bound carries no unconfirmed-submit guard

deleting confirmedApplied here broke 0 of 355 tests: under a bound a submit
that may not have landed moves the balance by 0, which the bound already
permits, so the guard could only ever drop the double commit it exists to
catch. the relaunch guard stays for a reason the bound does not cover, and
both tests now assert a verdict that changes when their guard does.

* docs(ci): three of the replay-ui properties are cross-panel

* docs(manual): the starter property only fires on web

* test(folio): judge the conjunct on the landings a real run produces

three of the 18 frames the recorded ios run drove it down, each with the
second commit the bound is there to catch. neutering the comparison reddens
it: a second commit on 357900 went unjudged.

* test(folio): the walk drives the composition the spec runs

countSubmitsInWindow never saw an amountText here, so every walk test counted
submits the app must have refused. with the field passed, a refused submit no
longer buys a later double tap an alibi: without it the window reads 3, not 1.

* docs(folio): say which double submit the conjunct can see, and which it cannot

the home landing is the counting invariant's, three of three in the recorded
ios run; this one gets the interleaving whose second pop is cancelled. it is
still the only judge on the 18 ledger landings that run produced.

* docs(folio): the narrow window is not where the detection comes from

the double taps land on home, so the counting form convicts them; what turned
0 convictions into 4 on the recorded ios run is submitCouldCommit, which drops
the windows at those three steps from 5/4/7 to 2/1/2.

* docs(skills): folio drives three platforms from one spec

* fix(folio): an amount over the app's cap spends no window budget

the corpus reaches TxnSubmit with 999999999999999999999, AMOUNT_REGEX takes it
and AddTransactionViewModel refuses it against MAX_TRANSACTION_AMOUNT_CENTS, so
counting it was budget a double submit could hide behind.

* docs(folio): say which form judged one step, not which node was read once

* docs: a bound still needs the relaunch guard, and eventually does convict

* fix(sidecar): the hierarchy rpc serves the tree the snapshot reads

the runner compares the two per step, but snapshot settles and closes a
keyboard while hierarchy was a bare contentDescriptor. measured on emulator
-5556 (api 34) with an ime open: 489 nodes against the snapshot's 134. both
now come off snapshotTree under the same lock; the reread still costs ~75ms
when no keyboard is up.

* docs(runner): say what makes the two reads comparable

the reread's comment claimed the round trip was the only interval between
them; what it left out is that the two rpcs have to read the same way, which
the repo's own android backend did not do.

* refactor(runner): name the settle predicate for what it means

* ci: add a headless-chrome composite action

The setup-chrome / apparmor sysctl / launch-check trio is copied across
three jobs. The old comment described setup-chrome v1 semantics: under v2
stable is the default and the alternative is Chrome for Testing latest,
not a dev Chromium, so it is restated for what the pin actually does.

* ci(examples): add the folio setup actions

folio-app holds the per-platform toolchain and app build, so a caller
guards one step instead of eight. folio-simulator boots the simulator,
installs folio and leaves the app stopped.

* ci(examples): add the replay-ui fixture action

Records a trace and serves it with sanderling replay. The step page URL
is a composite output rather than GITHUB_ENV, so it is scoped to the one
step that drives it.

* ci(examples): one dispatch workflow for every example

folio.yml and replay-ui.yml ran the same operation: build sanderling for
a platform, bring a target up, run a spec against it, classify the trace,
upload the run. They are now one matrix over four examples, each naming
its own runner.

The job is named for what it fuzzes. 'dogfood' named why we run it, not
what runs, the same error as a diagnostic that reports a motivation
instead of an observation.

The matrix is computed by a plan job because jobs.<id>.if cannot read the
matrix context, so a static matrix has no way to leave a leg out. Seeds,
budgets, timeouts, runners and artifact names are unchanged.

* ci: reuse the headless-chrome action in the browser job

Same three steps the examples workflow needs, and the comment explaining
the AppArmor sysctl now lives in one place.

* ci: move the folio jdk step to setup-java v5

The only setup-java left on v4; every other one moved.

* ci: pin third-party actions to commit shas

buf-setup-action was already pinned with a comment saying why; the other
five rode mutable major tags, so a tag move is an unreviewed change to
what runs. Each major currently resolves to the release named in the
comment, so this freezes today's behaviour rather than changing it.

actions/* stay on major tags: they are first-party to the runner.

* ci(replay-ui): name the run directory for what it fuzzes

runs/dogfood and the '### replay-ui dogfood' heading carried the same
naming error as the job name: dogfooding is why the run exists, not what
it fuzzes.

* docs(driver): state the log level scale on LogEntry

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(sidecar): name the device the node counts came off

* fix(chrome): keep a log entry the level scale cannot rank

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* fix(chrome): record console levels on the logcat scale

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): say why upload-pages-artifact needs no include-hidden-files

v3 to v5 crossed v4's change to exclude dot-files. build/site has none,
so nothing was dropped, and the underscore directory is not hidden.

* test(browser): drive a console error through to the spec

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ioscompanion): name the vacuity behind the empty log slice

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: run the folio classifier's test in make test-ci-scripts

* fix(chrome): keep the message of an object console argument

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(browser): cover console.error with an error object

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(spec): let the runner install state.logs in the page

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(verifier): encode state.logs for the web host

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(chrome): install the step's logs in the page

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(ci): pin three real folio traces from run 31902501859

ios convicted on submitCommitsOneTransactionPerAction, web on both gated
properties, android ran its full 200 steps healthy. Every step is kept;
of each step only step, violations, witnesses and residuals survive.

hierarchy is replaced by the quoted "...Screen" resource ids it held, in
order. It cannot just be dropped: it is 95% of the bytes and also the
only place the android route gate's grep can match, so dropping it flips
that leg from healthy to 'never reached'. 8.4MB to 59KB.

* test(ci): drive the classifier over the real traces

Four cases on real data: each leg's real verdict, plus the android trace
cut before it reached the transaction screen, which is what proves the
route gate reads a real hierarchy dump.

Also corrects the hand-written fixtures. They set is_error to false on a
plain violation; internal/trace/writer.go tags that field omitempty, so a
real trace omits it entirely. Harmless to the classifier, but a fixture
that does not look like reality is the thing that hides drift.

* test(runner): teach the web fakes to take the step's logs

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* fix(runner): install the step's logs before the page extracts

On web every extractor reading is replaced by the one the page computed,
and the page answered logs: [], so noLogcatErrors counted an empty array
however full of errors the console was.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(runner): cover the logs reaching the page and failing to

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(spec): cover the host pushing state.logs into the page

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(browser): drive console.error through to a fired property

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* fix(runner): report a log fetch the driver could not make

The comment claimed the failure was warned about; nothing warned, so a
device whose log fetch failed every step held noLogcatErrors on evidence
nobody collected.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* test(runner): cover the silently dropped log fetch

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* fix(ci): read the route the spec reports, not the hierarchy dump

The android health gate grepped the trace for "AddTransactionScreen",
which occurs in exactly one place: the hierarchy dump, as a resource-id.
That is a debug artifact standing in for a fact the spec already reports,
and it was wrong in both directions. Against the real 8.4MB trace with
hierarchy stripped, the old gate failed a healthy 200-step run; against a
trace carrying the marker on a transition frame without the route ever
being reported, it passed and called it healthy.

It reads extractor_changes.route now, whose values come from SCREENS in
the spec, so the gate and the app agree on what being on a screen means.
routeOf answers null on a frame showing two screens, which is exactly the
frame the marker was matching.

The drift check grows to cover both new names: extract("route") and the
SCREENS key. The fixtures are re-derived keeping the route entry and no
hierarchy at all; the full artifacts and the fixtures give byte-identical
verdicts, which is what proves the coupling is gone.

Script and fixtures move together: either alone leaves the suite red.

* ci: check that the workflow references resolve

actionlint reads a local action's inputs but never checks its path
exists: uses: ./.github/actions/typo lints clean and fails only when the
job runs. Covers composite action paths, make targets including the ones
the examples matrix builds from $SANDERLING, and the scripts a run: step
invokes plus their executable bit.

Fails when it parses fewer references out of a file than that file
mentions, because a checker that matches nothing reports a safety it
never looked for.

* ci: lint the workflows on every pr

The workflows that fuzz the examples are dispatch-only, and GitHub will
not dispatch a workflow that is not on the default branch, so their first
real run is after merge. actionlint and the reference checker are the
only things that can fail before that.

actionlint is pinned by commit, and its tool version is pinned too so a
new release cannot change what CI enforces.

* ci: collapse the four workflows into one

Nine jobs written out one by one, each with its own steps and its own
calibrated seed and budget as literals. Triggers are pull requests, master
and v* tags, and a dispatch with no inputs.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: inline the two composite actions with one caller each

Both existed to give the matrix a per-target hook. folio-app and
headless-chrome stay: three and three callers.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: check that no run: block interpolates an expression

A ${{ }} lands in the script text before bash reads the line, and
actionlint only flags the contexts it already knows are attacker
controlled. Nothing enforced the rule the workflow follows. Also drops the
matrix table lookup, which has no table to read now.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci(folio): name the run, not the fuzzer, in the clean-run message

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs: point at the workflow that holds the release secrets now

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: name every job Category (variant), and gate the lot on one check

Follows the convention in antithesishq/bombadil: the display name is what
groups a run in the Actions UI, so Check (tests), Check (browser),
Check (workflows), Folio (android), Folio (ios), Folio (web), Replay UI,
Release and Docs. Every job carries a name, so none of them falls back to
its kebab-case id.

All checks passed needs all nine and runs with if: always(), so branch
protection has one check to point at and a skipped job cannot read as a
pass. Release and docs now gate on startsWith(github.ref, 'refs/tags/v')
alongside master, which is the form the trigger filter already uses.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: split the release job back in two

Collapsing them left the npm publish steps in a job holding contents:
write, because GoReleaser needs it, so npm ci ran its dependency lifecycle
scripts with a write-capable GITHUB_TOKEN in reach of the same job as a
live NPM_TOKEN. Release (npm) is back on contents: read and Release (cli)
keeps contents: write, which is what they each had before.

Each validates the tag from its own copy of the pattern rather than
waiting on a job that exists only to pass a string. Release (cli) is tags
only: there is no CLI to cut on a merge.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: run folio on pull requests

folio was skipped on pull requests, so ios, android and web only ever ran
after a merge. The three legs are 3 to 19 minutes and run in parallel, and
a superseded pull request run already cancels itself.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* ci: draw each group as its own box in the run graph

The run graph boxes jobs together when they share the same dependencies and
the same dependents. All ten jobs fed only all-checks-passed, so all ten drew
as one pile. A gate per group gives each group a dependent that is exactly
that group.

Release and docs now need the checks, which they should have all along: npm
publish and the pages deploy ran on a merge without waiting for the test job.
Folio stays unblocked so a 20 minute leg does not wait on a 3 minute one.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

sidecar/src/main/kotlin/dev/sanderling/sidecar/DriverBackend.kt

@@ -30,11 +30,21 @@ interface DriverBackend {
     fun healthy(): Boolean
     fun metrics(bundleId: String): MetricsSample
 
+    // snapshotTree is the tree a snapshot reads, without the screenshot. It is
+    // what the Hierarchy RPC serves, so the runner's two reads of a step come
+    // off one pipeline: a backend that waits out a transition or closes a
+    // keyboard before reading has to do the same on both, or the two trees
+    // differ over what the backend did between them rather than over what the
+    // app did. Measured on an API 34 emulator, an IME standing open is a
+    // 489-node bare read against the snapshot's 134.
+    fun snapshotTree(): String = hierarchy()
+
     // snapshot captures hierarchy then screenshot back-to-back. The service
     // layer holds a mutex around the call so concurrent callers observe a
     // serialized pair from the same on-device frame. Backends may override
     // to fuse the two reads more tightly when their native API allows.
-    fun snapshot(): SnapshotSample = SnapshotSample(hierarchy(), screenshot())
+    fun snapshot(): SnapshotSample =
+        SnapshotSample(snapshotTree(), screenshot())
 
     // close releases device-side resources on shutdown. The iOS backend must
     // stop its XCTest runner here: an orphaned runner session auto-restarts
@@ -185,7 +195,8 @@ private val ROUTE_TAG_KEYS = setOf(
     "accessibilityIdentifier",
 )
 
-private val jsonMapper = com.fasterxml.jackson.module.kotlin.jacksonObjectMapper()
+private val jsonMapper =
+    com.fasterxml.jackson.module.kotlin.jacksonObjectMapper()
 
 // countRouteScreens counts DISTINCT route-level destination tags, not the nodes
 // carrying them. A screen that nests a node repeating its own route id puts two
@@ -328,11 +339,12 @@ internal fun readLogcat(
         arguments.add(since)
     }
     return try {
-        val process = ProcessBuilder(
-            adbCmd(serial) + arguments,
-        ).redirectErrorStream(false).start()
-        val output = process.inputStream.bufferedReader().readText()
-        process.waitFor()
+        val command = adbCmd(serial) + arguments
+        val output = readProcessOutput(
+            ProcessBuilder(command).redirectErrorStream(false).start(),
+            ADB_OUTPUT_TIMEOUT_MILLIS,
+            describe = { command.joinToString(" ") },
+        )
         StubDriverBackend.parseLogcatOutput(output)
     } catch (cause: Exception) {
         println("adb logcat failed: $cause")
@@ -358,13 +370,76 @@ internal fun readProcMetrics(serial: String?, bundleId: String): MetricsSample {
 private fun adbCmd(serial: String?): List<String> =
     if (serial == null) listOf("adb") else listOf("adb", "-s", serial)
 
+// ADB_OUTPUT_TIMEOUT_MILLIS bounds the diagnostic adb reads: dumpsys, logcat,
+// `settings get`, /proc stats. None of them is the driver's data path, so the
+// bound wants to be generous enough that it cannot fire on a link that works,
+// and it is: a hierarchy fetch, far heavier than any of these, measures at a
+// 76ms median and a 168ms p90 over the same remote adb link. What it caps is
+// the other end, where a wedged adb once held a step ~100s.
+internal const val ADB_OUTPUT_TIMEOUT_MILLIS = 10_000L
+
+private val adbReaders: java.util.concurrent.ExecutorService =
+    java.util.concurrent.Executors.newCachedThreadPool { runnable ->
+        Thread(runnable, "adb-output").apply { isDaemon = true }
+    }
+
+// readProcessOutput returns a process's stdout, or "" when it does not arrive
+// inside timeoutMillis.
+//
+// The bound belongs on the READ, not on waitFor. readText ends at EOF, and a
+// wedged adb neither writes nor exits, so EOF never comes and a waitFor with a
+// timeout after it is a line that never runs. Waiting first and reading after
+// is worse still: a process with more to say than a pipe buffer holds, which
+// logcat and dumpsys both are, blocks writing while the waiter waits for it to
+// finish, and neither ever moves.
+//
+// So the read runs on a daemon thread and killing the process is what releases
+// it: destroy closes the pipe, the reader sees EOF, the thread ends. Returning
+// "" hands every caller the answer it already treats as "adb said nothing",
+// which is the safe direction for all of them.
+internal fun readProcessOutput(
+    process: Process,
+    timeoutMillis: Long,
+    describe: () -> String,
+    log: (String) -> Unit = { System.err.println(it) },
+): String {
+    val reader = adbReaders.submit<String> {
+        process.inputStream.bufferedReader().readText()
+    }
+    return try {
+        val output = reader.get(
+            timeoutMillis,
+            java.util.concurrent.TimeUnit.MILLISECONDS,
+        )
+        if (!process.waitFor(
+                timeoutMillis,
+                java.util.concurrent.TimeUnit.MILLISECONDS,
+            )
+        ) {
+            process.destroyForcibly()
+        }
+        output
+    } catch (cause: java.util.concurrent.TimeoutException) {
+        process.destroyForcibly()
+        reader.cancel(true)
+        log(
+            "warn: ${describe()} gave nothing in ${timeoutMillis}ms; " +
+                "killed it and read no answer",
+        )
+        ""
+    } catch (cause: Exception) {
+        process.destroyForcibly()
+        ""
+    }
+}
+
 private fun adbOutput(serial: String?, arguments: List<String>): String = try {
-    val process = ProcessBuilder(
-        adbCmd(serial) + arguments,
-    ).redirectErrorStream(false).start()
-    val output = process.inputStream.bufferedReader().readText()
-    process.waitFor()
-    output
+    val command = adbCmd(serial) + arguments
+    readProcessOutput(
+        ProcessBuilder(command).redirectErrorStream(false).start(),
+        ADB_OUTPUT_TIMEOUT_MILLIS,
+        describe = { command.joinToString(" ") },
+    )
 } catch (cause: Exception) {
     ""
 }
@@ -473,8 +548,14 @@ class StubDriverBackend(
     companion object {
         private const val IDLE_POLL_INTERVAL_MILLIS = 50L
 
+        // A count we could not read is not a count of zero. Defaulting it to
+        // zero made an unreadable dumpsys mean "nothing is animating, go
+        // ahead", which is the one answer the caller cannot check: it breaks
+        // out of the settle and snapshots whatever frame is on screen. Unknown
+        // keeps it waiting instead, inside the deadline waitForIdle already
+        // holds, and it agrees with the probe's own exception path.
         internal fun isAnimationCountIdle(grepOutput: String): Boolean =
-            (grepOutput.trim().toIntOrNull() ?: 0) == 0
+            grepOutput.trim().toIntOrNull() == 0
 
         internal fun parseResolvedActivity(
             bundleId: String,
@@ -496,8 +577,8 @@ class StubDriverBackend(
                 when (ch) {
                     ' ' -> sb.append("%s")
 
-                    '\\', '"', '\'', '&', '|', ';', '<', '>', '(', ')', '*', '?',
-                    '$', '`', '[', ']', '{', '}', '~', '#',
+                    '\\', '"', '\'', '&', '|', ';', '<', '>', '(', ')', '*',
+                    '?', '$', '`', '[', ']', '{', '}', '~', '#',
                     -> sb.append(
                         '\\',
                     ).append(ch)
@@ -779,6 +860,210 @@ internal fun typeChunks(
     return typed
 }
 
+// dismissSoftKeyboard closes an open IME, and issues nothing when none is open.
+//
+// The keyboard is its own window over the bottom of the app, and the hierarchy
+// carries only what is visible to the user, so every app node under it is
+// absent from the tree the picker enumerates targets from. Typing raises it, so
+// an IME left open hides a form's submit control for as long as the fuzzer
+// keeps typing into that form, which is a state it cannot type its way out of.
+//
+// The mInputShown guard is load-bearing rather than an optimisation: BACK is
+// what closes an open IME, and BACK with no IME open navigates out of the
+// screen, so an unguarded dismissal would make every InputText a back press.
+//
+// The flag trails the BACK it answers for, by about 0.6s on API 36, and a
+// second dismissal inside that window reads the stale true and back-presses an
+// IME that has already gone. What keeps that unreachable is the caller: one
+// dismissal per inputText, and the runner focuses the field with a tap before
+// every InputText, which raises the IME again long before this probe runs. A
+// caller that dismissed twice in a row, or typed without focusing first, would
+// lose that margin.
+//
+// treeWithoutKeyboard closes a keyboard too, on the snapshot path, and does not
+// cost this one its margin: it reads no flag, and the two are a waitForIdle and
+// a hierarchy fetch apart, several times the window in which this one is stale.
+internal fun dismissSoftKeyboard(shell: (String) -> String) {
+    if (!shell("dumpsys input_method").contains("mInputShown=true")) return
+    shell("input keyevent 4")
+}
+
+// KEYBOARD_DISMISS_READS bounds the re-reads a snapshot spends waiting for the
+// IME window to leave the tree after BACK. The window leaves over an
+// animation, so the first read back can still carry it. A hierarchy read
+// measures at a 76ms median and a 168ms p90 on the API 34 emulator, so with
+// the interval these four reads watch most of a second: several retractions
+// over, without turning a keyboard the app keeps re-raising into a wait with
+// no end.
+internal const val KEYBOARD_DISMISS_READS = 4
+internal const val KEYBOARD_DISMISS_INTERVAL_MILLIS = 100L
+
+// imePackageOf takes the package half of an input-method component id
+// ("pkg/.Service"), the form both `settings get secure default_input_method`
+// and dumpsys' mCurMethodId use. Anything that is not a package name reads as
+// "no IME known", which disables the dismissal rather than guessing.
+internal fun imePackageOf(component: String): String? =
+    component.trim().substringBefore('/')
+        .takeIf { it.isNotEmpty() && it.contains('.') }
+
+// treeShowsIme reports whether the keyboard window is in the tree, by the view
+// ids the IME's own resources give it ("pkg:id/name").
+internal fun treeShowsIme(treeJson: String, imePackage: String): Boolean =
+    treeJson.contains("$imePackage:id/")
+
+// treeWithoutKeyboard closes a keyboard standing in the snapshot and returns a
+// tree read after it has gone, or the tree it was given when none is open.
+//
+// It belongs here, before the read the picker chooses from, rather than after
+// the tap that raised the keyboard. Two reasons. The picker only ever sees
+// snapshots, so a dismissal anywhere later leaves this step choosing between
+// the handful of targets an open keyboard left in the tree, which is the
+// budget the fuzzer was losing. And the state it has to judge is settled here:
+// the action landed a waitForIdle ago, where straight after the tap the
+// keyboard is still on its way up and nothing it could read would say so yet.
+//
+// The tree is also a better guard than mInputShown. BACK closes an open
+// keyboard and navigates when none is open, so pressing it is only safe on a
+// true reading; mInputShown trails the keyboard by up to 0.6s, while a tree
+// carrying the IME's own view ids is the keyboard being on screen, read a
+// moment ago. Once dismissed, the re-reads confirm it went rather than pressing
+// BACK again, so a keyboard the app puts straight back costs re-reads and never
+// a second back press.
+internal fun treeWithoutKeyboard(
+    tree: String,
+    imePackage: String?,
+    dismiss: () -> Unit,
+    reread: () -> String,
+    sleep: (Long) -> Unit = { Thread.sleep(it) },
+): String {
+    if (imePackage == null || !treeShowsIme(tree, imePackage)) return tree
+    dismiss()
+    var current = tree
+    repeat(KEYBOARD_DISMISS_READS) {
+        sleep(KEYBOARD_DISMISS_INTERVAL_MILLIS)
+        current = reread()
+        if (!treeShowsIme(current, imePackage)) return current
+    }
+    return current
+}
+
+// SELECT_ALL_COMMAND selects the focused field's whole content with
+// CTRL+A (keycodes 113 and 29) and DELETE_KEY_COMMAND then deletes the
+// selection (keycode 67). Two key events, whatever the field holds.
+internal const val SELECT_ALL_COMMAND = "input keycombination 113 29"
+internal const val DELETE_KEY_COMMAND = "input keyevent 67"
+
+// DELETE_BATCH_KEYS bounds how many deletes ride in one `input keyevent`
+// invocation on the fallback path. `input` takes a list of keycodes, so the
+// round trip is paid per batch rather than per character: measured 2.3 ms/char
+// against the 29.6 ms/char of one round trip each.
+internal const val DELETE_BATCH_KEYS = 200
+
+internal fun deleteKeyCommands(count: Int, batch: Int): List<String> {
+    if (count <= 0) return emptyList()
+    val size = batch.coerceAtLeast(1)
+    return (0 until count).chunked(size).map { chunk ->
+        chunk.joinToString(" ", prefix = "input keyevent ") { "67" }
+    }
+}
+
+// focusedEditableTextLength reports how much text the focused text field
+// holds, or null when the tree names no focused text field. Null is "cannot
+// tell", which is not the same as empty and must not be read as it.
+//
+// The field is found by class, not by an "editable" attribute: maestro's tree
+// carries no such attribute. Class also settles the trap an open keyboard
+// sets, which is that the IME contributes a focused node of its own. That node
+// holds no text, so taking the first focused node would read a field still
+// holding 4096 characters as empty, and empty is the answer that stops the
+// erase.
+internal fun focusedEditableTextLength(treeJson: String): Int? {
+    if (treeJson.isBlank()) return null
+    return try {
+        focusedFieldLength(jsonMapper.readTree(treeJson))
+    } catch (_: Exception) {
+        null
+    }
+}
+
+private fun focusedFieldLength(
+    node: com.fasterxml.jackson.databind.JsonNode,
+): Int? {
+    val attributes = node.get("attributes")
+    if (attributes != null && attributes.isObject &&
+        attributes.get("focused")?.asText() == "true" &&
+        attributes.get("class")?.asText().orEmpty().endsWith("EditText")
+    ) {
+        return attributes.get("text")?.asText().orEmpty().length
+    }
+    val children = node.get("children") ?: return null
+    if (!children.isArray) return null
+    for (child in children) focusedFieldLength(child)?.let { return it }
+    return null
+}
+
+// eraseFocusedField clears the field the runner just tapped.
+//
+// maestro's eraseText sends one delete per character through its own
+// instrumentation, which measured 29.6 ms/char on the API 34 emulator: the
+// 4096-character string the corpus types cost ~121s to clear, a fifth of a 20
+// minute budget spent on one step. Selecting the content and deleting the
+// selection costs the same two key events at any length, measured 0.15s to
+// 1.16s for 4096 characters across API 34, 35 and 36.
+//
+// A fast erase that leaves characters behind would be far worse than a slow
+// one, because the next InputText appends to the residue and nothing
+// downstream detects it. So the result is read back off the tree, and a field
+// that is not empty, or that the tree cannot report on at all, is finished off
+// per character. Those deletes ride in batches, so even that path costs one
+// round trip per batch rather than the one per character this replaces.
+internal fun eraseFocusedField(
+    characterCount: Int,
+    shell: (String) -> Unit,
+    focusedTextLength: () -> Int?,
+) {
+    if (characterCount <= 0) return
+    shell(SELECT_ALL_COMMAND)
+    shell(DELETE_KEY_COMMAND)
+    if (focusedTextLength() == 0) return
+    for (command in deleteKeyCommands(characterCount, DELETE_BATCH_KEYS)) {
+        shell(command)
+    }
+}
+
+// typingOwner picks what the mid-type foreground guard holds later reads
+// against. A dumpsys it could read names the resumed package, and that is the
+// answer.
+//
+// A read that failed is the interesting case, and neither obvious answer is
+// right. Passing null hands typeChunks "no owner", which switches the guard off
+// altogether and lets the rest of the string spray into whatever holds the
+// foreground: an unreadable probe must never read as focus being fine. But
+// refusing to type is worse in practice. The failure is a degraded link, which
+// lasts, so every InputText in the run becomes a no-op, the budget goes on
+// typing nothing, and the run ends green having tested nothing.
+//
+// So it falls back to the bundle the run launched, which leaves the guard armed
+// against the app the keystrokes were meant for. That reference is better than
+// the resumed package anyway: a foreground already stolen before typing began
+// reads as its own owner, and the guard then matches it happily chunk after
+// chunk.
+internal fun typingOwner(
+    dumpsys: String,
+    launchedBundleId: String?,
+    warn: (String) -> Unit,
+): String? {
+    parseResumedPackage(dumpsys)?.let { return it }
+    warn(
+        "warn: could not read the foreground app; guarding typing with " +
+            (
+                launchedBundleId?.let { "the launched bundle $it" }
+                    ?: "nothing, no launch was recorded"
+                ),
+    )
+    return launchedBundleId
+}
+
 // resumedActivityPackage matches a "package/activity" component, mirroring the
 // Go scope guard's regex so both read the same dumpsys wording.
 private val resumedActivityPackage =
@@ -831,6 +1116,14 @@ internal fun <T> retryOpen(
 class MaestroDriverBackend(private val serial: String?) : DriverBackend {
     private val dadb: dadb.Dadb = buildDadb(serial)
 
+    private val imePackage: String? by lazy {
+        imePackageOf(
+            runCatching {
+                dadb.shell("settings get secure default_input_method").allOutput
+            }.getOrDefault(""),
+        )
+    }
+
     // A fresh AndroidDriver per open attempt. Its gRPC channel is built once in
     // the constructor and permanently shut down by close(), so reopening a
     // closed instance would reuse a dead channel; rebuild it each try instead.
@@ -847,6 +1140,9 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
             }
         }
 
+    @Volatile
+    private var launchedBundleId: String? = null
+
     override fun launch(
         bundleId: String,
         clearState: Boolean,
@@ -854,6 +1150,7 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
     ) {
         if (clearState) driver.clearAppState(bundleId)
         driver.launchApp(bundleId, env)
+        launchedBundleId = bundleId
     }
 
     override fun terminate(bundleId: String) = driver.stopApp(bundleId)
@@ -885,6 +1182,11 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
         } else {
             driver.inputText(text)
         }
+        // A probe that fails reads as "no IME open", which is the safe way to be
+        // wrong: it skips the dismissal rather than sending a stray BACK.
+        dismissSoftKeyboard {
+            runCatching { dadb.shell(it).allOutput }.getOrDefault("")
+        }
     }
 
     // typeShellSafe types shell-safe ASCII through adb `input text` in chunks,
@@ -892,8 +1194,14 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
     // started in has lost the foreground, the remaining keystrokes would spray
     // into whatever window stole it (the launcher search box, in practice), so
     // typing stops instead of leaking out of the app under test.
+    //
+    // typingOwner decides what "the app the type started in" means when the
+    // read that would name it fails: the launched bundle, so a link that cannot
+    // answer degrades the guard rather than switching it off.
     private fun typeShellSafe(text: String) {
-        val owner = foregroundPackage()
+        val owner = typingOwner(foregroundDumpsys(), launchedBundleId) {
+            System.err.println(it)
+        }
         val typed =
             typeChunks(chunkForInput(text, INPUT_CHUNK_CHARS), owner, {
                 foregroundPackage()
@@ -907,17 +1215,21 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
         }
     }
 
-    // foregroundPackage returns the package of the top resumed activity, or null
-    // if it cannot be read. Used to detect mid-type focus escapes.
-    private fun foregroundPackage(): String? = parseResumedPackage(
-        adbOutput(
-            serial,
-            listOf("shell", "dumpsys", "activity", "activities"),
-        ),
+    private fun foregroundDumpsys(): String = adbOutput(
+        serial,
+        listOf("shell", "dumpsys", "activity", "activities"),
     )
 
-    override fun eraseText(characterCount: Int) =
-        driver.eraseText(characterCount)
+    // foregroundPackage returns the package of the top resumed activity, or null
+    // if it cannot be read. Used to detect mid-type focus escapes.
+    private fun foregroundPackage(): String? =
+        parseResumedPackage(foregroundDumpsys())
+
+    override fun eraseText(characterCount: Int) = eraseFocusedField(
+        characterCount,
+        shell = { dadb.shell(it) },
+        focusedTextLength = { focusedEditableTextLength(hierarchy()) },
+    )
 
     override fun swipe(
         fromX: Int,
@@ -948,8 +1260,8 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
     override fun recentLogs(sinceUnixMillis: Long, minLevel: String) =
         readLogcat(serial, sinceUnixMillis, minLevel)
 
-    // snapshot waits out a NavHost cross-fade before it reads, so the runner is
-    // never handed a tree holding two routes at once. It belongs here rather
+    // snapshotTree waits out a NavHost cross-fade before it reads, so the runner
+    // is never handed a tree holding two routes at once. It belongs here rather
     // than in waitForIdle: the runner gives waitForIdle a one-second deadline
     // and abandons the RPC when it expires, which is not enough room for a
     // 700ms fade that began before the settle did, and a wait that outlives the
@@ -960,9 +1272,15 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
     // The predicate costs nothing on a settled frame: the read it needs is the
     // read the snapshot was going to do anyway. That is what makes this
     // affordable, where the structural poll that used to run in waitForIdle was
-    // not: it fetched the hierarchy ~4 more times on every mutating step.
-    override fun snapshot(): SnapshotSample =
-        SnapshotSample(awaitSettledTree { hierarchy() }, screenshot())
+    // not: it fetched the hierarchy ~4 more times on every mutating step. The
+    // keyboard leg costs nothing either when no IME is standing in the tree,
+    // which is what lets the Hierarchy RPC serve this too.
+    override fun snapshotTree(): String = treeWithoutKeyboard(
+        awaitSettledTree { hierarchy() },
+        imePackage,
+        dismiss = { runCatching { dadb.shell("input keyevent 4") } },
+        reread = { awaitSettledTree { hierarchy() } },
+    )
 
     override fun waitForIdle(durationMillis: Long) {
         // waitForAppToSettle blocks on the View-system animation and maestro's
@@ -1014,15 +1332,75 @@ internal fun dadbTargetFor(serial: String?): DadbTarget {
     }
 }
 
+internal data class AdbServerEndpoint(val host: String, val port: Int)
+
+private const val ADB_SERVER_HOST = "localhost"
+private const val ADB_SERVER_PORT = 5037
+
+// adbServerEndpoint reads where the adb server listens the way the adb CLI
+// reads it: ADB_SERVER_SOCKET ("tcp:host:port", or "tcp:port" for a server on
+// this machine) outranks the older ANDROID_ADB_SERVER_ADDRESS /
+// ANDROID_ADB_SERVER_PORT pair, and unset means the loopback default.
+//
+// A value it cannot read throws instead of falling back to loopback. The
+// fallback is the dangerous answer: emulator serials are numbered per server,
+// so a run aimed at a remote emulator-5554 would quietly drive whatever this
+// machine calls emulator-5554 and report the results as the remote device's.
+internal fun adbServerEndpoint(
+    env: (String) -> String? = System::getenv,
+): AdbServerEndpoint {
+    val socket = env("ADB_SERVER_SOCKET")?.trim().orEmpty()
+    if (socket.isNotEmpty()) return parseAdbServerSocket(socket)
+    val host = env("ANDROID_ADB_SERVER_ADDRESS")?.trim().orEmpty()
+    val port = env("ANDROID_ADB_SERVER_PORT")?.trim().orEmpty()
+    return AdbServerEndpoint(
+        host.ifEmpty { ADB_SERVER_HOST },
+        if (port.isEmpty()) {
+            ADB_SERVER_PORT
+        } else {
+            adbServerPort(port, "ANDROID_ADB_SERVER_PORT=\"$port\"")
+        },
+    )
+}
+
+private fun parseAdbServerSocket(value: String): AdbServerEndpoint {
+    val named = "ADB_SERVER_SOCKET=\"$value\""
+    val address = value.removePrefix("tcp:")
+    if (address == value) rejectAdbServerSocket(named)
+    val colon = address.lastIndexOf(':')
+    if (colon < 0) {
+        return AdbServerEndpoint(
+            ADB_SERVER_HOST,
+            adbServerPort(address, named),
+        )
+    }
+    val host = address.substring(0, colon)
+    if (host.isEmpty()) rejectAdbServerSocket(named)
+    return AdbServerEndpoint(
+        host,
+        adbServerPort(address.substring(colon + 1), named),
+    )
+}
+
+private fun rejectAdbServerSocket(named: String): Nothing =
+    throw IllegalArgumentException("$named is not tcp:host:port")
+
+private fun adbServerPort(text: String, named: String): Int =
+    text.toIntOrNull()?.takeIf { it in 1..65535 }
+        ?: throw IllegalArgumentException("$named has no usable port")
+
 private fun buildDadb(serial: String?): dadb.Dadb =
     when (val target = dadbTargetFor(serial)) {
         is DadbTarget.Tcp -> dadb.Dadb.create(target.host, target.port)
 
-        is DadbTarget.Server -> dadb.adbserver.AdbServer.createDadb(
-            "localhost",
-            5037,
-            "host:transport:${target.serial}",
-        )
+        is DadbTarget.Server -> {
+            val server = adbServerEndpoint()
+            dadb.adbserver.AdbServer.createDadb(
+                server.host,
+                server.port,
+                "host:transport:${target.serial}",
+            )
+        }
     }
 
 internal fun findBoundsBySelector(
@@ -1086,7 +1464,8 @@ internal fun pngHeight(bytes: ByteArray): Int {
         (bytes[22].toInt() and 0xFF shl 8) or (bytes[23].toInt() and 0xFF)
 }
 
-internal const val IOS_XCTEST_RUNNER_BUNDLE_ID = "dev.mobile.maestro-driver-iosUITests.xctrunner"
+internal const val IOS_XCTEST_RUNNER_BUNDLE_ID =
+    "dev.mobile.maestro-driver-iosUITests.xctrunner"
 
 // reapOrphanIosRunners kills XCTest runner sessions left over from a prior
 // run. A sidecar that died without its shutdown hook leaves its xcodebuild

sidecar/src/main/kotlin/dev/sanderling/sidecar/DriverService.kt

@@ -31,7 +31,10 @@ class DriverService(
     private val launchedBundleId = AtomicReference<String?>(null)
     private val snapshotLock = Any()
 
-    override fun launch(request: LaunchRequest, responseObserver: StreamObserver<Empty>) {
+    override fun launch(
+        request: LaunchRequest,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.launch(request.bundleId, request.clearState, request.envMap)
             launchedBundleId.set(request.bundleId)
@@ -39,7 +42,10 @@ class DriverService(
         }
     }
 
-    override fun terminate(request: Empty, responseObserver: StreamObserver<Empty>) {
+    override fun terminate(
+        request: Empty,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             launchedBundleId.get()?.let { backend.terminate(it) }
             launchedBundleId.set(null)
@@ -54,42 +60,60 @@ class DriverService(
         }
     }
 
-    override fun doubleTap(request: Point, responseObserver: StreamObserver<Empty>) {
+    override fun doubleTap(
+        request: Point,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.doubleTap(request.x, request.y)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun longPress(request: Point, responseObserver: StreamObserver<Empty>) {
+    override fun longPress(
+        request: Point,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.longPress(request.x, request.y)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun tapSelector(request: Selector, responseObserver: StreamObserver<Empty>) {
+    override fun tapSelector(
+        request: Selector,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.tapSelector(request.value)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun inputText(request: Text, responseObserver: StreamObserver<Empty>) {
+    override fun inputText(
+        request: Text,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.inputText(request.value)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun eraseText(request: EraseTextRequest, responseObserver: StreamObserver<Empty>) {
+    override fun eraseText(
+        request: EraseTextRequest,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.eraseText(request.characterCount)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun swipe(request: SwipeRequest, responseObserver: StreamObserver<Empty>) {
+    override fun swipe(
+        request: SwipeRequest,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             val from = request.from
             val to = request.to
@@ -98,16 +122,25 @@ class DriverService(
         }
     }
 
-    override fun pressKey(request: PressKeyRequest, responseObserver: StreamObserver<Empty>) {
+    override fun pressKey(
+        request: PressKeyRequest,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.pressKey(request.key)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun recentLogs(request: RecentLogsRequest, responseObserver: StreamObserver<LogEntries>) {
+    override fun recentLogs(
+        request: RecentLogsRequest,
+        responseObserver: StreamObserver<LogEntries>,
+    ) {
         runRpc(responseObserver) {
-            val entries = backend.recentLogs(request.sinceUnixMillis, request.levelAtLeast)
+            val entries = backend.recentLogs(
+                request.sinceUnixMillis,
+                request.levelAtLeast,
+            )
             val builder = LogEntries.newBuilder()
             for (entry in entries) {
                 builder.addEntries(
@@ -123,7 +156,10 @@ class DriverService(
         }
     }
 
-    override fun screenshot(request: Empty, responseObserver: StreamObserver<Image>) {
+    override fun screenshot(
+        request: Empty,
+        responseObserver: StreamObserver<Image>,
+    ) {
         runRpc(responseObserver) {
             val (png, width, height) = backend.screenshot()
             Image.newBuilder()
@@ -134,18 +170,34 @@ class DriverService(
         }
     }
 
-    override fun hierarchy(request: Empty, responseObserver: StreamObserver<HierarchyJSON>) {
+    // The runner reads this a second time per step to see whether the screen
+    // changed while it was looking, so it has to describe the same thing the
+    // snapshot's tree describes: same settle, same keyboard handling, same
+    // lock. Served off the bare backend read, the pair differed over what the
+    // backend did between them rather than over what the app did.
+    override fun hierarchy(
+        request: Empty,
+        responseObserver: StreamObserver<HierarchyJSON>,
+    ) {
         runRpc(responseObserver) {
-            HierarchyJSON.newBuilder().setJson(backend.hierarchy()).build()
+            val tree = synchronized(snapshotLock) { backend.snapshotTree() }
+            HierarchyJSON.newBuilder().setJson(tree).build()
         }
     }
 
-    override fun snapshot(request: Empty, responseObserver: StreamObserver<SnapshotResponse>) {
+    override fun snapshot(
+        request: Empty,
+        responseObserver: StreamObserver<SnapshotResponse>,
+    ) {
         runRpc(responseObserver) {
             val sample = synchronized(snapshotLock) { backend.snapshot() }
             val (png, width, height) = sample.screenshot
             SnapshotResponse.newBuilder()
-                .setHierarchy(HierarchyJSON.newBuilder().setJson(sample.hierarchyJson).build())
+                .setHierarchy(
+                    HierarchyJSON.newBuilder()
+                        .setJson(sample.hierarchyJson)
+                        .build(),
+                )
                 .setScreenshot(
                     Image.newBuilder()
                         .setPng(ByteString.copyFrom(png))
@@ -157,14 +209,20 @@ class DriverService(
         }
     }
 
-    override fun waitForIdle(request: Duration, responseObserver: StreamObserver<Empty>) {
+    override fun waitForIdle(
+        request: Duration,
+        responseObserver: StreamObserver<Empty>,
+    ) {
         runRpc(responseObserver) {
             backend.waitForIdle(request.millis)
             Empty.getDefaultInstance()
         }
     }
 
-    override fun health(request: Empty, responseObserver: StreamObserver<HealthStatus>) {
+    override fun health(
+        request: Empty,
+        responseObserver: StreamObserver<HealthStatus>,
+    ) {
         runRpc(responseObserver) {
             HealthStatus.newBuilder()
                 .setReady(backend.healthy())
@@ -174,9 +232,16 @@ class DriverService(
         }
     }
 
-    override fun metrics(request: MetricsRequest, responseObserver: StreamObserver<MetricsResponse>) {
+    override fun metrics(
+        request: MetricsRequest,
+        responseObserver: StreamObserver<MetricsResponse>,
+    ) {
         runRpc(responseObserver) {
-            val bundleId = if (request.bundleId.isNotEmpty()) request.bundleId else launchedBundleId.get().orEmpty()
+            val bundleId = if (request.bundleId.isNotEmpty()) {
+                request.bundleId
+            } else {
+                launchedBundleId.get().orEmpty()
+            }
             val sample = backend.metrics(bundleId)
             MetricsResponse.newBuilder()
                 .setCpuPercent(sample.cpuPercent)
@@ -191,7 +256,9 @@ class DriverService(
     // stale session, then closes the backend so the iOS XCTest runner process
     // dies with us instead of being orphaned.
     fun shutdown() {
-        runCatching { launchedBundleId.getAndSet(null)?.let { backend.terminate(it) } }
+        runCatching {
+            launchedBundleId.getAndSet(null)?.let { backend.terminate(it) }
+        }
         runCatching { backend.close() }
     }
 
@@ -209,8 +276,10 @@ class DriverService(
             // failures that do not extend Exception, and an uncaught one
             // kills the RPC as a channel-level Unknown instead of a status
             // the runner can classify.
-            observer.onError(io.grpc.Status.INTERNAL.withDescription(cause.toString())
-                .withCause(cause).asRuntimeException())
+            observer.onError(
+                io.grpc.Status.INTERNAL.withDescription(cause.toString())
+                    .withCause(cause).asRuntimeException(),
+            )
         }
     }
 

sidecar/src/main/kotlin/dev/sanderling/sidecar/Main.kt

@@ -13,14 +13,17 @@ class SidecarServer(
     private val shutdownLatch = CountDownLatch(1)
 
     fun start(): Int {
-        val server = NettyServerBuilder.forAddress(InetSocketAddress("127.0.0.1", port))
+        val server = NettyServerBuilder
+            .forAddress(InetSocketAddress("127.0.0.1", port))
             .addService(service)
             .build()
         server.start()
         grpcServer = server
-        Runtime.getRuntime().addShutdownHook(Thread {
-            stop()
-        })
+        Runtime.getRuntime().addShutdownHook(
+            Thread {
+                stop()
+            },
+        )
         return server.port
     }
 
@@ -48,23 +51,41 @@ class SidecarServer(
 // lost from run output.
 private fun quietExpectedDriverNoise() {
     org.apache.logging.log4j.core.config.Configurator.setLevel(
-        "util.CommandLineUtils", org.apache.logging.log4j.Level.OFF)
+        "util.CommandLineUtils",
+        org.apache.logging.log4j.Level.OFF,
+    )
     org.apache.logging.log4j.core.config.Configurator.setLevel(
-        "xcuitest.XCTestDriverClient", org.apache.logging.log4j.Level.OFF)
+        "xcuitest.XCTestDriverClient",
+        org.apache.logging.log4j.Level.OFF,
+    )
     org.apache.logging.log4j.core.config.Configurator.setLevel(
-        "maestro.drivers.AndroidDriver", org.apache.logging.log4j.Level.OFF)
+        "maestro.drivers.AndroidDriver",
+        org.apache.logging.log4j.Level.OFF,
+    )
 }
 
 fun main(arguments: Array<String>) {
     quietExpectedDriverNoise()
     val port = arguments.indexOf("--port").let { index ->
-        if (index >= 0 && index + 1 < arguments.size) arguments[index + 1].toInt() else 0
+        if (index >= 0 && index + 1 < arguments.size) {
+            arguments[index + 1].toInt()
+        } else {
+            0
+        }
     }
     val platform = arguments.indexOf("--platform").let { index ->
-        if (index >= 0 && index + 1 < arguments.size) arguments[index + 1] else "android"
+        if (index >= 0 && index + 1 < arguments.size) {
+            arguments[index + 1]
+        } else {
+            "android"
+        }
     }
     val serial = arguments.indexOf("--serial").let { index ->
-        if (index >= 0 && index + 1 < arguments.size) arguments[index + 1] else null
+        if (index >= 0 && index + 1 < arguments.size) {
+            arguments[index + 1]
+        } else {
+            null
+        }
     }
 
     val backend: DriverBackend = when (platform) {
@@ -74,7 +95,9 @@ fun main(arguments: Array<String>) {
     val service = DriverService(platform = platform, backend = backend)
     val server = SidecarServer(port, service)
     val boundPort = server.start()
-    println("sanderling-sidecar listening on 127.0.0.1:$boundPort platform=$platform")
+    println(
+        "sanderling-sidecar listening on 127.0.0.1:$boundPort platform=$platform",
+    )
     System.out.flush()
     server.awaitTermination()
 }

sidecar/src/test/kotlin/dev/sanderling/sidecar/AdbOutputTimeoutTest.kt

@@ -0,0 +1,120 @@
+package dev.sanderling.sidecar
+
+import org.junit.Test
+import java.io.InputStream
+import java.io.OutputStream
+import java.util.concurrent.CountDownLatch
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class AdbOutputTimeoutTest {
+
+    // An adb wedged on the link neither writes nor exits, so the read never
+    // reaches EOF. Without a bound on the READ the step waits for as long as
+    // adb feels like it: one such stall measured ~100s against a remote adb
+    // server. The bound has to release the reader as well as return, which is
+    // what killing the process does.
+    @Test(timeout = 20_000L)
+    fun aWedgedReadIsAbandonedAtTheBoundInsteadOfHangingForever() {
+        val process = FakeProcess(BlockingStream())
+        val logged = mutableListOf<String>()
+
+        val started = System.currentTimeMillis()
+        val output = readProcessOutput(process, 200L, { "adb shell pidof" }) {
+            logged.add(it)
+        }
+        val elapsed = System.currentTimeMillis() - started
+
+        assertEquals("", output, "a read that never lands is no answer")
+        assertTrue(process.destroyed, "the wedged adb must be killed, not left")
+        assertTrue(
+            elapsed < 10_000L,
+            "returned in ${elapsed}ms, not at a bound",
+        )
+        assertEquals(1, logged.size, "a silent timeout hides a degrading link")
+    }
+
+    @Test(timeout = 20_000L)
+    fun theAbandonedReadNamesTheCommandAndTheBound() {
+        val logged = mutableListOf<String>()
+        readProcessOutput(
+            FakeProcess(BlockingStream()),
+            200L,
+            { "adb -s emulator-5556 shell cat /proc/6103/stat" },
+        ) { logged.add(it) }
+
+        val line = logged.single()
+        assertTrue(
+            line.contains("adb -s emulator-5556 shell cat /proc/6103/stat"),
+            line,
+        )
+        assertTrue(line.contains("200"), line)
+    }
+
+    // The bound must cost the healthy path nothing: output that arrives comes
+    // back whole, and the process is left to exit on its own.
+    @Test(timeout = 20_000L)
+    fun outputThatArrivesComesBackWholeAndTheProcessSurvives() {
+        val text = "VmRSS:\t  123456 kB\nVmSize:\t  654321 kB\n"
+        val process = FakeProcess(text.byteInputStream())
+        val logged = mutableListOf<String>()
+
+        val output = readProcessOutput(process, 5_000L, { "adb shell cat" }) {
+            logged.add(it)
+        }
+
+        assertEquals(text, output)
+        assertTrue(!process.destroyed, "a process that answered is not killed")
+        assertTrue(logged.isEmpty(), "nothing to report on the healthy path")
+    }
+
+    // Output larger than a pipe buffer is why the read cannot be deferred
+    // until after the process exits: a process with more to say than the
+    // buffer holds blocks writing while a waiter waits for it to finish.
+    @Test(timeout = 20_000L)
+    fun outputLargerThanAPipeBufferComesBackWhole() {
+        val text = "x".repeat(512 * 1024)
+        val output = readProcessOutput(
+            FakeProcess(text.byteInputStream()),
+            5_000L,
+            { "adb logcat -d" },
+        ) {}
+        assertEquals(text.length, output.length)
+    }
+}
+
+// BlockingStream models a wedged adb: no bytes, and no EOF either, until the
+// process is killed and the pipe closes under the reader.
+private class BlockingStream : InputStream() {
+    private val released = CountDownLatch(1)
+
+    override fun read(): Int {
+        released.await()
+        return -1
+    }
+
+    override fun close() {
+        released.countDown()
+    }
+}
+
+private class FakeProcess(private val stream: InputStream) : Process() {
+    @Volatile var destroyed = false
+        private set
+
+    override fun getOutputStream(): OutputStream =
+        OutputStream.nullOutputStream()
+
+    override fun getInputStream(): InputStream = stream
+
+    override fun getErrorStream(): InputStream = InputStream.nullInputStream()
+
+    override fun waitFor(): Int = 0
+
+    override fun exitValue(): Int = 0
+
+    override fun destroy() {
+        destroyed = true
+        stream.close()
+    }
+}

sidecar/src/test/kotlin/dev/sanderling/sidecar/DadbTargetTest.kt

@@ -2,6 +2,8 @@ package dev.sanderling.sidecar
 
 import org.junit.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertTrue
 
 class DadbTargetTest {
 
@@ -10,7 +12,10 @@ class DadbTargetTest {
     }
 
     @Test fun hostPortSerialConnectsDirectly() {
-        assertEquals(DadbTarget.Tcp("192.168.1.243", 5555), dadbTargetFor("192.168.1.243:5555"))
+        assertEquals(
+            DadbTarget.Tcp("192.168.1.243", 5555),
+            dadbTargetFor("192.168.1.243:5555"),
+        )
     }
 
     @Test fun usbSerialRoutesThroughAdbServer() {
@@ -20,6 +25,108 @@ class DadbTargetTest {
     // A colon with a non-numeric port is a USB serial that merely contains a
     // colon, not a host:port, so it must route through the adb server.
     @Test fun colonWithNonNumericPortIsAServerSerial() {
-        assertEquals(DadbTarget.Server("emulator:5554x"), dadbTargetFor("emulator:5554x"))
+        assertEquals(
+            DadbTarget.Server("emulator:5554x"),
+            dadbTargetFor("emulator:5554x"),
+        )
+    }
+
+    // A serial-addressed device is reached through whichever adb server the
+    // environment names. Ignoring it sends the run to this machine's own
+    // server, where the serial either is missing or, worse, names a different
+    // device that happens to share the emulator numbering.
+    @Test fun adbServerSocketNamesARemoteServer() {
+        assertEquals(
+            AdbServerEndpoint("100.68.126.75", 5037),
+            adbServerEndpoint(
+                env("ADB_SERVER_SOCKET" to "tcp:100.68.126.75:5037"),
+            ),
+        )
+    }
+
+    @Test fun adbServerSocketWithOnlyAPortStaysLocal() {
+        assertEquals(
+            AdbServerEndpoint("localhost", 5038),
+            adbServerEndpoint(env("ADB_SERVER_SOCKET" to "tcp:5038")),
+        )
+    }
+
+    @Test fun androidAdbServerAddressAndPortPairIsHonoured() {
+        assertEquals(
+            AdbServerEndpoint("10.0.0.4", 5040),
+            adbServerEndpoint(
+                env(
+                    "ANDROID_ADB_SERVER_ADDRESS" to "10.0.0.4",
+                    "ANDROID_ADB_SERVER_PORT" to "5040",
+                ),
+            ),
+        )
+    }
+
+    @Test fun adbServerSocketOutranksTheOlderPair() {
+        assertEquals(
+            AdbServerEndpoint("100.68.126.75", 5037),
+            adbServerEndpoint(
+                env(
+                    "ADB_SERVER_SOCKET" to "tcp:100.68.126.75:5037",
+                    "ANDROID_ADB_SERVER_ADDRESS" to "10.0.0.4",
+                    "ANDROID_ADB_SERVER_PORT" to "5040",
+                ),
+            ),
+        )
+    }
+
+    @Test fun unsetEnvironmentKeepsTheLoopbackDefault() {
+        assertEquals(
+            AdbServerEndpoint("localhost", 5037),
+            adbServerEndpoint(env()),
+        )
+        assertEquals(
+            AdbServerEndpoint("localhost", 5037),
+            adbServerEndpoint(env("ADB_SERVER_SOCKET" to "")),
+        )
+    }
+
+    @Test fun eitherHalfOfTheOlderPairAloneKeepsTheOtherDefault() {
+        assertEquals(
+            AdbServerEndpoint("10.0.0.4", 5037),
+            adbServerEndpoint(env("ANDROID_ADB_SERVER_ADDRESS" to "10.0.0.4")),
+        )
+        assertEquals(
+            AdbServerEndpoint("localhost", 5040),
+            adbServerEndpoint(env("ANDROID_ADB_SERVER_PORT" to "5040")),
+        )
+    }
+
+    // A value that cannot be read must stop the run and say which variable
+    // held what. Falling back to loopback would drive this machine's devices
+    // while the operator believes the run is on the remote ones.
+    @Test fun malformedValuesFailNamingTheVariableAndItsContents() {
+        val cases = mapOf(
+            "ADB_SERVER_SOCKET" to listOf(
+                "100.68.126.75:5037",
+                "tcp:100.68.126.75:pear",
+                "tcp:",
+                "tcp::5037",
+                "unix:/tmp/adb",
+                "tcp:100.68.126.75:70000",
+            ),
+            "ANDROID_ADB_SERVER_PORT" to listOf("pear", "0", "-1"),
+        )
+        for ((variable, values) in cases) {
+            for (value in values) {
+                val failure = assertFailsWith<IllegalArgumentException>(value) {
+                    adbServerEndpoint(env(variable to value))
+                }
+                val message = failure.message.orEmpty()
+                assertTrue(message.contains(variable), message)
+                assertTrue(message.contains(value), message)
+            }
+        }
     }
 }
+
+private fun env(vararg entries: Pair<String, String>): (String) -> String? {
+    val values = entries.toMap()
+    return { values[it] }
+}

sidecar/src/test/kotlin/dev/sanderling/sidecar/DeviceOutputParserTest.kt

@@ -24,7 +24,8 @@ class DeviceOutputParserTest {
         assertEquals("FATAL EXCEPTION: main", lines[0].message)
 
         val year = java.util.Calendar.getInstance().get(java.util.Calendar.YEAR)
-        val cal = java.util.Calendar.getInstance().apply { timeInMillis = lines[0].unixMillis }
+        val cal = java.util.Calendar.getInstance()
+            .apply { timeInMillis = lines[0].unixMillis }
         assertEquals(year, cal.get(java.util.Calendar.YEAR))
         assertEquals(56, cal.get(java.util.Calendar.SECOND))
         assertEquals(789, cal.get(java.util.Calendar.MILLISECOND))
@@ -51,7 +52,9 @@ class DeviceOutputParserTest {
 
     @Test fun parseCpuTicksReturnsNullOnTruncatedOrNonNumericStat() {
         assertNull(parseCpuTicks("1234 (app) S 1 2 3"))
-        assertNull(parseCpuTicks("1234 (app) S " + (1..12).joinToString(" ") { "x" }))
+        assertNull(
+            parseCpuTicks("1234 (app) S " + (1..12).joinToString(" ") { "x" }),
+        )
         assertNull(parseCpuTicks(""))
     }
 
@@ -79,8 +82,14 @@ class DeviceOutputParserTest {
     }
 
     @Test fun parseBoundsAcceptsWellFormedAndRejectsMalformed() {
-        assertEquals(listOf(0, 0, 1080, 2340), parseBounds("[0,0,1080,2340]")?.toList())
-        assertEquals(listOf(-5, -10, 20, 30), parseBounds("[-5,-10,20,30]")?.toList())
+        assertEquals(
+            listOf(0, 0, 1080, 2340),
+            parseBounds("[0,0,1080,2340]")?.toList(),
+        )
+        assertEquals(
+            listOf(-5, -10, 20, 30),
+            parseBounds("[-5,-10,20,30]")?.toList(),
+        )
         assertNull(parseBounds("[0,0,1080]"))
         assertNull(parseBounds("0,0,1,1"))
         assertNull(parseBounds("[0, 0, 1, 1]"))
@@ -92,10 +101,14 @@ class DeviceOutputParserTest {
             "resource-id" to "com.example:id/loginButton",
             "bounds" to "[10,20,110,80]",
         )
-        assertEquals(listOf(10, 20, 110, 80), findBoundsBySelector(tree, "id:loginButton")?.toList())
         assertEquals(
             listOf(10, 20, 110, 80),
-            findBoundsBySelector(tree, "id:com.example:id/loginButton")?.toList(),
+            findBoundsBySelector(tree, "id:loginButton")?.toList(),
+        )
+        assertEquals(
+            listOf(10, 20, 110, 80),
+            findBoundsBySelector(tree, "id:com.example:id/loginButton")
+                ?.toList(),
         )
     }
 
@@ -104,21 +117,36 @@ class DeviceOutputParserTest {
             "resource-id" to "root",
             children = listOf(
                 node("text" to "Sign in", "bounds" to "[1,2,3,4]"),
-                node("content-desc" to "AccountCardRow-7", "bounds" to "[5,6,7,8]"),
+                node(
+                    "content-desc" to "AccountCardRow-7",
+                    "bounds" to "[5,6,7,8]",
+                ),
             ),
         )
-        assertEquals(listOf(1, 2, 3, 4), findBoundsBySelector(tree, "text:Sign in")?.toList())
-        assertEquals(listOf(5, 6, 7, 8), findBoundsBySelector(tree, "descPrefix:AccountCard")?.toList())
+        assertEquals(
+            listOf(1, 2, 3, 4),
+            findBoundsBySelector(tree, "text:Sign in")?.toList(),
+        )
+        assertEquals(
+            listOf(5, 6, 7, 8),
+            findBoundsBySelector(tree, "descPrefix:AccountCard")?.toList(),
+        )
     }
 
     @Test fun findBoundsBySelectorReturnsNullForBadSelectorOrNoMatch() {
-        val tree = node("resource-id" to "com.example:id/x", "bounds" to "[0,0,1,1]")
+        val tree = node(
+            "resource-id" to "com.example:id/x",
+            "bounds" to "[0,0,1,1]",
+        )
         assertNull(findBoundsBySelector(tree, "id"))
         assertNull(findBoundsBySelector(tree, "id:missing"))
     }
 
     @Test fun findBoundsBySelectorReturnsNullWhenMatchHasMalformedBounds() {
-        val tree = node("resource-id" to "com.example:id/x", "bounds" to "not-bounds")
+        val tree = node(
+            "resource-id" to "com.example:id/x",
+            "bounds" to "not-bounds",
+        )
         assertNull(findBoundsBySelector(tree, "id:x"))
     }
 
@@ -132,17 +160,26 @@ class DeviceOutputParserTest {
     private fun ihdr(width: Int, height: Int): ByteArray {
         val b = ByteArray(33)
         for (i in 0 until 8) b[8 + i] = 0
-        b[12] = 'I'.code.toByte(); b[13] = 'H'.code.toByte()
-        b[14] = 'D'.code.toByte(); b[15] = 'R'.code.toByte()
-        b[16] = (width ushr 24).toByte(); b[17] = (width ushr 16).toByte()
-        b[18] = (width ushr 8).toByte(); b[19] = width.toByte()
-        b[20] = (height ushr 24).toByte(); b[21] = (height ushr 16).toByte()
-        b[22] = (height ushr 8).toByte(); b[23] = height.toByte()
+        b[12] = 'I'.code.toByte()
+        b[13] = 'H'.code.toByte()
+        b[14] = 'D'.code.toByte()
+        b[15] = 'R'.code.toByte()
+        b[16] = (width ushr 24).toByte()
+        b[17] = (width ushr 16).toByte()
+        b[18] = (width ushr 8).toByte()
+        b[19] = width.toByte()
+        b[20] = (height ushr 24).toByte()
+        b[21] = (height ushr 16).toByte()
+        b[22] = (height ushr 8).toByte()
+        b[23] = height.toByte()
         return b
     }
 
     private fun node(
         vararg attrs: Pair<String, String>,
         children: List<maestro.TreeNode> = emptyList(),
-    ): maestro.TreeNode = maestro.TreeNode(attributes = attrs.toMap().toMutableMap(), children = children)
+    ): maestro.TreeNode = maestro.TreeNode(
+        attributes = attrs.toMap().toMutableMap(),
+        children = children,
+    )
 }

sidecar/src/test/kotlin/dev/sanderling/sidecar/DriverServiceTest.kt

@@ -20,20 +20,34 @@ import org.junit.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertTrue
 
-private data class Quintuple<A, B, C, D, E>(val a: A, val b: B, val c: C, val d: D, val e: E)
+private data class Quintuple<A, B, C, D, E>(
+    val a: A,
+    val b: B,
+    val c: C,
+    val d: D,
+    val e: E,
+)
 
 class DriverServiceTest {
 
     @get:Rule val grpcCleanup: GrpcCleanupRule = GrpcCleanupRule()
 
-    private fun newClient(backend: DriverBackend): DriverGrpc.DriverBlockingStub {
+    private fun newClient(
+        backend: DriverBackend,
+    ): DriverGrpc.DriverBlockingStub {
         val serverName = InProcessServerBuilder.generateName()
         val service = DriverService(platform = "android", backend = backend)
         grpcCleanup.register(
-            InProcessServerBuilder.forName(serverName).directExecutor().addService(service).build().start()
+            InProcessServerBuilder.forName(serverName)
+                .directExecutor()
+                .addService(service)
+                .build()
+                .start(),
         )
         val channel: ManagedChannel = grpcCleanup.register(
-            InProcessChannelBuilder.forName(serverName).directExecutor().build()
+            InProcessChannelBuilder.forName(serverName)
+                .directExecutor()
+                .build(),
         )
         return DriverGrpc.newBlockingStub(channel)
     }
@@ -59,20 +73,32 @@ class DriverServiceTest {
         var terminated: String? = null
         var closed = false
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun terminate(bundleId: String) { terminated = bundleId }
-            override fun close() { closed = true }
+            override fun terminate(bundleId: String) {
+                terminated = bundleId
+            }
+            override fun close() {
+                closed = true
+            }
         }
         val serverName = InProcessServerBuilder.generateName()
         val service = DriverService(platform = "android", backend = backend)
         grpcCleanup.register(
-            InProcessServerBuilder.forName(serverName).directExecutor().addService(service).build().start()
+            InProcessServerBuilder.forName(serverName)
+                .directExecutor()
+                .addService(service)
+                .build()
+                .start(),
         )
         val channel: ManagedChannel = grpcCleanup.register(
-            InProcessChannelBuilder.forName(serverName).directExecutor().build()
+            InProcessChannelBuilder.forName(serverName)
+                .directExecutor()
+                .build(),
         )
         val client = DriverGrpc.newBlockingStub(channel)
 
-        client.launch(LaunchRequest.newBuilder().setBundleId("com.example").build())
+        client.launch(
+            LaunchRequest.newBuilder().setBundleId("com.example").build(),
+        )
         service.shutdown()
 
         assertEquals("com.example", terminated)
@@ -83,8 +109,12 @@ class DriverServiceTest {
         var terminated: String? = null
         var closed = false
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun terminate(bundleId: String) { terminated = bundleId }
-            override fun close() { closed = true }
+            override fun terminate(bundleId: String) {
+                terminated = bundleId
+            }
+            override fun close() {
+                closed = true
+            }
         }
         val service = DriverService(platform = "android", backend = backend)
 
@@ -128,17 +158,17 @@ class DriverServiceTest {
     // the runner can tell transient failures from fatal ones.
     @Test fun backendStatusCodePassesThrough() {
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun inputText(text: String) {
+            override fun inputText(text: String): Unit =
                 throw io.grpc.Status.UNAVAILABLE
                     .withDescription("connection dropped mid-action")
                     .asRuntimeException()
-            }
         }
         val client = newClient(backend)
 
-        val thrown = kotlin.test.assertFailsWith<io.grpc.StatusRuntimeException> {
-            client.inputText(Text.newBuilder().setValue("hello").build())
-        }
+        val thrown =
+            kotlin.test.assertFailsWith<io.grpc.StatusRuntimeException> {
+                client.inputText(Text.newBuilder().setValue("hello").build())
+            }
         assertEquals(io.grpc.Status.Code.UNAVAILABLE, thrown.status.code)
     }
 
@@ -147,17 +177,19 @@ class DriverServiceTest {
     // channel-level Unknown the runner cannot classify.
     @Test fun nonExceptionThrowableMapsToInternal() {
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun inputText(text: String) {
+            override fun inputText(text: String): Unit =
                 throw Throwable("only one gesture can be performed at a time")
-            }
         }
         val client = newClient(backend)
 
-        val thrown = kotlin.test.assertFailsWith<io.grpc.StatusRuntimeException> {
-            client.inputText(Text.newBuilder().setValue("hello").build())
-        }
+        val thrown =
+            kotlin.test.assertFailsWith<io.grpc.StatusRuntimeException> {
+                client.inputText(Text.newBuilder().setValue("hello").build())
+            }
         assertEquals(io.grpc.Status.Code.INTERNAL, thrown.status.code)
-        assertTrue(thrown.status.description.orEmpty().contains("only one gesture"))
+        assertTrue(
+            thrown.status.description.orEmpty().contains("only one gesture"),
+        )
     }
 
     @Test fun reapOrphanIosRunnersKillsStrayXcodebuildAndRunnerApp() {
@@ -171,7 +203,16 @@ class DriverServiceTest {
         assertEquals("pkill", commands[0][0])
         assertTrue(commands[0][2].contains("test-without-building"))
         assertTrue(commands[0][2].contains("UDID-1234"))
-        assertEquals(listOf("xcrun", "simctl", "terminate", "UDID-1234", IOS_XCTEST_RUNNER_BUNDLE_ID), commands[1])
+        assertEquals(
+            listOf(
+                "xcrun",
+                "simctl",
+                "terminate",
+                "UDID-1234",
+                IOS_XCTEST_RUNNER_BUNDLE_ID,
+            ),
+            commands[1],
+        )
     }
 
     @Test fun reapOrphanIosRunnersReportsNothingFound() {
@@ -192,7 +233,9 @@ class DriverServiceTest {
         // still executing fails instead of queuing.
         val tapAction = {
             if (!inFlight.compareAndSet(false, true)) {
-                throw IllegalStateException("only one gesture can be performed at a time")
+                throw IllegalStateException(
+                    "only one gesture can be performed at a time",
+                )
             }
             invocations.incrementAndGet()
             Thread.sleep(150)
@@ -211,7 +254,9 @@ class DriverServiceTest {
         val tapAction = {
             if (failedFirst.compareAndSet(false, true)) {
                 Thread.sleep(60)
-                throw IllegalStateException("only one gesture can be performed at a time")
+                throw IllegalStateException(
+                    "only one gesture can be performed at a time",
+                )
             }
             landed.incrementAndGet()
             Unit
@@ -226,21 +271,38 @@ class DriverServiceTest {
         // directly.
         val taps = mutableListOf<Pair<Int, Int>>()
         val backend = object : DriverBackend {
-            override fun launch(bundleId: String, clearState: Boolean, env: Map<String, String>) {}
+            override fun launch(
+                bundleId: String,
+                clearState: Boolean,
+                env: Map<String, String>,
+            ) {}
             override fun terminate(bundleId: String) {}
-            override fun tap(x: Int, y: Int) { taps.add(x to y) }
+            override fun tap(x: Int, y: Int) {
+                taps.add(x to y)
+            }
             override fun tapSelector(selector: String) {}
             override fun inputText(text: String) {}
             override fun eraseText(characterCount: Int) {}
-            override fun swipe(fromX: Int, fromY: Int, toX: Int, toY: Int, durationMillis: Long) {}
+            override fun swipe(
+                fromX: Int,
+                fromY: Int,
+                toX: Int,
+                toY: Int,
+                durationMillis: Long,
+            ) {}
             override fun pressKey(key: String) {}
             override fun longPress(x: Int, y: Int) {}
-            override fun screenshot(): Triple<ByteArray, Int, Int> = Triple(byteArrayOf(), 0, 0)
+            override fun screenshot(): Triple<ByteArray, Int, Int> =
+                Triple(byteArrayOf(), 0, 0)
             override fun hierarchy(): String = "{}"
-            override fun recentLogs(sinceUnixMillis: Long, minLevel: String): List<LogLine> = emptyList()
+            override fun recentLogs(
+                sinceUnixMillis: Long,
+                minLevel: String,
+            ): List<LogLine> = emptyList()
             override fun waitForIdle(durationMillis: Long) {}
             override fun healthy(): Boolean = true
-            override fun metrics(bundleId: String): MetricsSample = MetricsSample(0.0, 0L, 0L)
+            override fun metrics(bundleId: String): MetricsSample =
+                MetricsSample(0.0, 0L, 0L)
         }
         val client = newClient(backend)
 
@@ -252,13 +314,16 @@ class DriverServiceTest {
         val backend = StubDriverBackend("android")
         val client = newClient(backend)
 
-        client.eraseText(EraseTextRequest.newBuilder().setCharacterCount(11).build())
+        client.eraseText(
+            EraseTextRequest.newBuilder().setCharacterCount(11).build(),
+        )
         assertEquals(11, backend.lastEraseCharacterCount)
     }
 
     @Test fun screenshotReturnsBackendBytes() {
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun screenshot(): Triple<ByteArray, Int, Int> = Triple(byteArrayOf(1, 2, 3), 1080, 2340)
+            override fun screenshot(): Triple<ByteArray, Int, Int> =
+                Triple(byteArrayOf(1, 2, 3), 1080, 2340)
         }
         val client = newClient(backend)
 
@@ -268,9 +333,17 @@ class DriverServiceTest {
         assertEquals(3, image.png.size())
     }
 
-    @Test fun hierarchyReturnsBackendJson() {
+    // The runner reads the hierarchy a second time per step to see whether the
+    // screen changed while it was looking, so this has to answer with the tree
+    // the snapshot's read produces: same settle, same keyboard handling. Served
+    // off the bare backend read, the pair differs over what the backend did
+    // between the two reads rather than over what the app did. Measured on an
+    // API 34 emulator with an IME standing open, that is a 489-node tree
+    // against the snapshot's 134.
+    @Test fun hierarchyServesTheTreeTheSnapshotReads() {
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun hierarchy(): String = "{\"x\":1}"
+            override fun hierarchy(): String = "{\"bare\":1}"
+            override fun snapshotTree(): String = "{\"x\":1}"
         }
         val client = newClient(backend)
 
@@ -294,7 +367,13 @@ class DriverServiceTest {
     @Test fun swipeForwardsEndpointsAndDuration() {
         var observed: Quintuple<Int, Int, Int, Int, Long>? = null
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun swipe(fromX: Int, fromY: Int, toX: Int, toY: Int, durationMillis: Long) {
+            override fun swipe(
+                fromX: Int,
+                fromY: Int,
+                toX: Int,
+                toY: Int,
+                durationMillis: Long,
+            ) {
                 observed = Quintuple(fromX, fromY, toX, toY, durationMillis)
             }
         }
@@ -325,14 +404,18 @@ class DriverServiceTest {
 
     @Test fun recentLogsReturnsBackendEntries() {
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun recentLogs(sinceUnixMillis: Long, minLevel: String): List<LogLine> {
-                return listOf(LogLine(1, "E", "AndroidRuntime", "boom"))
-            }
+            override fun recentLogs(
+                sinceUnixMillis: Long,
+                minLevel: String,
+            ): List<LogLine> = listOf(LogLine(1, "E", "AndroidRuntime", "boom"))
         }
         val client = newClient(backend)
 
         val response = client.recentLogs(
-            RecentLogsRequest.newBuilder().setSinceUnixMillis(0).setLevelAtLeast("E").build(),
+            RecentLogsRequest.newBuilder()
+                .setSinceUnixMillis(0)
+                .setLevelAtLeast("E")
+                .build(),
         )
         assertEquals(1, response.entriesCount)
         assertEquals("AndroidRuntime", response.getEntries(0).tag)
@@ -351,7 +434,9 @@ class DriverServiceTest {
         }
         val client = newClient(backend)
 
-        client.launch(LaunchRequest.newBuilder().setBundleId("com.launched").build())
+        client.launch(
+            LaunchRequest.newBuilder().setBundleId("com.launched").build(),
+        )
         client.metrics(MetricsRequest.getDefaultInstance())
 
         assertEquals("com.launched", sampled)
@@ -367,8 +452,12 @@ class DriverServiceTest {
         }
         val client = newClient(backend)
 
-        client.launch(LaunchRequest.newBuilder().setBundleId("com.launched").build())
-        client.metrics(MetricsRequest.newBuilder().setBundleId("com.other").build())
+        client.launch(
+            LaunchRequest.newBuilder().setBundleId("com.launched").build(),
+        )
+        client.metrics(
+            MetricsRequest.newBuilder().setBundleId("com.other").build(),
+        )
 
         assertEquals("com.other", sampled)
     }

sidecar/src/test/kotlin/dev/sanderling/sidecar/EraseTextTest.kt

@@ -0,0 +1,128 @@
+package dev.sanderling.sidecar
+
+import org.junit.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class EraseTextTest {
+
+    // maestro's eraseText sends one delete per character through its
+    // instrumentation, measured at 29.6 ms/char on the API 34 emulator: the
+    // 4096-character string the corpus types cost ~121s to clear, a fifth of a
+    // 20 minute run for one step. Selecting the field and deleting the
+    // selection is the same two key events whatever the field holds.
+    @Test fun aClearedFieldCostsTwoKeyEventsWhateverItsLength() {
+        for (length in listOf(1, 21, 512, 4096)) {
+            val sent = mutableListOf<String>()
+            eraseFocusedField(length, { sent.add(it) }) { 0 }
+            assertEquals(
+                listOf(SELECT_ALL_COMMAND, DELETE_KEY_COMMAND),
+                sent,
+                "length $length must not scale the erase",
+            )
+        }
+    }
+
+    // The dangerous failure is a fast erase that leaves characters behind: the
+    // next InputText appends to the residue and every reading downstream is
+    // wrong with nothing to catch it. A field the select-all did not clear is
+    // finished off per character rather than assumed empty.
+    @Test fun aFieldTheSelectAllMissedIsFinishedOffPerCharacter() {
+        val sent = mutableListOf<String>()
+        eraseFocusedField(4096, { sent.add(it) }) { 4096 }
+
+        assertEquals(SELECT_ALL_COMMAND, sent.first())
+        assertEquals(DELETE_KEY_COMMAND, sent[1])
+        assertEquals(
+            4096,
+            sent.drop(2).sumOf { command ->
+                command.removePrefix("input keyevent ").split(" ").size
+            },
+            "every character must still be deleted",
+        )
+    }
+
+    // Unknown is not empty. A tree that cannot name the focused field is no
+    // evidence the erase worked, and the safe way to be wrong is the delete
+    // that costs time rather than the one that leaves residue.
+    @Test fun aFieldThatCannotBeReadIsFinishedOffRatherThanAssumedEmpty() {
+        val sent = mutableListOf<String>()
+        eraseFocusedField(8, { sent.add(it) }) { null }
+        assertTrue(sent.size > 2, "an unverified erase must not stop at two")
+    }
+
+    @Test fun nothingToEraseIssuesNoKeysAtAll() {
+        val sent = mutableListOf<String>()
+        eraseFocusedField(0, { sent.add(it) }) { 0 }
+        eraseFocusedField(-1, { sent.add(it) }) { 0 }
+        assertEquals(emptyList(), sent)
+    }
+
+    // Batching is what keeps the fallback affordable: one round trip per batch
+    // rather than one per character, measured 2.3 ms/char against maestro's
+    // 29.6. The count must survive the batching exactly.
+    @Test fun deleteKeyCommandsBatchesWithoutLosingACharacter() {
+        for (count in listOf(1, 199, 200, 201, 4096)) {
+            val commands = deleteKeyCommands(count, DELETE_BATCH_KEYS)
+            val keys = commands.flatMap {
+                it.removePrefix("input keyevent ").split(" ")
+            }
+            assertEquals(count, keys.size, "count $count")
+            assertTrue(keys.all { it == "67" }, "only KEYCODE_DEL")
+            assertTrue(
+                commands.size <= (count + DELETE_BATCH_KEYS - 1) /
+                    DELETE_BATCH_KEYS,
+                "count $count used ${commands.size} round trips",
+            )
+        }
+    }
+
+    // The erase targets the field the runner just tapped, so the length that
+    // decides whether it worked is that field's, not some other field that
+    // legitimately still holds text.
+    //
+    // The tree these fixtures copy is the one the device really returns, and
+    // it holds the trap: an open keyboard puts a SECOND focused node in the
+    // tree, one of the IME's own keys, and it carries no text. Reading the
+    // first focused node would call a field that still holds 4096 characters
+    // empty, which is the one wrong answer that matters here. maestro's tree
+    // also carries no "editable" attribute at all, so the text field has to be
+    // recognised by its class.
+    @Test fun theFocusedFieldIsReadPastTheKeyboardsOwnFocusedKey() {
+        assertEquals(4096, focusedEditableTextLength(TREE_WITH_FULL_FIELD))
+        assertEquals(0, focusedEditableTextLength(TREE_WITH_EMPTY_FIELD))
+    }
+
+    @Test fun aTreeWithNoFocusedFieldReadsAsUnknown() {
+        assertEquals(null, focusedEditableTextLength(TREE_WITH_NO_FOCUS))
+        assertEquals(null, focusedEditableTextLength(""))
+        assertEquals(null, focusedEditableTextLength("not json"))
+    }
+}
+
+// The keyboard's own focused key, exactly as the device reports it: focused,
+// no text, and not a text field.
+private val IME_FOCUSED_KEY =
+    """
+    {"attributes":{"text":"","resource-id":
+     "com.google.android.inputmethod.latin:id/key_pos_header_access",
+     "focused":"true","class":"android.widget.FrameLayout"},"children":[]}
+    """.trimIndent()
+
+private fun tree(focusedText: String?, otherText: String): String {
+    val field = focusedText?.let {
+        """,{"attributes":{"resource-id":"AccountNameField","focused":"true",
+           "class":"android.widget.EditText","text":"$it"},"children":[]}"""
+    } ?: ""
+    return """
+    {"attributes":{"resource-id":"AddAccountScreen"},"children":[
+      $IME_FOCUSED_KEY $field,
+      {"attributes":{"resource-id":"OtherField","focused":"false",
+       "class":"android.widget.EditText","text":"$otherText"},
+       "children":[]}]}
+    """.trimIndent()
+}
+
+private val TREE_WITH_FULL_FIELD = tree("a".repeat(4096), "keep me")
+private val TREE_WITH_EMPTY_FIELD = tree("", "keep me")
+private val TREE_WITH_NO_FOCUS = tree(null, "keep me")

sidecar/src/test/kotlin/dev/sanderling/sidecar/IdleDetectionTest.kt

@@ -21,11 +21,17 @@ class IdleDetectionTest {
         assertFalse(StubDriverBackend.isAnimationCountIdle("3\n"))
     }
 
-    @Test fun idleWhenOutputEmpty() {
-        assertTrue(StubDriverBackend.isAnimationCountIdle(""))
+    // A dumpsys that said nothing does not say the device is still. Reading
+    // absence as idle is how a settle returns instantly on a degraded link and
+    // hands the runner a screen caught mid-animation; the caller bounds its own
+    // wait, so the cost of being wrong the other way is a wait it already
+    // budgeted for. The exception path of the same probe already answers false.
+    @Test fun unreadableOutputIsNotIdle() {
+        assertFalse(StubDriverBackend.isAnimationCountIdle(""))
+        assertFalse(StubDriverBackend.isAnimationCountIdle("   \n"))
     }
 
-    @Test fun idleWhenOutputIsNotANumber() {
-        assertTrue(StubDriverBackend.isAnimationCountIdle("error: no service"))
+    @Test fun unparseableOutputIsNotIdle() {
+        assertFalse(StubDriverBackend.isAnimationCountIdle("error: no service"))
     }
 }

sidecar/src/test/kotlin/dev/sanderling/sidecar/InputTextTest.kt

@@ -32,7 +32,8 @@ class InputTextTest {
         val fallback = listOf(
             "Emergency Fund", "🙂🔥💸", "  ", "\t\n", "'; DROP TABLE--",
             "<script>alert(1)</script>", "../../etc/passwd", "%s%n", "",
-            "-1", "-rf", // a leading dash could be read as an option by `input text`
+            // a leading dash could be read as an option by `input text`
+            "-1", "-rf",
         )
         for (text in fallback) {
             assertTrue(
@@ -190,12 +191,12 @@ class InputTextTest {
 
     @Test fun parseResumedPackageReadsEachResumedActivityWording() {
         val cases = mapOf(
-            "    topResumedActivity=ActivityRecord{8b u0 app.folio/.MainActivity t42}" to
-                "app.folio",
-            "  mResumedActivity: ActivityRecord{1c u0 com.example.app/.Home t9}" to
-                "com.example.app",
-            "  ResumedActivity: ActivityRecord{2d u0 app.folio/com.folio.Detail t9}" to
-                "app.folio",
+            "    topResumedActivity=ActivityRecord{8b u0 " +
+                "app.folio/.MainActivity t42}" to "app.folio",
+            "  mResumedActivity: ActivityRecord{1c u0 " +
+                "com.example.app/.Home t9}" to "com.example.app",
+            "  ResumedActivity: ActivityRecord{2d u0 " +
+                "app.folio/com.folio.Detail t9}" to "app.folio",
         )
         for ((line, want) in cases) {
             assertEquals(want, parseResumedPackage(line), line)
@@ -206,10 +207,249 @@ class InputTextTest {
         )
     }
 
+    @Test fun aReadableDumpsysNamesTheResumedPackage() {
+        val warnings = mutableListOf<String>()
+        assertEquals(
+            "app.folio",
+            typingOwner(RESUMED_DUMPSYS, "app.folio") { warnings.add(it) },
+        )
+        assertTrue(warnings.isEmpty(), "nothing to report when the read worked")
+    }
+
+    // A dumpsys that said nothing is not evidence that focus is fine. Handing
+    // typeChunks a null owner turns the guard off outright, and the keystrokes
+    // then go wherever the foreground happens to be.
+    @Test fun anUnreadableDumpsysGuardsWithTheLaunchedBundle() {
+        val warnings = mutableListOf<String>()
+        assertEquals(
+            "app.folio",
+            typingOwner("", "app.folio") { warnings.add(it) },
+        )
+        assertEquals(1, warnings.size, "a degraded guard must not be silent")
+        assertTrue(warnings.single().contains("app.folio"), warnings.single())
+    }
+
+    // Wording no marker matches is the same "we do not know" as an empty read.
+    @Test fun dumpsysWithNoResumedMarkerGuardsWithTheLaunchedBundle() {
+        assertEquals(
+            "app.folio",
+            typingOwner("  mFocusedApp=null\n  nothing here\n", "app.folio") {},
+        )
+    }
+
+    // The whole point of the fallback: on a link that cannot answer, typing is
+    // still guarded, so a foreground that was stolen stops it after the first
+    // chunk instead of spraying the rest into whatever took focus.
+    @Test fun unreadableLinkStillStopsTypingWhenFocusWasStolen() {
+        val owner = typingOwner("", "app.folio") {}
+        val sent = mutableListOf<String>()
+
+        typeChunks(listOf("aaa", "bbb", "ccc"), owner, {
+            "com.android.launcher"
+        }) { sent.add(it) }
+
+        assertEquals(
+            listOf("aaa"),
+            sent,
+            "an unguarded type would have sent every chunk to the launcher",
+        )
+    }
+
+    // And the other half of the trade: the fallback must not turn a degraded
+    // link into a run that types nothing. A no-op InputText on every step is a
+    // green run that tested nothing, which is worse than the spray it avoids.
+    @Test fun unreadableLinkStillTypesWhenTheAppKeepsFocus() {
+        val owner = typingOwner("", "app.folio") {}
+        val sent = mutableListOf<String>()
+
+        val typed = typeChunks(listOf("aaa", "bbb", "cc"), owner, {
+            "app.folio"
+        }) { sent.add(it) }
+
+        assertEquals(listOf("aaa", "bbb", "cc"), sent)
+        assertEquals(8, typed)
+    }
+
+    // With no launch recorded there is nothing to guard against, and the honest
+    // answer is to say the guard is off rather than imply it ran.
+    @Test fun noLaunchedBundleLeavesTheGuardOffAndSaysSo() {
+        val warnings = mutableListOf<String>()
+        assertEquals(null, typingOwner("", null) { warnings.add(it) })
+        assertEquals(1, warnings.size)
+    }
+
     @Test fun maestroKeyForResolvesAndRejects() {
         assertEquals(maestro.KeyCode.BACK, maestroKeyFor("back"))
         assertEquals(maestro.KeyCode.BACK, maestroKeyFor("BACK"))
         assertEquals(maestro.KeyCode.ENTER, maestroKeyFor("enter"))
         assertFailsWith<IllegalArgumentException> { maestroKeyFor("zorp") }
     }
+
+    // An IME left open hides every app node beneath it from the hierarchy, so a
+    // form whose submit button sits under the keyboard becomes unreachable for
+    // as long as the fuzzer keeps typing into it. Typing must close the
+    // keyboard it raised.
+    @Test fun dismissSoftKeyboardClosesAnOpenIme() {
+        val commands = mutableListOf<String>()
+        dismissSoftKeyboard {
+            commands.add(it)
+            IME_OPEN_DUMPSYS
+        }
+        assertEquals(
+            listOf("dumpsys input_method", "input keyevent 4"),
+            commands,
+        )
+    }
+
+    // The guard is the dangerous half: BACK is only swallowed by an open IME,
+    // so dismissing unconditionally would turn every InputText into a back
+    // press and walk the fuzzer straight out of the screen it was filling in.
+    @Test fun dismissSoftKeyboardSendsNoBackWhenNoImeIsOpen() {
+        val commands = mutableListOf<String>()
+        dismissSoftKeyboard {
+            commands.add(it)
+            IME_CLOSED_DUMPSYS
+        }
+        assertEquals(listOf("dumpsys input_method"), commands)
+    }
+
+    // Typing is not the only thing that raises the keyboard: tapping a field
+    // raises it too, and nothing was closing that one. The snapshot the picker
+    // chooses from is missing every app node the keyboard covers, so the step
+    // spends its budget choosing between the few targets left. Closing it
+    // before the tree is read is what gives the step its targets back.
+    @Test fun aKeyboardInTheTreeIsClosedBeforeTheTreeIsReturned() {
+        var backs = 0
+        val reads = mutableListOf<String>()
+        val settled = treeWithoutKeyboard(
+            IME_TREE,
+            IME_PACKAGE,
+            dismiss = { backs++ },
+            reread = { APP_TREE.also { reads.add(it) } },
+            sleep = {},
+        )
+        assertEquals(APP_TREE, settled)
+        assertEquals(1, backs, "one BACK closes the keyboard")
+        assertEquals(1, reads.size, "the tree is re-read once it is gone")
+    }
+
+    // The guard has to be the tree itself. BACK with no keyboard open
+    // navigates out of the screen, so a snapshot that pressed it on every read
+    // would walk the fuzzer backwards out of the app a step at a time.
+    @Test fun aTreeWithNoKeyboardIsReturnedUntouched() {
+        var backs = 0
+        var reads = 0
+        val settled = treeWithoutKeyboard(
+            APP_TREE,
+            IME_PACKAGE,
+            dismiss = { backs++ },
+            reread = {
+                reads++
+                APP_TREE
+            },
+            sleep = {},
+        )
+        assertEquals(APP_TREE, settled)
+        assertEquals(0, backs, "no keyboard in the tree means no BACK")
+        assertEquals(0, reads, "and no second hierarchy read to pay for")
+    }
+
+    // An unknown IME package is the honest "cannot tell", and the safe way to
+    // be wrong is to leave the keyboard up rather than press BACK blind.
+    @Test fun anUnknownImePackageSendsNoBack() {
+        var backs = 0
+        assertEquals(
+            IME_TREE,
+            treeWithoutKeyboard(
+                IME_TREE,
+                null,
+                dismiss = { backs++ },
+                reread = { APP_TREE },
+                sleep = {},
+            ),
+        )
+        assertEquals(0, backs)
+    }
+
+    // A keyboard the app puts straight back gets ONE back press, not one per
+    // re-read. The flag behind the older dismissal lags a BACK by up to 0.6s,
+    // and a burst of them inside that window is how a dismissal turns into
+    // navigation.
+    @Test fun aKeyboardThatStaysUpIsNotBackPressedRepeatedly() {
+        var backs = 0
+        var reads = 0
+        val settled = treeWithoutKeyboard(
+            IME_TREE,
+            IME_PACKAGE,
+            dismiss = { backs++ },
+            reread = {
+                reads++
+                IME_TREE
+            },
+            sleep = {},
+        )
+        assertEquals(IME_TREE, settled, "the caller still gets a tree")
+        assertEquals(1, backs)
+        assertTrue(
+            reads in 1..KEYBOARD_DISMISS_READS,
+            "bounded re-reads, got $reads",
+        )
+    }
+
+    @Test fun imePackageOfReadsTheComponentAndRejectsNonsense() {
+        assertEquals(
+            "com.google.android.inputmethod.latin",
+            imePackageOf(
+                "com.google.android.inputmethod.latin/.LatinIME\n",
+            ),
+        )
+        assertEquals(null, imePackageOf("null"))
+        assertEquals(null, imePackageOf(""))
+        assertEquals(null, imePackageOf("  \n"))
+    }
+
+    @Test fun treeShowsImeMatchesTheImesOwnViewIdsOnly() {
+        assertTrue(treeShowsIme(IME_TREE, IME_PACKAGE))
+        assertTrue(!treeShowsIme(APP_TREE, IME_PACKAGE))
+    }
 }
+
+private val RESUMED_DUMPSYS =
+    """
+      mFocusedApp=ActivityRecord{1a u0 app.folio/.MainActivity t14}
+      topResumedActivity=ActivityRecord{f3 u0 app.folio/.MainActivity t14}
+    """.trimIndent()
+
+private const val IME_PACKAGE = "com.google.android.inputmethod.latin"
+
+private val APP_TREE =
+    """
+    {"attributes":{"resource-id":"AddAccountScreen"},"children":[
+      {"attributes":{"resource-id":"AccountNameField"},"children":[]},
+      {"attributes":{"resource-id":"AddAccountSubmit"},"children":[]}]}
+    """.trimIndent()
+
+// The submit control is gone: an open keyboard does not merely cover the node,
+// it takes it out of the tree the picker enumerates.
+private val IME_TREE =
+    """
+    {"attributes":{"resource-id":"AddAccountScreen"},"children":[
+      {"attributes":{"resource-id":"AccountNameField"},"children":[]},
+      {"attributes":{
+        "resource-id":"com.google.android.inputmethod.latin:id/keyboard_holder"
+      },"children":[]}]}
+    """.trimIndent()
+
+private val IME_OPEN_DUMPSYS =
+    """
+      mCurMethodId=com.google.android.inputmethod.latin/.LatinIME
+      mInputShown=true
+      mSystemReady=true mInteractive=true
+    """.trimIndent()
+
+private val IME_CLOSED_DUMPSYS =
+    """
+      mCurMethodId=com.google.android.inputmethod.latin/.LatinIME
+      mInputShown=false
+      mSystemReady=true mInteractive=true
+    """.trimIndent()

sidecar/src/test/kotlin/dev/sanderling/sidecar/ResolveActivityTest.kt

@@ -12,28 +12,40 @@ class ResolveActivityTest {
             com.example.app/.MainActivity
         """.trimIndent()
 
-        val activity = StubDriverBackend.parseResolvedActivity("com.example.app", output)
+        val activity = StubDriverBackend.parseResolvedActivity(
+            "com.example.app",
+            output,
+        )
         assertEquals(".MainActivity", activity)
     }
 
     @Test fun extractsFullyQualifiedActivity() {
         val output = "com.example.app/com.example.app.ui.LaunchActivity"
 
-        val activity = StubDriverBackend.parseResolvedActivity("com.example.app", output)
+        val activity = StubDriverBackend.parseResolvedActivity(
+            "com.example.app",
+            output,
+        )
         assertEquals("com.example.app.ui.LaunchActivity", activity)
     }
 
     @Test fun returnsNullWhenPackageNotFound() {
         val output = "No activity found"
 
-        val activity = StubDriverBackend.parseResolvedActivity("com.example.app", output)
+        val activity = StubDriverBackend.parseResolvedActivity(
+            "com.example.app",
+            output,
+        )
         assertNull(activity)
     }
 
     @Test fun doesNotMatchDifferentPackagePrefix() {
         val output = "other.pkg/.MainActivity"
 
-        val activity = StubDriverBackend.parseResolvedActivity("com.example.app", output)
+        val activity = StubDriverBackend.parseResolvedActivity(
+            "com.example.app",
+            output,
+        )
         assertNull(activity)
     }
 }

sidecar/src/test/kotlin/dev/sanderling/sidecar/RouteTransitionTest.kt

@@ -13,10 +13,13 @@ class RouteTransitionTest {
     private fun screen(id: String, child: String = "") =
         """{"attributes":{"resource-id":"$id"},"children":[$child]}"""
 
-    private fun tree(vararg children: String) =
-        """{"attributes":{"resource-id":"root"},"children":[${children.joinToString(",")}]}"""
+    private fun tree(vararg children: String): String {
+        val joined = children.joinToString(",")
+        return """{"attributes":{"resource-id":"root"},"children":[$joined]}"""
+    }
 
-    private val crossFade = tree(screen("LedgerScreen"), screen("AddTransactionScreen"))
+    private val crossFade =
+        tree(screen("LedgerScreen"), screen("AddTransactionScreen"))
     private val landed = tree(screen("AddTransactionScreen"))
 
     @Test fun waitsForTheCrossFadeToLandAndReturnsTheLandedTree() {
@@ -29,8 +32,15 @@ class RouteTransitionTest {
             reads++
             if (reads <= 3) crossFade else landed
         }
-        assertTrue(reads > 3, "must keep reading until the fade lands, reads=$reads")
-        assertEquals(1, countRouteScreens(settled), "must return a tree with one route")
+        assertTrue(
+            reads > 3,
+            "must keep reading until the fade lands, reads=$reads",
+        )
+        assertEquals(
+            1,
+            countRouteScreens(settled),
+            "must return a tree with one route",
+        )
     }
 
     @Test fun settledFrameCostsExactlyOneRead() {
@@ -54,13 +64,21 @@ class RouteTransitionTest {
         // would burn the whole poll budget and still hand over a frame the
         // runner refuses to act on.
         val nested = tree(screen("HomeScreen", screen("HomeScreen")))
-        assertEquals(1, countRouteScreens(nested), "the same id twice is one route")
+        assertEquals(
+            1,
+            countRouteScreens(nested),
+            "the same id twice is one route",
+        )
         var reads = 0
         awaitSettledTree {
             reads++
             nested
         }
-        assertEquals(1, reads, "a repeated route id must not be treated as a transition")
+        assertEquals(
+            1,
+            reads,
+            "a repeated route id must not be treated as a transition",
+        )
     }
 
     @Test fun aLayoutThatKeepsTwoRoutesIsBoundedByTheCap() {
@@ -78,7 +96,11 @@ class RouteTransitionTest {
             elapsed < TRANSITION_POLL_CAP_MILLIS + 1000L,
             "must stop at the cap, elapsed=${elapsed}ms",
         )
-        assertEquals(crossFade, settled, "the caller still gets a tree to record")
+        assertEquals(
+            crossFade,
+            settled,
+            "the caller still gets a tree to record",
+        )
     }
 
     @Test fun capCoversTheNavHostFadePlusTheStreak() {
@@ -89,20 +111,29 @@ class RouteTransitionTest {
         val fadeMillis = 700L
         val start = System.currentTimeMillis()
         val settled = awaitSettledTree {
-            if (System.currentTimeMillis() - start < fadeMillis) crossFade else landed
+            if (System.currentTimeMillis() - start < fadeMillis) {
+                crossFade
+            } else {
+                landed
+            }
         }
         val elapsed = System.currentTimeMillis() - start
 
-        assertEquals(landed, settled, "must hand back the landed tree, not the fade")
+        assertEquals(
+            landed,
+            settled,
+            "must hand back the landed tree, not the fade",
+        )
         assertTrue(
             elapsed >= fadeMillis,
             "cannot have settled before the fade ended, elapsed=${elapsed}ms",
         )
         assertTrue(
             elapsed < TRANSITION_POLL_CAP_MILLIS,
-            "the ${TRANSITION_POLL_CAP_MILLIS}ms cap has to leave room for a ${fadeMillis}ms " +
-                "fade and the ${TRANSITION_STABLE_STREAK_MILLIS}ms streak after it, but the " +
-                "wait ran to the cap instead, elapsed=${elapsed}ms",
+            "the ${TRANSITION_POLL_CAP_MILLIS}ms cap has to leave room for " +
+                "a ${fadeMillis}ms fade and the " +
+                "${TRANSITION_STABLE_STREAK_MILLIS}ms streak after it, but " +
+                "the wait ran to the cap instead, elapsed=${elapsed}ms",
         )
     }
 }

sidecar/src/test/kotlin/dev/sanderling/sidecar/SidecarServerTest.kt

@@ -6,7 +6,10 @@ import kotlin.test.assertTrue
 class SidecarServerTest {
     @Test
     fun startBindsEphemeralPortAndStopReleasesIt() {
-        val server = SidecarServer(port = 0, service = DriverService(backend = StubDriverBackend("android")))
+        val server = SidecarServer(
+            port = 0,
+            service = DriverService(backend = StubDriverBackend("android")),
+        )
         val boundPort = server.start()
         try {
             assertTrue(boundPort > 0, "expected ephemeral port, got $boundPort")

sidecar/src/test/kotlin/dev/sanderling/sidecar/SnapshotHandlerTest.kt

@@ -19,14 +19,22 @@ class SnapshotHandlerTest {
 
     @get:Rule val grpcCleanup: GrpcCleanupRule = GrpcCleanupRule()
 
-    private fun newClient(backend: DriverBackend): DriverGrpc.DriverBlockingStub {
+    private fun newClient(
+        backend: DriverBackend,
+    ): DriverGrpc.DriverBlockingStub {
         val serverName = InProcessServerBuilder.generateName()
         val service = DriverService(platform = "android", backend = backend)
         grpcCleanup.register(
-            InProcessServerBuilder.forName(serverName).directExecutor().addService(service).build().start(),
+            InProcessServerBuilder.forName(serverName)
+                .directExecutor()
+                .addService(service)
+                .build()
+                .start(),
         )
         val channel: ManagedChannel = grpcCleanup.register(
-            InProcessChannelBuilder.forName(serverName).directExecutor().build(),
+            InProcessChannelBuilder.forName(serverName)
+                .directExecutor()
+                .build(),
         )
         return DriverGrpc.newBlockingStub(channel)
     }
@@ -37,8 +45,10 @@ class SnapshotHandlerTest {
         // forward those calls to the delegate, not these overrides. Override
         // snapshot() directly so the test exercises the wire path end-to-end.
         val backend = object : DriverBackend by StubDriverBackend("android") {
-            override fun snapshot(): SnapshotSample =
-                SnapshotSample("{\"x\":1}", Triple(byteArrayOf(7, 8, 9), 1080, 2340))
+            override fun snapshot(): SnapshotSample = SnapshotSample(
+                "{\"x\":1}",
+                Triple(byteArrayOf(7, 8, 9), 1080, 2340),
+            )
         }
         val client = newClient(backend)
 
@@ -55,13 +65,23 @@ class SnapshotHandlerTest {
         // aligned with the final hierarchy snapshot the runner accepts.
         val callOrder = mutableListOf<String>()
         val backend = object : DriverBackend {
-            override fun launch(bundleId: String, clearState: Boolean, env: Map<String, String>) {}
+            override fun launch(
+                bundleId: String,
+                clearState: Boolean,
+                env: Map<String, String>,
+            ) {}
             override fun terminate(bundleId: String) {}
             override fun tap(x: Int, y: Int) {}
             override fun tapSelector(selector: String) {}
             override fun inputText(text: String) {}
             override fun eraseText(characterCount: Int) {}
-            override fun swipe(fromX: Int, fromY: Int, toX: Int, toY: Int, durationMillis: Long) {}
+            override fun swipe(
+                fromX: Int,
+                fromY: Int,
+                toX: Int,
+                toY: Int,
+                durationMillis: Long,
+            ) {}
             override fun pressKey(key: String) {}
             override fun longPress(x: Int, y: Int) {}
             override fun screenshot(): Triple<ByteArray, Int, Int> {
@@ -72,10 +92,14 @@ class SnapshotHandlerTest {
                 callOrder.add("hierarchy")
                 return "{}"
             }
-            override fun recentLogs(sinceUnixMillis: Long, minLevel: String): List<LogLine> = emptyList()
+            override fun recentLogs(
+                sinceUnixMillis: Long,
+                minLevel: String,
+            ): List<LogLine> = emptyList()
             override fun waitForIdle(durationMillis: Long) {}
             override fun healthy(): Boolean = true
-            override fun metrics(bundleId: String): MetricsSample = MetricsSample(0.0, 0L, 0L)
+            override fun metrics(bundleId: String): MetricsSample =
+                MetricsSample(0.0, 0L, 0L)
         }
         backend.snapshot()
         assertEquals(listOf("hierarchy", "screenshot"), callOrder)
@@ -88,7 +112,8 @@ class SnapshotHandlerTest {
         val maxObserved = AtomicInteger(0)
         val callCount = AtomicInteger(0)
         val lock = ReentrantLock()
-        val recordingBackend = object : DriverBackend by StubDriverBackend("android") {
+        val delegate = StubDriverBackend("android")
+        val recordingBackend = object : DriverBackend by delegate {
             override fun snapshot(): SnapshotSample {
                 val now = inFlight.incrementAndGet()
                 try {
@@ -109,9 +134,13 @@ class SnapshotHandlerTest {
         // Use a real (multi-threaded) executor on the server side so the service
         // is not artificially serialized by directExecutor.
         val serverName = InProcessServerBuilder.generateName()
-        val service = DriverService(platform = "android", backend = recordingBackend)
+        val service =
+            DriverService(platform = "android", backend = recordingBackend)
         grpcCleanup.register(
-            InProcessServerBuilder.forName(serverName).addService(service).build().start(),
+            InProcessServerBuilder.forName(serverName)
+                .addService(service)
+                .build()
+                .start(),
         )
         val channel: ManagedChannel = grpcCleanup.register(
             InProcessChannelBuilder.forName(serverName).build(),

sidecar/src/test/kotlin/dev/sanderling/sidecar/StabilityPollTest.kt

@@ -13,7 +13,10 @@ class StabilityPollTest {
             elapsed >= MIN_STABLE_STREAK_MILLIS,
             "must observe a stable streak of at least ${MIN_STABLE_STREAK_MILLIS}ms, elapsed=${elapsed}ms",
         )
-        assertTrue(elapsed < 3000L, "should not run to cap when stable, elapsed=${elapsed}ms")
+        assertTrue(
+            elapsed < 3000L,
+            "should not run to cap when stable, elapsed=${elapsed}ms",
+        )
     }
 
     @Test fun slowSnapshotReadsDoNotEatTheStreak() {
@@ -38,8 +41,9 @@ class StabilityPollTest {
         val observedQuiet = sampleStarts.last() - sampleEnds.first()
         assertTrue(
             observedQuiet >= MIN_STABLE_STREAK_MILLIS,
-            "the poll returned having observed only ${observedQuiet}ms of quiet, not " +
-                "${MIN_STABLE_STREAK_MILLIS}ms; starts=$sampleStarts ends=$sampleEnds",
+            "the poll returned having observed only ${observedQuiet}ms of " +
+                "quiet, not ${MIN_STABLE_STREAK_MILLIS}ms; " +
+                "starts=$sampleStarts ends=$sampleEnds",
         )
         assertTrue(
             sampleStarts.size >= 3,
@@ -60,23 +64,27 @@ class StabilityPollTest {
             calls++
             when {
                 calls <= 2 -> "calm"
+
                 calls == 3 -> {
                     transientAt = System.currentTimeMillis()
                     "transient"
                 }
+
                 else -> "stable"
             }
         }
         val sinceTransition = System.currentTimeMillis() - transientAt
         assertTrue(
             calls >= 8,
-            "after the transition the poll needs a fresh matching pair and then a full " +
-                "${MIN_STABLE_STREAK_MILLIS}ms of quiet, which is 8 samples, got $calls",
+            "after the transition the poll needs a fresh matching pair and " +
+                "then a full ${MIN_STABLE_STREAK_MILLIS}ms of quiet, which " +
+                "is 8 samples, got $calls",
         )
         assertTrue(
             sinceTransition >= MIN_STABLE_STREAK_MILLIS,
-            "the calm prefix must not count: a full ${MIN_STABLE_STREAK_MILLIS}ms streak has to " +
-                "start over after the transition, returned ${sinceTransition}ms after it",
+            "the calm prefix must not count: a full " +
+                "${MIN_STABLE_STREAK_MILLIS}ms streak has to start over " +
+                "after the transition, returned ${sinceTransition}ms after it",
         )
     }
 
@@ -105,7 +113,10 @@ class StabilityPollTest {
             "frame-$calls"
         }
         val elapsed = System.currentTimeMillis() - start
-        assertTrue(elapsed in budget..(budget + 1000L), "expected to hit cap, elapsed=$elapsed")
+        assertTrue(
+            elapsed in budget..(budget + 1000L),
+            "expected to hit cap, elapsed=$elapsed",
+        )
     }
 
     @Test fun zeroBudgetReturnsImmediately() {
@@ -117,7 +128,8 @@ class StabilityPollTest {
         assertEquals(0, calls)
     }
 
-    @Test fun structuralHashIgnoresBoundsAndIdenticalForSemanticallyEqualTrees() {
+    @Test
+    fun structuralHashIgnoresBoundsAndIdenticalForSemanticallyEqualTrees() {
         val a = """
         {"attributes":{"resource-id":"LoginScreen","bounds":"[0,0,1080,2340]"},
          "children":[
@@ -130,13 +142,24 @@ class StabilityPollTest {
            {"attributes":{"resource-id":"LoginEmail","bounds":"[10,11,1070,101]","text":"a@b"},"children":[]}
          ]}
         """.trimIndent()
-        assertEquals(structuralHash(a), structuralHash(b), "bounds-only flicker must not change hash")
+        assertEquals(
+            structuralHash(a),
+            structuralHash(b),
+            "bounds-only flicker must not change hash",
+        )
     }
 
     @Test fun structuralHashDiffersWhenContentChanges() {
-        val a = """{"attributes":{"resource-id":"LoginEmail","text":"a@b"},"children":[]}"""
-        val b = """{"attributes":{"resource-id":"LoginEmail","text":"c@d"},"children":[]}"""
-        assertTrue(structuralHash(a) != structuralHash(b), "text change must alter hash")
+        val a = """
+        {"attributes":{"resource-id":"LoginEmail","text":"a@b"},"children":[]}
+        """.trimIndent()
+        val b = """
+        {"attributes":{"resource-id":"LoginEmail","text":"c@d"},"children":[]}
+        """.trimIndent()
+        assertTrue(
+            structuralHash(a) != structuralHash(b),
+            "text change must alter hash",
+        )
     }
 
     @Test fun stabilitySnapshotReturnsNullDuringNavHostCrossFade() {
@@ -160,7 +183,10 @@ class StabilityPollTest {
          ]}
         """.trimIndent()
         val hash = stabilitySnapshot(singleScreen)
-        assertTrue(hash != null && hash.isNotBlank(), "single-screen tree must yield a hash, got $hash")
+        assertTrue(
+            hash != null && hash.isNotBlank(),
+            "single-screen tree must yield a hash, got $hash",
+        )
     }
 
     @Test fun stabilitySnapshotIgnoresNonRouteAttributeValues() {
@@ -173,7 +199,10 @@ class StabilityPollTest {
            {"attributes":{"text":"Welcome to MyScreen"},"children":[]}
          ]}
         """.trimIndent()
-        assertTrue(stabilitySnapshot(tree) != null, "non-route attribute must not be counted as a screen")
+        assertTrue(
+            stabilitySnapshot(tree) != null,
+            "non-route attribute must not be counted as a screen",
+        )
     }
 
     @Test fun countRouteScreensCountsTestTagAndIdentifier() {

sidecar/src/test/kotlin/dev/sanderling/sidecar/WdaRecoveryTest.kt

@@ -12,14 +12,15 @@ import kotlin.test.assertTrue
 
 class WdaRecoveryTest {
 
-    private fun recovery(
-        isAlive: () -> Boolean,
-        restart: () -> Unit,
-    ) = WdaRecovery(isAlive = isAlive, restart = restart, log = {})
+    private fun recovery(isAlive: () -> Boolean, restart: () -> Unit) =
+        WdaRecovery(isAlive = isAlive, restart = restart, log = {})
 
     @Test fun aliveChannelSkipsRestartAndRetriesReads() {
         val restarts = AtomicInteger(0)
-        val recovery = recovery(isAlive = { true }, restart = { restarts.incrementAndGet() })
+        val recovery = recovery(
+            isAlive = { true },
+            restart = { restarts.incrementAndGet() },
+        )
         var calls = 0
 
         val result = recovery.run(replay = true) {
@@ -35,10 +36,15 @@ class WdaRecoveryTest {
 
     @Test fun aliveChannelSurfacesUnavailableForActions() {
         val restarts = AtomicInteger(0)
-        val recovery = recovery(isAlive = { true }, restart = { restarts.incrementAndGet() })
+        val recovery = recovery(
+            isAlive = { true },
+            restart = { restarts.incrementAndGet() },
+        )
 
         val thrown = assertFailsWith<io.grpc.StatusRuntimeException> {
-            recovery.run(replay = false) { throw IOException("connection reset") }
+            recovery.run(replay = false) {
+                throw IOException("connection reset")
+            }
         }
 
         assertEquals(io.grpc.Status.Code.UNAVAILABLE, thrown.status.code)
@@ -101,7 +107,9 @@ class WdaRecoveryTest {
         )
 
         val thrown = assertFailsWith<IllegalStateException> {
-            recovery.run(replay = true) { throw IOException("connection refused") }
+            recovery.run(replay = true) {
+                throw IOException("connection refused")
+            }
         }
 
         assertTrue(thrown.message.orEmpty().contains("WDA reconnect failed"))
@@ -116,7 +124,9 @@ class WdaRecoveryTest {
         )
 
         assertFailsWith<IllegalArgumentException> {
-            recovery.run(replay = true) { throw IllegalArgumentException("bad selector") }
+            recovery.run(replay = true) {
+                throw IllegalArgumentException("bad selector")
+            }
         }
 
         assertEquals(0, restarts.get())
@@ -127,7 +137,9 @@ class WdaRecoveryTest {
         val recovery = recovery(isAlive = { true }, restart = {})
 
         val thrown = assertFailsWith<io.grpc.StatusRuntimeException> {
-            recovery.run(replay = true) { throw IOException("connection reset") }
+            recovery.run(replay = true) {
+                throw IOException("connection reset")
+            }
         }
 
         assertEquals(io.grpc.Status.Code.UNAVAILABLE, thrown.status.code)