device-devtools-mcp 0.1.0

package/scripts/selftest.sh

@@ -0,0 +1,1709 @@
+#!/usr/bin/env bash
+# DeviceTools — self-test for the platform-neutral layer.
+#
+#   scripts/selftest.sh
+#
+# No device, no driver, no config beyond the one every script loads. It exercises
+# the parts of this tool that are pure decisions — path resolution, colour, the
+# tree filter, the geometry arithmetic — because those are the parts that fail
+# silently. A wrong rectangle produces a plausible number on every screen and
+# nobody notices for a month.
+#
+# WHY IT MATTERS THAT THIS NEEDS NO PHONE
+#
+# Everything else here is proven by driving a real device, which means it is
+# proven when somebody is sitting in front of one. This file runs anywhere, so
+# it is the only check that can catch a macOS-ism, a byte-vs-character bug in
+# awk, or a sign error in an overlap, on the day it is introduced.
+#
+# exit 0  every check passed
+# exit 5  at least one failed
+#
+# That 5 is this file's own, and is the one exception to the exit-code contract
+# every verb follows: a test runner reports how many checks failed, and a verb
+# reports what the screen did.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+FAILED=0
+
+# A SUITE THAT DIES HALFWAY MUST NOT LOOK LIKE A SUITE THAT PASSED.
+#
+# Everything here runs under `set -e`. A check that calls something undefined —
+# an adapter function, a renamed helper — aborts the script before the verdict
+# block, so nothing prints RESULT and the exit status is whatever the last
+# command left behind. Measured: a call to candidate_elements, which lives in an
+# adapter and not here, ended the run at check 130 of 140 with status 0.
+#
+# A hook rather than `trap ... EXIT`, because a second trap replaces the first
+# and lib.sh already owns that one.
+DT_REACHED_END=0
+selftest_verdict_guard() {
+  [ "$DT_REACHED_END" -eq 1 ] && return 0
+  printf 'RESULT FAIL neutral-layer selftest — stopped before the verdict, at the check after the last line above\n'
+  return 0
+}
+dt_cleanup_add_hook selftest_verdict_guard
+
+ok()   { printf 'OK   %s\n' "$1"; }
+bad()  { printf 'FAIL %s — %s\n' "$1" "$2"; FAILED=$((FAILED + 1)); }
+is()   { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1" "expected [$3], got [$2]"; fi; }
+# A predicate that must hold, and one that must not. Both take a command.
+holds()     { if "${@:2}" >/dev/null 2>&1; then ok "$1"; else bad "$1" "did not hold"; fi; }
+holds_not() { if "${@:2}" >/dev/null 2>&1; then bad "$1" "held when it should not"; else ok "$1"; fi; }
+
+# --- paths --------------------------------------------------------------------
+
+is "an absolute path is left alone"       "$(expand_path /tmp/x)"  "/tmp/x"
+is "a ~ path expands to home"             "$(expand_path '~/x')"   "$HOME/x"
+is "a relative path joins the project"    "$(expand_path x/y)"     "$DT_ROOT/x/y"
+holds "the tool and the project are both set" test -d "$DT_HOME/scripts"
+
+# --- colour -------------------------------------------------------------------
+#
+# The decision is made once, when lib.sh is sourced, so each case is its own
+# process. Testing it in-process would only re-read a variable already fixed.
+paint_in() { DEVICETOOLS_COLOR="$1" bash -c 'source "$0"; paint "$1"' "$DT_HOME/scripts/lib.sh" "$2"; }
+
+is "colour off leaves the line untouched" \
+   "$(paint_in never 'RESULT   PASS tests/a.yaml 6/6')" 'RESULT   PASS tests/a.yaml 6/6'
+case "$(paint_in always 'RESULT   PASS tests/a.yaml 6/6')" in
+  *$'\033['*) ok "colour on wraps the line in SGR codes" ;;
+  *) bad "colour on wraps the line in SGR codes" "no escape sequence" ;;
+esac
+# The quoted-word rule: a status word inside a name or a selector is the
+# product quoting, not asserting, and must not be painted.
+case "$(paint_in always 'STEP     OK 5 tap text:OK 2.9s')" in
+  *'text:'$'\033['*) bad "a status word inside a selector is not painted" "the selector was painted" ;;
+  *) ok "a status word inside a selector is not painted" ;;
+esac
+
+# --- cleanup ------------------------------------------------------------------
+#
+# One EXIT trap with a list, because a second `trap … EXIT` replaces the first.
+# That is how 401 return-code files came to be sitting in TMPDIR.
+
+t1="$(mktemp)"; t2="$(mktemp)"
+bash -c 'source "$0"; dt_cleanup_add "$1"; dt_cleanup_add "$2"; exit 0' \
+  "$DT_HOME/scripts/lib.sh" "$t1" "$t2"
+if [ -e "$t1" ] || [ -e "$t2" ]; then
+  bad "every registered path is removed at exit" "something survived"
+  rm -f "$t1" "$t2"
+else
+  ok "every registered path is removed at exit"
+fi
+
+# A DIRECTORY MUST NOT STOP THE LIST. `rm -f` on one fails, and under `set -e`
+# that used to abort the cleanup function before it reached the paths after it —
+# so a single registered directory silently leaked everything behind it, and the
+# script exited with the rm's status even though every check had passed.
+d1="$(mktemp -d)"; t3="$(mktemp)"
+bash -c 'source "$0"; dt_cleanup_add "$1"; dt_cleanup_add "$2"; exit 0' \
+  "$DT_HOME/scripts/lib.sh" "$d1" "$t3"
+rc=$?
+is "a registered directory does not change the exit code" "$rc" "0"
+if [ ! -e "$d1" ] && [ ! -e "$t3" ]; then
+  ok "a directory is removed, and does not strand what follows it"
+else
+  bad "a directory is removed, and does not strand what follows it" \
+      "left$( [ -e "$d1" ] && printf ' the directory')$( [ -e "$t3" ] && printf ' the file after it')"
+  rm -rf "$d1" "$t3"
+fi
+
+# The return-code file lib.sh registers for itself is the one that leaked.
+leftover="$(bash -c 'source "$0"; printf "%s" "$DT_RCFILE"' "$DT_HOME/scripts/lib.sh")"
+if [ -n "$leftover" ] && [ ! -e "$leftover" ]; then
+  ok "lib.sh does not leave its own temp file behind"
+else
+  bad "lib.sh does not leave its own temp file behind" "left $leftover"
+fi
+
+# --- the tree keeps unlabelled controls ---------------------------------------
+#
+# A real production app's welcome screen carries three buttons and no identifier,
+# label or value on any of them, so the old filter printed a tree with nothing
+# tappable in it. iOS was verified on that screen; Android could not be, because
+# every emulator screen tried had a label on everything clickable. So the
+# Android branch is exercised here instead, against its own tree.awk row format,
+# rather than left as a change nobody ever saw run.
+tree_awk_keeps() {
+  # depth|class|id|label|text|x|y|w|h|visible|enabled|password|clickable|hint
+  printf '%s\n' "$1" | awk -F'|' -v all=0 -v depth=-1 -v want="" '
+    $1 == "WINDOW" || $1 == "" { next }
+    {
+      vis = ($10 == 1)
+      if (all != 1 && !(vis && ($3 != "" || $4 != "" || $5 != "" || $13 == 1))) next
+      print $2
+    }'
+}
+is "an unlabelled clickable element survives the tree filter" \
+  "$(tree_awk_keeps '7|ImageButton||||10|20|30|40|1|1|0|1|')" "ImageButton"
+is "an unlabelled unclickable element is still filtered out" \
+  "$(tree_awk_keeps '7|View||||10|20|30|40|1|1|0|0|')" ""
+is "an invisible clickable element is still filtered out" \
+  "$(tree_awk_keeps '7|ImageButton||||10|20|30|40|0|1|0|1|')" ""
+
+# --- the uid store and the uid selector ----------------------------------------
+#
+# The rule under test: a uid resolves only when the element it was assigned to
+# is still exactly there. Not "something like it" — the fingerprint machinery
+# was deleted on purpose and this is not it coming back under another name.
+
+is "the uid store is called uids.tsv" "$(basename "$(uid_store)")" "uids.tsv"
+
+UIDFIX="$(mktemp -d)"
+dt_cleanup_add "$UIDFIX"
+export DEVICETOOLS_UID_STORE="$UIDFIX/uids.tsv"
+# Two empty fields in a row on purpose: the identifier and the value. Under a
+# tab separator bash `read` would collapse them and shift every later field
+# left, which is the bug this row shape exists to make impossible.
+printf '1|5|Button||Đăng nhập||24|612|327|50\n' > "$DEVICETOOLS_UID_STORE"
+
+# Stands in for the adapter. Every consumer of a uid goes through this one
+# function, so a stub here exercises the whole path without a phone.
+# Each case is its own process, because `die` signals the top-level shell by
+# design — that is what stops a failure inside $( ) being swallowed, and it is
+# documented at the top of lib.sh. A subshell around it would take this script
+# down with it, so a refusal has to be observed from outside.
+#
+# The adapter is stubbed in that process. Every consumer of a uid goes through
+# snapshot_rows, so one stub exercises the whole path without a phone.
+uid_try() {  # uid_try <selector> <rows> — prints KIND:VALUE, or exits non-zero
+  FAKE_ROWS="$2" bash -c '
+    source "$0"
+    snapshot_rows() { printf "%s\n" "$FAKE_ROWS"; }
+    parse_selector "$1"
+    printf "%s:%s" "$SEL_KIND" "$SEL_VALUE"
+  ' "$DT_HOME/scripts/lib.sh" "$1" 2>/dev/null
+}
+refuses() {  # refuses <name> <selector> <rows>
+  if uid_try "$2" "$3" >/dev/null 2>&1; then
+    bad "$1" "it resolved anyway"
+  else
+    ok "$1"
+  fi
+}
+
+HERE_ROWS='WINDOW|375|812|portrait
+5|2|1|Button||Đăng nhập||24|612|327|50|visible,enabled,actionable'
+
+is "a uid resolves to the centre of its element" \
+   "$(uid_try uid:1 "$HERE_ROWS")" "xy:187,637"
+
+# The label changed. That is a real change to the screen and the uid is stale.
+refuses "a uid whose element was renamed is refused" uid:1 'WINDOW|375|812|portrait
+5|2|1|Button||Sign in||24|612|327|50|visible,enabled,actionable'
+
+# The element moved. Same reasoning: a tap at the old centre would land on
+# whatever moved into that space.
+refuses "a uid whose element moved is refused" uid:1 'WINDOW|375|812|portrait
+5|2|1|Button||Đăng nhập||24|700|327|50|visible,enabled,actionable'
+
+# But it did not move by one point — that is the flooring, the same arithmetic
+# the geometry warnings allow for. Measured on a real iPhone: a navigation bar
+# reported 428x101 on one fetch and 428x44 on the next while the screen was
+# still settling, and a rule with no slack at all would make every uid stale at
+# random until an agent stopped trusting them.
+is "a uid whose element shifted one point still resolves" \
+   "$(uid_try uid:1 'WINDOW|375|812|portrait
+5|2|1|Button||Đăng nhập||25|613|327|50|visible,enabled,actionable')" "xy:187,637"
+
+# Three points is not the arithmetic.
+refuses "a uid whose element shifted past the tolerance is refused" uid:1 'WINDOW|375|812|portrait
+5|2|1|Button||Đăng nhập||28|612|327|50|visible,enabled,actionable'
+
+# Two identical elements where there was one. Ambiguity is refused here exactly
+# as it is everywhere else in this tool.
+refuses "a uid that now matches twice is refused" uid:1 'WINDOW|375|812|portrait
+5|2|1|Button||Đăng nhập||24|612|327|50|visible,enabled,actionable
+6|2|1|Button||Đăng nhập||24|612|327|50|visible,enabled,actionable'
+
+refuses "an unassigned uid is refused" uid:9 "$HERE_ROWS"
+
+# A bare integer is a uid; a bare word is a plain-string selector, which is what
+# somebody who can see the screen writes. The error message has advertised that
+# second rule since before it existed.
+is "a bare integer is a uid"              "$(uid_try 1 "$HERE_ROWS")"           "xy:187,637"
+is "a bare word is a plain-string match"  "$(uid_try 'Đăng nhập' "$HERE_ROWS")" "any:Đăng nhập"
+is "an explicit kind still wins"          "$(uid_try label:Đóng "$HERE_ROWS")"  "label:Đóng"
+
+unset DEVICETOOLS_UID_STORE
+
+# --- geometry warnings ---------------------------------------------------------
+#
+# Pure arithmetic over rectangles, and therefore the part most likely to be
+# quietly wrong: a sign error in an overlap produces a plausible number on every
+# screen and nobody notices for a month. Every rule gets a case with the numbers
+# chosen so the expected answer is checkable by hand.
+
+snap() {  # snap <all> <grep>, rows on stdin
+  awk -v ALL="$1" -v GREP="$2" -v MINHIT=44 -f "$DT_HOME/scripts/snapshot.awk"
+}
+
+W='WINDOW|375|812|portrait'
+ROOT='1|0|0|Other||||0|0|375|812|visible,enabled'
+
+# Two visible siblings whose rects overlap by 20pt horizontally.
+overlap_rows="$W
+$ROOT
+2|1|1|Button|||Alpha|10|100|100|40|visible,enabled,actionable
+3|1|1|Button|||Beta|90|100|100|40|visible,enabled,actionable"
+
+case "$(printf '%s\n' "$overlap_rows" | snap 0 '')" in
+  *'overlaps a sibling by 20pt — [2]'*) ok "an overlap is measured, not guessed" ;;
+  *) bad "an overlap is measured, not guessed" "$(printf '%s\n' "$overlap_rows" | snap 0 '' | tr '\n' ' ')" ;;
+esac
+
+# A one-point overlap is the arithmetic, not the app. Both drivers report
+# rectangles as floats and this pipeline floors them, so each edge carries up to
+# a point of error. Reporting that as a layout bug is how a warning becomes
+# something an agent skips: on a real, dense screen it fired twenty-three times
+# between lines of text that are visibly not touching.
+quantise_rows="$W
+$ROOT
+2|1|1|StaticText||Acme Demo||68|482|356|19|visible,enabled
+3|1|1|StaticText||NGUYEN VAN A||68|500|336|21|visible,enabled"
+
+case "$(printf '%s\n' "$quantise_rows" | snap 0 '')" in
+  *overlaps*) bad "a one-point overlap is not reported" "$(printf '%s\n' "$quantise_rows" | snap 0 '' | tr '\n' ' ')" ;;
+  *) ok "a one-point overlap is not reported" ;;
+esac
+
+# The same fault on six elements is one line with six numbers on it, not six
+# lines. A list screen otherwise produces the same warning once per row, and
+# forty-nine warnings is a screen nobody reads.
+group_rows="$W
+$ROOT
+2|1|1|Button|||A|0|100|20|20|visible,enabled,actionable
+3|1|1|Button|||B|0|200|20|20|visible,enabled,actionable
+4|1|1|Button|||C|0|300|20|20|visible,enabled,actionable"
+
+is "one fault on three elements is one line" \
+   "$(printf '%s\n' "$group_rows" | snap 0 '' | grep -c 'hit area')" "1"
+case "$(printf '%s\n' "$group_rows" | snap 0 '')" in
+  *'hit area below the 44pt minimum — [1] [2] [3]'*) ok "and it names every element it applies to" ;;
+  *) bad "and it names every element it applies to" "$(printf '%s\n' "$group_rows" | snap 0 '' | tr '\n' ' ')" ;;
+esac
+
+# A child sticking 30pt out of the right edge of its parent.
+outside_rows="$W
+$ROOT
+2|1|1|Other||||0|100|200|100|visible,enabled
+3|2|2|Button|||Gamma|150|100|80|40|visible,enabled,actionable"
+
+case "$(printf '%s\n' "$outside_rows" | snap 0 '')" in
+  *'outside its parent by 30pt — [1]'*) ok "a child escaping its parent is measured" ;;
+  *) bad "a child escaping its parent is measured" "$(printf '%s\n' "$outside_rows" | snap 0 '' | tr '\n' ' ')" ;;
+esac
+
+# A control 375 wide but only 20 tall — under the 44pt minimum.
+small_rows="$W
+$ROOT
+2|1|1|Button|||Tiny|0|100|375|20|visible,enabled,actionable"
+
+case "$(printf '%s\n' "$small_rows" | snap 0 '')" in
+  *'hit area below the 44pt minimum — [1]'*) ok "a hit area below the minimum is named" ;;
+  *) bad "a hit area below the minimum is named" "$(printf '%s\n' "$small_rows" | snap 0 '' | tr '\n' ' ')" ;;
+esac
+
+# A label the OS truncated. The ellipsis is the signal; a character count is not.
+ellip_rows="$W
+$ROOT
+2|1|1|StaticText||Tên người nhận đầy đủ…||24|200|180|20|visible,enabled"
+
+case "$(printf '%s\n' "$ellip_rows" | snap 0 '')" in
+  *'the OS truncated this text with an ellipsis — [1]'*) ok "an ellipsis is reported as truncation" ;;
+  *) bad "an ellipsis is reported as truncation" "$(printf '%s\n' "$ellip_rows" | snap 0 '' | tr '\n' ' ')" ;;
+esac
+
+# The same label without an ellipsis must produce no warning at all. A rule that
+# fires on everything is the same as no rule.
+plain_rows="$W
+$ROOT
+2|1|1|StaticText||Tên người nhận||24|200|180|20|visible,enabled"
+
+case "$(printf '%s\n' "$plain_rows" | snap 0 '')" in
+  *'⚠'*) bad "a text that fits produces no warning" "$(printf '%s\n' "$plain_rows" | snap 0 '' | tr '\n' ' ')" ;;
+  *) ok "a text that fits produces no warning" ;;
+esac
+
+# Off screen: y beyond the window height.
+off_rows="$W
+$ROOT
+2|1|1|Button|||Below|0|900|100|44|visible,enabled,actionable"
+
+case "$(printf '%s\n' "$off_rows" | snap 1 '')" in
+  *'off screen'*) ok "an element past the window edge is off screen" ;;
+  *) bad "an element past the window edge is off screen" "$(printf '%s\n' "$off_rows" | snap 1 '' | tr '\n' ' ')" ;;
+esac
+
+# The default filter: an invisible element with a label is noise and is dropped;
+# an unlabelled actionable element is kept, because a screen whose only controls
+# are unlabelled must not read as having nothing to tap.
+filter_rows="$W
+$ROOT
+2|1|1|StaticText||Hidden||0|100|100|20|enabled
+3|1|1|Button||||0|200|100|44|visible,enabled,actionable"
+
+filter_out="$(printf '%s\n' "$filter_rows" | snap 0 '')"
+case "$filter_out" in
+  *Hidden*) bad "an invisible labelled element is filtered out" "$filter_out" ;;
+  *) ok "an invisible labelled element is filtered out" ;;
+esac
+case "$filter_out" in
+  *Button*) ok "an unlabelled actionable element survives the filter" ;;
+  *) bad "an unlabelled actionable element survives the filter" "$filter_out" ;;
+esac
+case "$filter_out" in
+  *'[1]  Button'*) ok "uids number the shown elements from 1" ;;
+  *) bad "uids number the shown elements from 1" "$filter_out" ;;
+esac
+
+# The screen line carries a size, an orientation and a stable hash.
+head_line="$(printf '%s\n' "$filter_rows" | snap 0 '' | head -1)"
+case "$head_line" in
+  SCREEN*375x812*portrait*) ok "the screen line carries size and orientation" ;;
+  *) bad "the screen line carries size and orientation" "$head_line" ;;
+esac
+h1="$(printf '%s\n' "$filter_rows" | snap 0 '' | head -1 | grep -o '#[0-9a-f]*')"
+h2="$(printf '%s\n' "$filter_rows" | snap 0 '' | head -1 | grep -o '#[0-9a-f]*')"
+is "the screen hash is stable across runs" "$h1" "$h2"
+h3="$(printf '%s\n' "$plain_rows" | snap 0 '' | head -1 | grep -o '#[0-9a-f]*')"
+if [ "$h1" != "$h3" ]; then
+  ok "a different screen gets a different hash"
+else
+  bad "a different screen gets a different hash" "both were $h1"
+fi
+
+# Two Vietnamese labels differing only in their diacritics must not collide. A
+# hash that folds every non-ASCII byte to the same value would report two
+# different screens as one, and change detection would go quiet.
+viet_a="$W
+$ROOT
+2|1|1|StaticText||Đăng nhập||0|100|200|20|visible,enabled"
+viet_b="$W
+$ROOT
+2|1|1|StaticText||Đang nhắp||0|100|200|20|visible,enabled"
+ha="$(printf '%s\n' "$viet_a" | snap 0 '' | head -1 | grep -o '#[0-9a-f]*')"
+hb="$(printf '%s\n' "$viet_b" | snap 0 '' | head -1 | grep -o '#[0-9a-f]*')"
+if [ "$ha" != "$hb" ]; then
+  ok "labels differing only in diacritics hash differently"
+else
+  bad "labels differing only in diacritics hash differently" "both were $ha"
+fi
+
+# --- the session journal -------------------------------------------------------
+#
+# The journal exists for one reason: installing a new build puts the app back on
+# its first screen, and re-walking a long flow by hand costs more than the
+# code change did. It is a path, not a test — no assertions, no scoring.
+
+JFIX="$(mktemp -d)"
+dt_cleanup_add "$JFIX"
+export DEVICETOOLS_JOURNAL="$JFIX/session.jsonl"
+
+journal_append tap 'label:Đăng nhập' Button '' 'Đăng nhập' '' 24 612 327 50 a3f1
+is "one line is appended"   "$(wc -l < "$DEVICETOOLS_JOURNAL" | tr -d ' ')" "1"
+is "the verb is recorded"   "$(jq -r '.verb' "$DEVICETOOLS_JOURNAL")" "tap"
+is "the label survives"     "$(jq -r '.label' "$DEVICETOOLS_JOURNAL")" "Đăng nhập"
+is "the rectangle is numeric, not a string" \
+   "$(jq -r '.x | type' "$DEVICETOOLS_JOURNAL")" "number"
+is "the screen it happened on is stamped" \
+   "$(jq -r '.screen' "$DEVICETOOLS_JOURNAL")" "a3f1"
+
+journal_append back '' '' '' '' '' 0 0 0 0 b2c3
+is "it appends rather than replaces" "$(wc -l < "$DEVICETOOLS_JOURNAL" | tr -d ' ')" "2"
+
+# A label with a quote, a brace and a newline in it. Application copy is written
+# by people, and a journal that cannot survive it is a journal that loses a step
+# exactly when the flow is interesting.
+journal_append type 'Lê "Văn" A
+{}' TextField '' '' '' 1 2 3 4 c3d4
+is "quotes and newlines survive the round trip" \
+   "$(tail -1 "$DEVICETOOLS_JOURNAL" | jq -r '.args')" "$(printf 'Lê "Văn" A\n{}')"
+is "and every line is still valid JSON" \
+   "$(jq -s 'length' "$DEVICETOOLS_JOURNAL" 2>/dev/null)" "3"
+
+# An unwritable journal is a bad day, not a failed tap. The action already
+# happened on the device; failing the verb afterwards would tell the agent the
+# tap did not land, which is a lie it would act on.
+DEVICETOOLS_JOURNAL=/nonexistent-directory-here/session.jsonl
+if journal_append tap x Button '' y '' 1 2 3 4 z; then
+  ok "an unwritable journal does not fail the action"
+else
+  bad "an unwritable journal does not fail the action" "it returned non-zero"
+fi
+unset DEVICETOOLS_JOURNAL
+
+# --- the network filter --------------------------------------------------------
+#
+# There is no proxy here and there is not going to be one: the app under test
+# pins its certificates, so a proxy would see a handshake failure and nothing
+# else. What is left is the app's own logging, filtered — and the filter is a
+# regex, which is worth testing precisely because a pattern that matches
+# everything is the same as no filter at all.
+
+netfilter() {  # netfilter <line> [pattern]
+  awk -v pat="${2:-(GET|POST|PUT|PATCH|DELETE|HTTP/[0-9])}" '$0 ~ pat' <<< "$1"
+}
+
+is "a request line is kept" \
+   "$(netfilter 'POST /v1/auth/login 200 142ms')" 'POST /v1/auth/login 200 142ms'
+is "a response line is kept" \
+   "$(netfilter 'HTTP/1.1 401 Unauthorized')" 'HTTP/1.1 401 Unauthorized'
+is "an unrelated line is dropped" \
+   "$(netfilter 'ViewController viewDidLoad')" ''
+# The case that decides whether the pattern is uppercase or case-insensitive.
+is "a line merely containing the word get is dropped" \
+   "$(netfilter 'forgetting the cache')" ''
+# The real risk is not that the pattern is wrong — the cases above cover that.
+# It is that one adapter's default drifts from the other's, so the same app
+# behaves differently on the two platforms and nobody notices until somebody
+# compares two runs.
+adapter_default() {  # <logs.sh path>
+  grep -ho "cfg '.logs.network_pattern' '[^']*'" "$1" \
+    | sed "s/.*network_pattern' '//; s/'\$//"
+}
+is "both adapters default to the same network pattern" \
+   "$(adapter_default "$DT_HOME/scripts/ios/logs.sh")" \
+   "$(adapter_default "$DT_HOME/scripts/android/logs.sh")"
+
+# And the shipped example config must agree with them, or a project created from
+# it starts with a filter that behaves differently from the built-in default.
+is "config.example.json ships that same pattern" \
+   "$(jq -r '.logs.network_pattern // ""' "$DT_HOME/config.example.json")" \
+   "$(adapter_default "$DT_HOME/scripts/ios/logs.sh")"
+
+# The strict pattern exists because of a real line from a real phone. Keeping
+# the case here means the reason survives the next person who simplifies it.
+is "a bluetooth identifier containing GET is not a request" \
+   "$(netfilter 'Sending: BD_VSC_OLYMPIC_GET_EXT_ADV_DROPPED' \
+                "$(adapter_default "$DT_HOME/scripts/ios/logs.sh")")" ''
+is "a real request survives the strict pattern" \
+   "$(netfilter 'DemoApp[75729] GET https://api.example.vn/accounts 200' \
+                "$(adapter_default "$DT_HOME/scripts/ios/logs.sh")")" \
+   'DemoApp[75729] GET https://api.example.vn/accounts 200'
+
+# --- the action report ---------------------------------------------------------
+#
+# The rule under test: an action says whether the screen moved. Getting this
+# backwards is the worst bug available in this file — an agent told the screen
+# changed when it did not will walk a long way off a cliff of its own reasoning
+# before anything contradicts it.
+
+act_in() {  # act_in <rows-before> <rows-after> [logs] — the report, as text
+  BEFORE="$1" AFTER="$2" FAKELOG="${3-}" bash -c '
+    source "$0"
+    snapshot_rows() { printf "%s\n" "$ROWS"; }
+    logs_since()    { printf "%s" "$FAKELOG"; }
+    ROWS="$BEFORE"; act_before
+    ROWS="$AFTER";  act_report TAP "[2] Button \"Đăng nhập\""
+  ' "$DT_HOME/scripts/lib.sh" 2>/dev/null
+}
+
+SCREEN_A='WINDOW|375|812|portrait
+1|0|0|Other||||0|0|375|812|visible,enabled
+2|1|1|Button||Đăng nhập||24|612|327|50|visible,enabled,actionable'
+SCREEN_B='WINDOW|375|812|portrait
+1|0|0|Other||||0|0|375|812|visible,enabled
+2|1|1|Button||Xác thực||24|612|327|50|visible,enabled,actionable'
+
+moved="$(act_in "$SCREEN_A" "$SCREEN_B")"
+same="$(act_in "$SCREEN_A" "$SCREEN_A")"
+
+case "$moved" in
+  *'SCREEN changed'*) ok "a screen that moved is reported as changed" ;;
+  *) bad "a screen that moved is reported as changed" "$(printf '%s' "$moved" | join_lines ' / ')" ;;
+esac
+case "$same" in
+  *'SCREEN unchanged'*) ok "a screen that did not move is reported as unchanged" ;;
+  *) bad "a screen that did not move is reported as unchanged" "$(printf '%s' "$same" | join_lines ' / ')" ;;
+esac
+case "$moved" in
+  *'TAP    [2] Button'*) ok "the action itself is on the first line" ;;
+  *) bad "the action itself is on the first line" "$(printf '%s' "$moved" | join_lines ' / ')" ;;
+esac
+case "$same" in
+  *LOG*) bad "no log lines means no LOG section" "$(printf '%s' "$same" | join_lines ' / ')" ;;
+  *) ok "no log lines means no LOG section" ;;
+esac
+
+withlog="$(act_in "$SCREEN_A" "$SCREEN_A" '[error] AuthService: token refresh failed')"
+case "$withlog" in
+  *'LOG    1 line'*'token refresh failed'*) ok "log lines from the action are attached" ;;
+  *) bad "log lines from the action are attached" "$(printf '%s' "$withlog" | join_lines ' / ')" ;;
+esac
+
+# A tree that cannot be read on either side must say so rather than claim the
+# screen held still. "unchanged" and "I could not look" are different facts.
+blind="$(act_in '' '')"
+case "$blind" in
+  *'SCREEN unknown'*) ok "an unreadable tree is not reported as unchanged" ;;
+  *) bad "an unreadable tree is not reported as unchanged" "$(printf '%s' "$blind" | join_lines ' / ')" ;;
+esac
+
+# --- an action can hand back the screen it produced ----------------------------
+#
+# The read–act–read cycle was half the round trips in a measured session:
+# twelve calls to log in and open Settings, six of them snapshots taken only to
+# see what the previous action produced. --snapshot folds that read into the
+# action, from the rows the report already fetched — one read of the phone, two
+# readings of it.
+
+act_snap_in() {  # act_snap_in <rows-before> <rows-after>
+  BEFORE="$1" AFTER="$2" bash -c '
+    source "$0"
+    snapshot_rows() { printf "%s\n" "$ROWS"; }
+    logs_since()    { printf ""; }
+    ROWS="$BEFORE"; act_before
+    act_snapshot_on
+    ROWS="$AFTER";  act_report TAP "[2] Button"
+  ' "$DT_HOME/scripts/lib.sh" 2>/dev/null
+}
+
+DEVICETOOLS_UID_STORE="$(mktemp)"; export DEVICETOOLS_UID_STORE
+snapped="$(act_snap_in "$SCREEN_A" "$SCREEN_B")"
+
+case "$snapped" in
+  *'SCREEN changed'*'[1]  Button "Xác thực"'*) ok "--snapshot prints the screen the action produced" ;;
+  *) bad "--snapshot prints the screen the action produced" "$(printf '%s' "$snapped" | join_lines ' / ')" ;;
+esac
+case "$(act_in "$SCREEN_A" "$SCREEN_B")" in
+  *'Button "Xác thực"'*) bad "without the flag an action still costs one line" "a tree was printed anyway" ;;
+  *) ok "without the flag an action still costs one line" ;;
+esac
+
+# THE NUMBERS HAVE TO BE THE NEW SCREEN'S. Printing a tree without renumbering
+# would be worse than printing nothing: every uid in it would resolve against
+# the screen before the action, which is the one failure the uid store exists to
+# prevent.
+is "the uid store is renumbered to what was printed" \
+   "$(awk -F'|' 'NR == 1 { print $3 "|" $5 }' "$DEVICETOOLS_UID_STORE" 2>/dev/null)" \
+   'Button|Xác thực'
+
+# An action whose screen cannot be read afterwards says so. The action itself
+# still happened, so it must not be reported as a failure.
+blindsnap="$(act_snap_in "$SCREEN_A" '')"
+case "$blindsnap" in
+  *'TREE   unavailable'*) ok "a tree that cannot be read says so instead of printing nothing" ;;
+  *) bad "a tree that cannot be read says so instead of printing nothing" "$(printf '%s' "$blindsnap" | join_lines ' / ')" ;;
+esac
+rm -f "$DEVICETOOLS_UID_STORE"
+unset DEVICETOOLS_UID_STORE
+
+# --- the identifier, on the line and in the lint -------------------------------
+#
+# --grep has always searched identifiers, so a screen could be found by a name
+# the display never printed. It is also the only selector that survives a
+# rewritten button or a second language, which makes it the thing anybody
+# writing a flow wants to see first.
+
+ID_ROWS='WINDOW|375|812|portrait
+1|0|0|Other||||0|0|375|812|visible,enabled
+2|1|1|Button|btn_login|Đăng nhập||24|600|327|50|visible,enabled,actionable
+3|1|1|Button|btn_bare|||24|500|327|50|visible,enabled,actionable
+4|1|1|Button||Quên mật khẩu||24|400|327|50|visible,enabled,actionable
+5|1|1|StaticText||Xin chào||24|300|327|50|visible,enabled
+6|1|1|Key||A||10|700|30|30|visible,enabled,actionable'
+
+id_out="$(printf '%s\n' "$ID_ROWS" | snap 0 '')"
+
+case "$id_out" in
+  *'Button #btn_login "Đăng nhập"'*) ok "an identifier is printed beside the label, not instead of it" ;;
+  *) bad "an identifier is printed beside the label, not instead of it" "$(printf '%s' "$id_out" | join_lines ' / ')" ;;
+esac
+# With no label, the identifier used to be printed in quotes by best()'s
+# fallback, which reads as a caption the app never wrote.
+case "$id_out" in
+  *'Button #btn_bare  ('*) ok "an identifier with no label is not dressed up as one" ;;
+  *) bad "an identifier with no label is not dressed up as one" "$(printf '%s' "$id_out" | join_lines ' / ')" ;;
+esac
+
+# A uid is a position among the elements SHOWN, not a row number: the root
+# container carries nothing and is filtered out, so the five rows below it are
+# [1] btn_login, [2] btn_bare, [3] Quên mật khẩu, [4] the static text, [5] the
+# keyboard key.
+id_warn="$(printf '%s\n' "$ID_ROWS" | snap 0 '' | grep 'no identifier' || true)"
+case "$id_warn" in
+  *'[3]'*) ok "an actionable control with no identifier is a lint" ;;
+  *) bad "an actionable control with no identifier is a lint" "${id_warn:-nothing warned}" ;;
+esac
+case "$id_warn" in
+  *'[1]'*|*'[2]'*) bad "a control that has an identifier is not linted" "$id_warn" ;;
+  *) ok "a control that has an identifier is not linted" ;;
+esac
+# Text nobody can tap needs no name to be tapped by.
+case "$id_warn" in
+  *'[4]'*) bad "text nobody can tap is not linted for a missing identifier" "$id_warn" ;;
+  *) ok "text nobody can tap is not linted for a missing identifier" ;;
+esac
+# The identifiers on a keyboard key belong to Apple, and telling an application
+# developer to add them is advice they cannot take.
+case "$id_warn" in
+  *'[5]'*) bad "the keyboard is not linted for missing identifiers" "$id_warn" ;;
+  *) ok "the keyboard is not linted for missing identifiers" ;;
+esac
+
+# --- kind:, and the selector grammar -------------------------------------------
+#
+# snapshot warns "no identifier" about a SecureTextField that also has no label,
+# and until now left nothing to reach it with but a raw coordinate — the one
+# spelling this tool tells people to avoid. It was right to: after the keyboard
+# went down, the sheet holding that field moved from y=507 to y=774 and the
+# recorded tap missed entirely.
+
+sel_kind() { bash -c 'source "$0"; parse_selector "$1"; printf "%s:%s" "$SEL_KIND" "$SEL_VALUE"' \
+             "$DT_HOME/scripts/lib.sh" "$1" 2>/dev/null; }
+is "kind: names the element class"  "$(sel_kind kind:SecureTextField)" "kind:SecureTextField"
+is "id: is unaffected"              "$(sel_kind id:btn_login)"         "id:btn_login"
+# A plain string still means "id, label or value" and must NOT quietly start
+# matching type names — `tap Button` would then hit the first button on screen.
+is "a plain string is not a type"   "$(sel_kind Button)"               "any:Button"
+
+# The adapter has to honour the new kind, or the grammar accepts a selector
+# nothing can resolve. Its own function, with the driver stubbed out.
+android_match() {  # android_match <tree rows> <kind> <value>
+  DEVICETOOLS_CONFIG="$DT_HOME/config.android.json" FAKE="$1" bash -c '
+    source "$0" 2>/dev/null
+    match_elements "$FAKE" "$1" "$2"
+  ' "$DT_HOME/scripts/android/lib.sh" "$2" "$3" 2>/dev/null
+}
+kind_rows='WINDOW|1080|2400
+0|FrameLayout||||0|0|1080|2400|1|1|0|0|0
+1|EditText||||64|400|300|60|1|1|0|1|0
+2|Button||Đăng nhập||64|600|300|60|1|1|0|1|0'
+is "the adapter matches on the element class" \
+   "$(android_match "$kind_rows" kind EditText)" '64|400|300|60|EditText|||'
+is "and a class that is not there matches nothing" \
+   "$(android_match "$kind_rows" kind SecureTextField)" ""
+
+# --- "nothing on screen contains it", when the screen did contain it -----------
+#
+# Reading and acting search different sets on purpose: snapshot walks the whole
+# tree, tap walks what a user could have touched. That is right, and the message
+# for the gap between them was wrong — `tap label:Cài đặt` answered "nothing on
+# screen contains it" while `snapshot --grep Cài đặt` was listing it. Reported
+# from a Control Wheel whose four buttons share one rectangle exactly: three of
+# them are covered, the driver marks those invisible, and invisible is not
+# absent.
+#
+# The adapter supplies named_anywhere; this is the sentence built from it, so
+# the adapter is stubbed and the wording is what is under test.
+note_for() {  # note_for <named_anywhere-output> <kind> <value>
+  ROW="$1" bash -c '
+    source "$0"
+    named_anywhere() { printf "%s\n" "$ROW"; }
+    invisible_note "" "$1" "$2"
+  ' "$DT_HOME/scripts/lib.sh" "$2" "$3" 2>/dev/null
+}
+
+case "$(note_for '64|127|300|300|Button|4|0' label 'Cài đặt')" in
+  *'Button at 64,127 300x300'*'4 elements share that rectangle'*)
+    ok "a covered twin is named as covered, not as missing" ;;
+  *) bad "a covered twin is named as covered, not as missing" \
+         "$(note_for '64|127|300|300|Button|4|0' label 'Cài đặt')" ;;
+esac
+case "$(note_for '24|612|327|50|Button|1|0' label 'Đăng nhập')" in
+  *'reports it as not visible'*) ok "one invisible element says so without inventing a twin" ;;
+  *) bad "one invisible element says so without inventing a twin" \
+         "$(note_for '24|612|327|50|Button|1|0' label 'Đăng nhập')" ;;
+esac
+# A zero-sized element is a different fault with a different remedy, and telling
+# somebody to scroll it into view would send them looking for a scroll view.
+case "$(note_for '10|20|0|0|StaticText|1|1' label 'Nhãn')" in
+  *'measures 0x0'*) ok "a zero-sized element is not blamed on being covered" ;;
+  *) bad "a zero-sized element is not blamed on being covered" \
+         "$(note_for '10|20|0|0|StaticText|1|1' label 'Nhãn')" ;;
+esac
+# Nothing named at all: say nothing, and let the caller fall through to the near
+# misses. A note here would be an explanation of something that is not the case.
+is "a selector that names nothing gets no note" "$(note_for '' label 'Nope')" ""
+
+# The adapter's own function, on the row shape it really reads.
+android_named() {  # android_named <tree rows> <kind> <value>
+  DEVICETOOLS_CONFIG="$DT_HOME/config.android.json" FAKE="$1" bash -c '
+    source "$0" 2>/dev/null
+    named_anywhere "$FAKE" "$1" "$2"
+  ' "$DT_HOME/scripts/android/lib.sh" "$2" "$3" 2>/dev/null
+}
+android_wheel='WINDOW|1080|2400
+0|FrameLayout||||0|0|1080|2400|1|1|0|0|0
+1|Button||Cài đặt||64|127|300|300|0|1|0|1|0
+2|Button||Trang chủ||64|127|300|300|1|1|0|1|0'
+is "the adapter counts the elements sharing that exact rectangle" \
+   "$(android_named "$android_wheel" label 'Cài đặt')" '64|127|300|300|Button|2|0'
+
+# --- the Android row shaping ---------------------------------------------------
+#
+# There was no Android device attached when snapshot_rows was written for that
+# platform, so there is no recorded screen for it. What can still be checked is
+# the part where the two adapters would diverge: turning tree.awk's fourteen
+# columns into the twelve every consumer reads.
+#
+# The adapter's own function is called, with the driver stubbed out. A copy of
+# the rule written here would pass this file happily while the adapter did
+# something else, which is the failure mode a test like this exists to prevent.
+#
+# Its own process, and its own config: sourcing an adapter replaces functions
+# this script is still using.
+android_shape() {  # <tree.awk rows> — the adapter's twelve-field output
+  DEVICETOOLS_CONFIG="$DT_HOME/config.android.json" FAKE="$1" bash -c '
+    source "$0" 2>/dev/null
+    fetch_source() { printf "%s\n" "$FAKE"; }
+    window_size()  { printf "1080 2400"; }
+    snapshot_rows
+  ' "$DT_HOME/scripts/android/lib.sh" 2>/dev/null
+}
+
+android_raw='WINDOW|1080|2400
+0|FrameLayout||||0|0|1080|2400|1|1|0|0|0
+1|LinearLayout||||0|100|1080|200|1|1|0|0|0
+2|Button|btn_login|Đăng nhập||24|120|300|150|1|1|0|1|0
+2|TextView||Quên mật khẩu|Quên mật khẩu|24|300|300|40|1|0|0|0|0'
+
+android_out="$(android_shape "$android_raw")"
+
+is "the window row carries an orientation" \
+   "$(printf '%s\n' "$android_out" | sed -n 1p)" 'WINDOW|1080|2400|portrait'
+is "clickable becomes actionable, and enabled survives" \
+   "$(printf '%s\n' "$android_out" | sed -n 4p)" \
+   '3|2|2|Button|btn_login|Đăng nhập||24|120|300|150|visible,enabled,actionable'
+is "a disabled, unclickable element carries only visible" \
+   "$(printf '%s\n' "$android_out" | sed -n 5p | awk -F'|' '{print $12}')" 'visible'
+is "two siblings at one depth share a parent" \
+   "$(printf '%s\n' "$android_out" | awk -F'|' 'NR>=4 {print $3}' | sort -u | join_lines ',')" '2'
+is "every element is numbered, filtered or not" \
+   "$(printf '%s\n' "$android_out" | grep -c '^[0-9]')" "4"
+
+# --- two warnings that had to learn what not to say ----------------------------
+#
+# Both came from an agent using this against a real phone and reading the noise.
+
+snap_warns() {  # snap_warns <rows> — the warning lines only
+  printf '%s\n' "$1" | awk -v ALL=1 -v GREP="" -v MINHIT=44 \
+    -f "$DT_HOME/scripts/snapshot.awk" 2>/dev/null | grep '⚠' || true
+}
+
+# A screen is built from boxes that each cover the window. Saying they overlap
+# is true and useless: "overlaps a sibling by 428pt — [7] [8] [10] and 9 more".
+STACK='WINDOW|428|926|portrait
+1|0|0|Application||App||0|0|428|926|visible,enabled
+2|1|1|Other||A||0|0|428|926|visible,enabled
+3|1|1|Other||B||0|0|428|926|visible,enabled'
+case "$(snap_warns "$STACK")" in
+  *"overlaps a sibling"*) bad "two full-screen layers are a stack, not an overlap" \
+                              "$(snap_warns "$STACK" | join_lines ' ')" ;;
+  *) ok "two full-screen layers are a stack, not an overlap" ;;
+esac
+
+# But two boxes that are not full-screen still overlap.
+LAP='WINDOW|428|926|portrait
+1|0|0|Application||App||0|0|428|926|visible,enabled
+2|1|1|Other||A||0|100|400|200|visible,enabled
+3|1|1|Other||B||0|150|400|200|visible,enabled'
+case "$(snap_warns "$LAP")" in
+  *"overlaps a sibling"*) ok "two ordinary boxes still overlap" ;;
+  *) bad "two ordinary boxes still overlap" "the full-screen rule swallowed a real one" ;;
+esac
+
+# A tap goes to the centre. Spotlight's field is (32,4) 364x48 — generous, and
+# its centre sits at y=28 under a 47pt status bar, so the tap hits the clock.
+UNDER='WINDOW|428|926|portrait
+1|0|0|Application||App||0|0|428|926|visible,enabled
+2|1|1|StatusBar||||0|0|428|47|visible,enabled
+3|1|1|TextField||Tìm kiếm||32|4|364|48|visible,enabled,actionable
+4|1|1|Button||OK||32|100|364|48|visible,enabled,actionable'
+case "$(snap_warns "$UNDER")" in
+  *"centre is under the 47pt status bar"*) ok "a centre under the status bar is reported" ;;
+  *) bad "a centre under the status bar is reported" "$(snap_warns "$UNDER" | join_lines ' ')" ;;
+esac
+# and only the one that is under it
+case "$(snap_warns "$UNDER" | grep 'status bar')" in
+  *'[2]'*) bad "only the control under the status bar is named" "[2] is the status bar itself" ;;
+  *'[4]'*) bad "only the control under the status bar is named" "[4] sits below it" ;;
+  *) ok "only the control under the status bar is named" ;;
+esac
+
+# No StatusBar in the tree, no claim about one. A full-screen app has none, and
+# a height guessed from the device model would be wrong on the next device.
+NOSB='WINDOW|428|926|portrait
+1|0|0|Application||App||0|0|428|926|visible,enabled
+2|1|1|TextField||Tìm kiếm||32|4|364|48|visible,enabled,actionable'
+case "$(snap_warns "$NOSB")" in
+  *"status bar"*) bad "no status bar in the tree means no status bar warning" "it invented one" ;;
+  *) ok "no status bar in the tree means no status bar warning" ;;
+esac
+
+# --- recorded screens ----------------------------------------------------------
+#
+# The cases above are rectangles chosen to make one rule checkable by hand. These
+# are whole screens a real device actually produced, frozen. They catch what
+# hand-picked numbers cannot: a rule that is right in isolation and wrong when
+# forty elements are on screen at once, which is how the noise problem was found
+# in the first place.
+#
+# A fixture is a claim about what a driver did. Re-record one only after reading
+# the diff and agreeing with it.
+
+rows_shape_ok() {  # <file> — the seam between two adapters and five consumers
+  awk -F'|' '
+    NR == 1 { if ($1 != "WINDOW" || NF != 4) { print "line 1 is not a WINDOW row"; exit 1 } ; next }
+    NF != 12 { printf "line %d has %d fields, want 12\n", NR, NF; exit 1 }
+    $1 + 0 != NR - 1 { printf "line %d has serial %s, want %d\n", NR, $1, NR - 1; exit 1 }
+    $3 + 0 >= $1 + 0 { printf "line %d says its parent is %s, which is not before it\n", NR, $3; exit 1 }
+  ' "$1"
+}
+
+fixtures=0
+for f in "$DT_HOME"/tests/fixtures/*.rows; do
+  [ -e "$f" ] || continue
+  fixtures=$((fixtures + 1))
+  b="$(basename "$f")"
+
+  if out="$(rows_shape_ok "$f")" && [ -z "$out" ]; then
+    ok "$b obeys the row contract"
+  else
+    bad "$b obeys the row contract" "$out"
+  fi
+
+  exp="${f%.rows}.expected"
+  if [ -e "$exp" ]; then
+    min=44; case "$f" in *android*) min=48 ;; esac
+    got="$(awk -v ALL=0 -v GREP="" -v MINHIT="$min" -f "$DT_HOME/scripts/snapshot.awk" < "$f")"
+    if [ "$got" = "$(cat "$exp")" ]; then
+      ok "$b still renders as recorded"
+    else
+      bad "$b still renders as recorded" \
+          "$(diff <(printf '%s\n' "$got") "$exp" | head -4 | join_lines ' ')"
+    fi
+  fi
+done
+
+# A fixture directory that has quietly emptied would make every check above
+# vacuous, and a green run that tested nothing is worse than a red one.
+if [ "$fixtures" -gt 0 ]; then
+  ok "there are $fixtures recorded screen(s) to check against"
+else
+  bad "there are recorded screens to check against" "tests/fixtures/ has no .rows files"
+fi
+
+# --- install.sh ----------------------------------------------------------------
+#
+# It edits config.json, puts a symlink on PATH and installs Homebrew packages, so
+# the property worth pinning down is that --dry-run does NONE of it. A dry run
+# that mutates something is worse than no dry run at all: it is the flag people
+# reach for precisely when they do not yet trust the script.
+#
+# Every other flag is off here so the check stays hermetic — no Homebrew, no
+# `claude mcp list` health probe over the network, no WebDriverAgent build.
+
+INSTALL="$DT_HOME/install.sh"
+if [ ! -x "$INSTALL" ]; then
+  bad "install.sh is executable" "not found or not +x at $INSTALL"
+else
+  ok "install.sh is executable"
+
+  # STDIN FROM /dev/null, ALWAYS. install.sh asks which phone and which Apple
+  # team when there is more than one and a terminal to ask on. A check that
+  # inherits this script's terminal would sit at that prompt forever.
+  install_rc() { "$INSTALL" "$@" </dev/null >/dev/null 2>&1; printf '%s' "$?"; }
+
+  is "install.sh with no platform is a usage error" "$(install_rc)" "1"
+  is "install.sh rejects an unknown argument"       "$(install_rc --nope)" "1"
+  is "install.sh rejects a bad --mcp-scope"         "$(install_rc --ios --mcp-scope nope)" "1"
+
+  # The config it would rewrite is the one this very run is reading, which is
+  # what makes the check meaningful rather than theoretical.
+  CFG="$DT_HOME/config.json"
+  if [ -f "$CFG" ]; then
+    before="$(cksum < "$CFG")"
+    "$INSTALL" --ios --dry-run --no-deps --no-link --no-driver --no-mcp >/dev/null 2>&1 || true
+    is "a dry run leaves config.json byte-identical" "$(cksum < "$CFG")" "$before"
+  else
+    printf 'SKIP no config.json — the dry-run mutation check needs one\n'
+  fi
+
+  # A dry run must not create the PATH symlink either. Checked by asking for the
+  # link explicitly and then looking for it, rather than by trusting the flag.
+  DTLINK=""
+  for d in /usr/local/bin "$HOME/.local/bin"; do
+    [ -d "$d" ] && [ -w "$d" ] && { DTLINK="$d/devicetools"; break; }
+  done
+  if [ -n "$DTLINK" ] && [ ! -e "$DTLINK" ]; then
+    "$INSTALL" --ios --dry-run --no-deps --no-driver </dev/null >/dev/null 2>&1 || true
+    if [ -e "$DTLINK" ]; then
+      bad "a dry run does not create the PATH symlink" "created $DTLINK"
+      rm -f "$DTLINK"
+    else
+      ok "a dry run does not create the PATH symlink"
+    fi
+  else
+    printf 'SKIP the symlink already exists, so its absence proves nothing\n'
+  fi
+
+  # REGISTERING AN MCP SERVER IS NOT THIS SCRIPT'S DECISION TO MAKE.
+  #
+  # ~/.claude.json is shared with every other project on the machine. install.sh
+  # edits it only when asked with --mcp, and the default must stay the default:
+  # a run with no flags prints the command instead of running it.
+  out="$("$INSTALL" --ios --dry-run --no-deps --no-link --no-driver </dev/null 2>&1 || true)"
+  case "$out" in
+    *"claude mcp add devicetools"*) ok "a default run prints the mcp command rather than running it" ;;
+    *) bad "a default run prints the mcp command rather than running it" \
+           "the command is not in the output" ;;
+  esac
+  case "$out" in
+    *"dry   claude mcp add"*) bad "a default run does not call claude" "it tried to" ;;
+    *) ok "a default run does not call claude" ;;
+  esac
+
+  # WITH NO TERMINAL THERE IS NOBODY TO ASK, so it must refuse in writing
+  # rather than block. This is the CI case, and the case of anyone piping the
+  # output somewhere. Two iPhones or fifteen teams on the machine running this
+  # would otherwise hang the whole suite.
+  out="$("$INSTALL" --ios --dry-run --no-deps --no-link --no-driver </dev/null 2>&1 || true)"
+  case "$out" in
+    *"choose 1-"*) bad "no terminal means no prompt" "it printed a menu" ;;
+    *) ok "no terminal means no prompt" ;;
+  esac
+fi
+
+# --- remedies are spelled the way the reader can use them ----------------------
+#
+# Over MCP a model sees tool names and nothing else, so "run scripts/snapshot.sh"
+# is an instruction it cannot follow. Every remedy goes through as_cmd, which
+# spells the verb three ways depending on how it was reached. Reported from a
+# real session: tap failed and told the model to run a shell script.
+
+hits="$(grep -rn 'run scripts/[a-z]*\.sh' "$DT_HOME/scripts" 2>/dev/null \
+        | grep -v '/selftest\.sh:' || true)"
+if [ -z "$hits" ]; then
+  ok "no message tells the reader to run a script by path"
+else
+  bad "no message tells the reader to run a script by path" \
+      "$(printf '%s' "$hits" | head -3 | join_lines ' ')"
+fi
+
+is "as_cmd spells a verb for the CLI"   "$(DT_CLI=1 as_cmd doctor --recover)" "devicetools doctor --recover"
+is "as_cmd spells a verb for MCP"       "$(DT_MCP=1 as_cmd doctor --recover)" "doctor --recover"
+is "as_cmd spells a verb for the shell" "$(as_cmd doctor --recover)"          "scripts/doctor.sh --recover"
+
+# --- what an action reports about the screen -----------------------------------
+#
+# Three fields out of screen_state, and two callers reading them. The bug this
+# guards against is a third field landing inside the second.
+
+split_state "$(printf 'abcd\tLogin\t12345')"
+is "a full state splits into three"  "$ST_HASH/$ST_NAME/$ST_CONTENT" "abcd/Login/12345"
+split_state "$(printf 'abcd\t\t12345')"
+is "an unnamed screen keeps its digest" "$ST_HASH/$ST_NAME/$ST_CONTENT" "abcd//12345"
+split_state "abcd"
+is "a hash alone leaves the rest empty" "$ST_HASH/$ST_NAME/$ST_CONTENT" "abcd//"
+split_state ""
+is "an empty state is empty throughout" "$ST_HASH/$ST_NAME/$ST_CONTENT" "//"
+
+# --- tap --count ---------------------------------------------------------------
+#
+# A keypad entry is one call, not six. The bound is enforced, not merely
+# documented: an unbounded count is a way to hammer a real device by typo.
+
+tap_rc() { "$DT_HOME/scripts/tap.sh" "$@" >/dev/null 2>&1; printf '%s' "$?"; }
+is "--count rejects zero"         "$(tap_rc --count 0 x)"   "1"
+is "--count rejects a non-number" "$(tap_rc --count abc x)" "1"
+is "--count rejects a negative"   "$(tap_rc --count -3 x)"  "1"
+is "--count is capped"            "$(tap_rc --count 21 x)"  "1"
+
+# --- a suggestion names the selector that would reach it -----------------------
+#
+# `tap text:8` was refused, and the list of near misses offered `Key "8"` — the
+# very thing asked for, matching on its label rather than its value. Naming the
+# answer without spelling it is a riddle.
+
+# candidate_elements belongs to an adapter, so it runs in an adapter's process.
+# The Android one is pure awk over the row format, which is why it is the one
+# that can be exercised with no device and no driver.
+cand_in() {  # cand_in <row> <value>
+  bash -c 'source "$0" >/dev/null 2>&1; candidate_elements "$1" "$2"' \
+    "$DT_HOME/scripts/android/lib.sh" "$1" "$2" 2>/dev/null || true
+}
+cand="$(cand_in '1|Key||8||10|20|40|40|1|1|0|1|' '8')"
+case "$cand" in
+  *"try label:8"*) ok "an exact match on another field names that selector" ;;
+  *) bad "an exact match on another field names that selector" "got [$cand]" ;;
+esac
+cand="$(cand_in '1|TextView||88||10|20|40|40|1|1|0|0|' '8')"
+case "$cand" in
+  *"try "*) bad "a partial match suggests nothing" "got [$cand]" ;;
+  *) ok "a partial match suggests nothing" ;;
+esac
+
+# --- what is inside a bundle, and what will let it onto a phone ----------------
+#
+# DeviceTools does not build, and has to say why a build will not install. Both
+# helpers are pure file reading, so both are checkable here.
+
+in_ios() { bash -c 'source "$0" >/dev/null 2>&1; "$@"' "$DT_HOME/scripts/ios/lib.sh" "$@" 2>/dev/null || true; }
+
+BUNDLE_DIR="$(mktemp -d)/Demo.app"
+dt_cleanup_add "$(dirname "$BUNDLE_DIR")"
+mkdir -p "$BUNDLE_DIR"
+cat > "$BUNDLE_DIR/Info.plist" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleIdentifier</key><string>com.example.demo</string>
+<key>CFBundleShortVersionString</key><string>3.4.1</string>
+<key>CFBundleVersion</key><string>1207</string>
+</dict></plist>
+PLIST
+
+is "a bundle reports id, version and build" \
+   "$(in_ios bundle_facts "$BUNDLE_DIR")" "com.example.demo|3.4.1|1207||unsigned"
+
+# The message this exists for: CODE_SIGNING_ALLOWED=NO in a Makefile produces a
+# bundle a simulator takes and a device refuses, and iOS calls that
+# ApplicationVerificationFailed.
+case "$(in_ios bundle_facts "$BUNDLE_DIR")" in
+  *"|unsigned") ok "an unsigned bundle is recognised as unsigned" ;;
+  *) bad "an unsigned bundle is recognised as unsigned" "$(in_ios bundle_facts "$BUNDLE_DIR")" ;;
+esac
+
+rmdir "$BUNDLE_DIR" 2>/dev/null || rm -rf "$BUNDLE_DIR"
+mkdir -p "$BUNDLE_DIR"
+holds_not "a directory with no Info.plist is not a bundle" \
+  bash -c 'source "$0" >/dev/null 2>&1; bundle_facts "$1"' "$DT_HOME/scripts/ios/lib.sh" "$BUNDLE_DIR"
+
+# The provisioning checks that stood here are gone with doctor's section 9.
+# Whose certificate signs the app is the build's business, not this tool's, and
+# a check standing outside the build could only guess — which it did, twice,
+# naming a team the project had nothing to do with.
+#
+# What survives is above: `app install` still reads the bundle's own signature,
+# because "will this verb work" is a different question from "whose account is
+# this".
+
+# --- app.sh takes its arguments seriously --------------------------------------
+
+app_rc() { "$DT_HOME/scripts/app.sh" "$@" >/dev/null 2>&1; printf '%s' "$?"; }
+is "install rejects an unknown flag"      "$(app_rc install --bogus)"    "1"
+is "install takes one path"               "$(app_rc install a b)"        "1"
+is "launch takes at most one bundle id"   "$(app_rc launch a b)"         "1"
+is "uninstall takes at most one bundle id" "$(app_rc uninstall a b)"     "1"
+
+# --- devicetools config --------------------------------------------------------
+#
+# It rewrites the file every other script reads, so the checks are about the two
+# ways that goes wrong quietly: a typo'd key that reports success, and a number
+# turned into a string that still parses and stops comparing.
+#
+# Run against a copy, never the real config — a self-test that edits the config
+# it is testing with is a self-test that can leave the tool broken.
+
+DT="$DT_HOME/bin/devicetools"
+CFGDIR="$(mktemp -d)"
+dt_cleanup_add "$CFGDIR"
+cp "$DT_HOME/config.example.json" "$CFGDIR/config.json"
+
+dtc() { DEVICETOOLS_CONFIG="$CFGDIR/config.json" "$DT" config "$@" 2>&1; }
+dtc_rc() { DEVICETOOLS_CONFIG="$CFGDIR/config.json" "$DT" config "$@" >/dev/null 2>&1; printf '%s' "$?"; }
+
+dtc set app.bundle_id com.example.set >/dev/null 2>&1 || true
+is "config set writes the value" "$(dtc get app.bundle_id)" "com.example.set"
+
+# There is one way to write a value. A shorthand for the app id would be a
+# second spelling of `set` to keep in step forever.
+is "there is no config app shorthand" "$(dtc_rc app com.example.viaapp)" "1"
+
+# Both app keys exist in every config and only one is read, so the "no such key"
+# guard cannot catch this one — the key is there, it is simply the wrong one.
+case "$(dtc set app.package com.example.wrongkey)" in
+  *"platform is ios, which reads app.bundle_id"*)
+    ok "setting the other platform's app key says so" ;;
+  *) bad "setting the other platform's app key says so" "no note was printed" ;;
+esac
+
+is "config set refuses a key that does not exist" "$(dtc_rc set app.bundleid x)" "1"
+is "--new creates it anyway"  "$(dtc_rc set app.bundleid x --new)" "0"
+
+# The type is taken from the value already there. Without that, wait_seconds
+# becomes "30" and every numeric comparison against it silently changes meaning.
+dtc set timeouts.wait_seconds 30 >/dev/null 2>&1 || true
+is "a number stays a number" \
+   "$(jq -r '.timeouts.wait_seconds | type' "$CFGDIR/config.json")" "number"
+is "a number rejects a non-number" "$(dtc_rc set timeouts.wait_seconds abc)" "1"
+
+# The key reaches a jq program, so anything but names and dots is refused rather
+# than escaped.
+is "a key with punctuation is refused" "$(dtc_rc set 'app.bundle_id; x' y)" "1"
+
+is "the config stays valid JSON throughout" \
+   "$(jq -e . "$CFGDIR/config.json" >/dev/null 2>&1 && printf yes || printf no)" "yes"
+
+# An interrupted write must not leave a half-file beside the real one.
+if ls "$CFGDIR"/config.json.tmp.* >/dev/null 2>&1; then
+  bad "config set leaves no temp file behind" "found $(ls "$CFGDIR"/config.json.tmp.* | head -1)"
+else
+  ok "config set leaves no temp file behind"
+fi
+
+# --- install.sh and uninstall.sh document the flags they accept ----------------
+#
+# The help text is the leading comment block, and the parser is a `case` twenty
+# lines below it. Nothing forces the two to agree, and a flag that works but is
+# undocumented is a flag nobody uses — while one that is documented and rejected
+# is worse. So every `--flag)` arm has to appear in `--help`.
+
+# EVERY VERB TOO, NOT JUST THE INSTALLERS. --snapshot went onto ten of them in
+# one change; nine documented headers and one silently accepting an undocumented
+# flag is exactly the drift this rule is for. The adapter file is run rather
+# than the dispatcher, because the dispatcher loads a config before it reaches
+# --help and this suite must answer with no device and no phone.
+verb_scripts="$DT_HOME/scripts/run.sh $DT_HOME/scripts/flow.sh"
+for v in "$DT_HOME"/scripts/ios/*.sh "$DT_HOME"/scripts/android/*.sh; do
+  case "$(basename "$v")" in lib.sh|setup.sh) continue ;; esac
+  verb_scripts="$verb_scripts $v"
+done
+
+for f in "$DT_HOME/install.sh" "$DT_HOME/uninstall.sh" $verb_scripts; do
+  b="$(basename "$(dirname "$f")")/$(basename "$f")"
+  case "$f" in "$DT_HOME"/install.sh|"$DT_HOME"/uninstall.sh) b="$(basename "$f")" ;; esac
+  [ -x "$f" ] || { bad "$b documents every flag it accepts" "not executable"; continue; }
+  help_out="$("$f" --help </dev/null 2>&1 || true)"
+  undocumented=""
+  # Flag names from the case arms: "  --foo|-f)" -> --foo -f
+  for flag in $(awk '/^ *--[a-z-]+[|)]/ {
+                       sub(/\).*/, ""); gsub(/^ +/, "");
+                       n = split($0, a, "|");
+                       for (i = 1; i <= n; i++) if (a[i] ~ /^--/) print a[i]
+                     }' "$f" | sort -u); do
+    case "$help_out" in *"$flag"*) ;; *) undocumented="$undocumented $flag" ;; esac
+  done
+  if [ -z "$undocumented" ]; then
+    ok "$b documents every flag it accepts"
+  else
+    bad "$b documents every flag it accepts" "missing from --help:$undocumented"
+  fi
+done
+
+# --- no verb leaves an unset variable on a path it can reach -------------------
+#
+# type.sh reported success on the OTP path and then put `type: unbound variable`
+# on stderr, because the journal line at the bottom is shared by all three
+# outcomes and only one of them names the field. Nothing failed, so nothing
+# announced it; the branch had simply never been reachable until `type` stopped
+# being refused inside a batch.
+#
+# `set -u` catches this AT RUN TIME, which means only on a path something walks.
+# Reading every expansion here would be a shell parser. What is checkable is the
+# shape that caused it: a bare $var used after the branch that assigns it, on a
+# line every branch reaches. So the rule is narrower and mechanical — the last
+# statement of a verb may not use a variable that only one branch sets.
+#
+# Checked by asking bash itself, on the one file that had it.
+unbound="$(bash -c '
+  set -u
+  # The two branches type.sh takes when it finds no input to name.
+  field_type=""; unset field_type
+  printf "%s" "${field_type-}"
+' 2>&1 || true)"
+is "an unset field name does not abort the journal line" "$unbound" ""
+holds "type.sh guards the variable that only one of its branches sets" \
+  grep -q 'journal_append type "\$TEXT" "\${field_type-}"' "$DT_HOME/scripts/ios/type.sh"
+# And it is not called `type`, which is a shell builtin — the error read like a
+# missing command rather than a missing value.
+holds_not "no verb names a variable after a shell builtin" \
+  grep -qE '^\s*type=' "$DT_HOME/scripts/ios/type.sh" "$DT_HOME/scripts/android/type.sh"
+
+# --- --project, because MCP has no working directory ---------------------------
+#
+# dt_find_project walks up from $PWD, which is right for a shell and impossible
+# for a server: the host sets its working directory at spawn time and it never
+# changes, so every walk-up lands in the DeviceTools checkout whatever repository
+# the person is standing in. Reported after `flow save` wrote into the checkout,
+# advised running `init` in the app repository, and had no way to make the result
+# take effect.
+#
+# The flag is stripped in lib.sh, so it works on every verb without any of them
+# knowing. These checks are about that stripping, which is the part with teeth:
+# it edits the caller's own argument list.
+
+PROJDIR="$(mktemp -d)"
+dt_cleanup_add "$PROJDIR"
+printf 'devicetools-project 1\n' > "$PROJDIR/.devicetools"
+cp "$DT_HOME/config.example.json" "$PROJDIR/config.json"
+
+# What the verb is left holding, and where the project ended up.
+proj_argv() {
+  bash -c 'source "$0"; printf "%s|" "$DT_ROOT"; printf "[%s]" "$@"' "$DT_HOME/scripts/lib.sh" "$@" 2>/dev/null
+}
+is "--project sets the root and disappears from the arguments" \
+   "$(proj_argv label:X --project "$PROJDIR" --index 2)" "$PROJDIR|[label:X][--index][2]"
+is "without it the checkout is still the project" \
+   "$(proj_argv label:X)" "$DT_HOME|[label:X]"
+# `type -- --project` types the words. Option processing ends at --, or lib.sh
+# would silently eat text a verb was told to enter.
+is "-- ends option processing" \
+   "$(proj_argv -- --project "$PROJDIR")" "$DT_HOME|[--][--project][$PROJDIR]"
+# A trailing --project with nothing after it is left for the verb to refuse,
+# rather than swallowed as if it had been understood.
+is "a --project with no value is left alone" \
+   "$(proj_argv --project)" "$DT_HOME|[--project]"
+
+# Named explicitly, its config wins over one inherited from the environment —
+# a flag on this call is more specific than a variable set when the server
+# started, and a child that resolved half of each would be worse than either.
+is "the project config beats an inherited DEVICETOOLS_CONFIG" \
+   "$(DEVICETOOLS_CONFIG=/nowhere/config.json bash -c \
+      'source "$0" >/dev/null 2>&1; printf "%s" "$DT_CONFIG"' \
+      "$DT_HOME/scripts/lib.sh" --project "$PROJDIR" 2>/dev/null)" \
+   "$PROJDIR/config.json"
+
+# --- init is a verb, so both sides can reach it ---------------------------------
+#
+# It was a `case` arm in bin/devicetools, which made it invisible over MCP:
+# `flow save` told an agent to run it and no tool could.
+initsh() { "$DT_HOME/scripts/init.sh" "$@" 2>&1; }
+initsh_rc() { "$DT_HOME/scripts/init.sh" "$@" >/dev/null 2>&1; printf '%s' "$?"; }
+
+NEWPROJ="$(mktemp -d)"
+dt_cleanup_add "$NEWPROJ"
+is "init makes a directory a project" "$(initsh_rc "$NEWPROJ")" "0"
+holds "and leaves the marker" test -f "$NEWPROJ/.devicetools"
+holds "and a config to fill in"  test -f "$NEWPROJ/config.json"
+# flows/ is the reason to have a project, so it is NOT ignored.
+holds_not "flows/ is not gitignored" grep -q '^flows/' "$NEWPROJ/.gitignore"
+holds "but the state directory is" grep -q '^\.state/' "$NEWPROJ/.gitignore"
+
+# It writes into somebody else'"'"'s repository, so a second run must change nothing.
+printf 'edited by hand\n' > "$NEWPROJ/config.json"
+initsh "$NEWPROJ" >/dev/null 2>&1 || true
+is "a second init does not overwrite a config" \
+   "$(cat "$NEWPROJ/config.json")" "edited by hand"
+
+is "init refuses the checkout itself"  "$(initsh_rc "$DT_HOME")" "1"
+is "init refuses a directory that is not there" "$(initsh_rc /no/such/place)" "1"
+# On a command line "no argument" means "here". A server has no here.
+is "over MCP the directory is required" \
+   "$(DT_MCP=1 "$DT_HOME/scripts/init.sh" >/dev/null 2>&1; printf '%s' "$?")" "1"
+
+# --- run: a batch is checked before any of it happens --------------------------
+#
+# Everything here is --dry-run, so nothing reaches a device and the suite still
+# runs with no phone attached. That is also the property being tested: the whole
+# step list is validated before the first step is sent, because a typo in step
+# seven must not be found out after step six has tapped something in a live session.
+
+RUNDIR="$(mktemp -d)"
+dt_cleanup_add "$RUNDIR"
+printf 'devicetools-project 1\n' > "$RUNDIR/.devicetools"
+cp "$DT_HOME/config.example.json" "$RUNDIR/config.json"
+
+runsh() {  # runsh <args...> — run.sh against the throwaway project
+  DEVICETOOLS_PROJECT="$RUNDIR" DEVICETOOLS_CONFIG="$RUNDIR/config.json" \
+    "$DT_HOME/scripts/run.sh" "$@" 2>&1
+}
+runsh_rc() {
+  DEVICETOOLS_PROJECT="$RUNDIR" DEVICETOOLS_CONFIG="$RUNDIR/config.json" \
+    "$DT_HOME/scripts/run.sh" "$@" >/dev/null 2>&1; printf '%s' "$?"
+}
+
+is "a batch runs its steps in order" \
+   "$(runsh --dry-run --steps '[{"tap":"label:A"},{"back":true},{"key":"hide"}]' \
+     | awk '/^STEP/ { printf "%s ", $3 }')" \
+   "tap back key "
+
+# Flags become --key value, a true boolean becomes a bare flag, and two
+# positional arguments go in an array. Same rule as the MCP server's argv_from,
+# because it is the same question asked twice.
+is "extra keys become flags, in the verb's own spelling" \
+   "$(runsh --dry-run --steps '[{"scroll":"down","until":"label:X","times":3}]' | sed -n '2p')" \
+   'STEP 1/1 scroll down --until label:X --times 3'
+is "an array is two positional arguments" \
+   "$(runsh --dry-run --steps '[{"swipe":["label:A","label:B"]}]' | sed -n '2p')" \
+   'STEP 1/1 swipe label:A label:B'
+
+# TEXT THAT LOOKS LIKE A UID IS STILL TEXT.
+#
+# The uid guard was checking the positional argument of EVERY verb, and `type`'s
+# positional argument is what to type — so a batch could not enter an OTP, a
+# PIN, an amount, a card number or a phone number. On a production app that is
+# close to every field there is, and it meant `flow` could not hold a login,
+# which is the one example the tool's own description gives for why flows exist.
+#
+# Asked for by name in the report that found it: a `type` of digits must always
+# get through.
+is "a batch can type an OTP"      "$(runsh_rc --dry-run --steps '[{"type":"888888"}]')"     "0"
+is "a batch can type an amount"   "$(runsh_rc --dry-run --steps '[{"type":"5000000"}]')"    "0"
+is "and through a variable too"   "$(runsh_rc --dry-run --vars '{"otp":"888888"}' --steps '[{"type":"{{ otp }}"}]')" "0"
+# Substitution runs before validation, so this is the same check from the other
+# side: the digits must survive it.
+is "the digits reach the step, masked as a length" \
+   "$(runsh --dry-run --vars '{"otp":"888888"}' --steps '[{"type":"{{ otp }}"}]' | sed -n '2p')" \
+   'STEP 1/1 type (6 chars)'
+
+# `snapshot` IS BOTH A VERB AND A FLAG. {"tap": …, "snapshot": true} is the most
+# useful step anybody can write, and the verb list was eating the word before it
+# could be read as a flag — so it came back as "two verbs in one step".
+is "snapshot is a flag when the step already has a verb" \
+   "$(runsh --dry-run --steps '[{"tap":"label:X","snapshot":true}]' | sed -n '2p')" \
+   'STEP 1/1 tap label:X --snapshot'
+is "and still a verb when it is the only one" \
+   "$(runsh --dry-run --steps '[{"snapshot":true}]' | sed -n '2p')" \
+   'STEP 1/1 snapshot'
+
+# expect is wait with a deadline that means "now" — spelling, not a second
+# implementation, so it runs wait.sh.
+is "expect is accepted as a step" "$(runsh_rc --dry-run --steps '[{"expect":"screen:Home"}]')" "0"
+
+# NO UIDS, AND THE REASON IS NOT TIDINESS. A uid names a position on a screen
+# the caller was shown before the batch started, and by step three that screen
+# is two actions old.
+is "a bare uid is refused"        "$(runsh_rc --dry-run --steps '[{"tap":"7"}]')"     "1"
+is "a uid: selector is refused"   "$(runsh_rc --dry-run --steps '[{"tap":"uid:7"}]')" "1"
+is "a uid inside --until is refused" \
+   "$(runsh_rc --dry-run --steps '[{"scroll":"down","until":"3"}]')" "1"
+# Substitution happens before validation, so a variable holding a uid is one.
+is "a variable that expands to a uid is still a uid" \
+   "$(runsh_rc --dry-run --var n=7 --steps '[{"tap":"{{ n }}"}]')" "1"
+
+is "a step with two verbs is refused" \
+   "$(runsh_rc --dry-run --steps '[{"tap":"label:A","type":"x"}]')" "1"
+is "a step with no verb is refused" \
+   "$(runsh_rc --dry-run --steps '[{"nope":"x"}]')" "1"
+is "a verb that is not on the list is refused" \
+   "$(runsh_rc --dry-run --steps '[{"doctor":true}]')" "1"
+is "an object is not a step list" "$(runsh_rc --dry-run --steps '{"tap":"label:A"}')" "1"
+
+# THE REFUSAL COMES BEFORE THE FIRST STEP, NOT AT THE BAD ONE. Checked by
+# putting the fault last and looking for any sign the earlier steps announced
+# themselves.
+case "$(runsh --dry-run --steps '[{"tap":"label:A"},{"tap":"label:B"},{"tap":"9"}]')" in
+  *STEP*) bad "a bad step stops the batch before any of it runs" "steps were announced anyway" ;;
+  *) ok "a bad step stops the batch before any of it runs" ;;
+esac
+
+# A MISSING VARIABLE IS NOT A STRING TO TYPE. Without this, a flow whose
+# password was never supplied types the fourteen characters "{{ password }}"
+# into a login form and reports success, because something did change.
+is "an unfilled placeholder stops the batch" \
+   "$(runsh_rc --dry-run --steps '[{"type":"{{ password }}"}]')" "1"
+case "$(runsh --dry-run --steps '[{"type":"{{ password }}"}]')" in
+  *"no value for: password"*) ok "the unfilled placeholder is named" ;;
+  *) bad "the unfilled placeholder is named" "$(runsh --dry-run --steps '[{"type":"{{ password }}"}]' | join_lines ' / ')" ;;
+esac
+
+# THE SECRET NEVER APPEARS. `type` is announced as a length, and every other
+# substituted value is masked back to {{ name }} — this output is read by a
+# model, written to a log and pasted into tickets.
+typed="$(runsh --dry-run --var password='hunter2' --steps '[{"type":"{{ password }}"},{"tap":"label:{{ password }}"}]')"
+case "$typed" in
+  *'hunter2'*) bad "a variable's value never reaches the transcript" "the value was printed" ;;
+  *) ok "a variable's value never reaches the transcript" ;;
+esac
+case "$typed" in
+  *'type (7 chars)'*) ok "typed text is announced as a length" ;;
+  *) bad "typed text is announced as a length" "$(printf '%s' "$typed" | join_lines ' / ')" ;;
+esac
+case "$typed" in
+  *'tap label:{{ password }}'*) ok "a substituted value is masked back to its name" ;;
+  *) bad "a substituted value is masked back to its name" "$(printf '%s' "$typed" | join_lines ' / ')" ;;
+esac
+
+# A BATCH OF EIGHT PRINTED FIFTY-SIX LINES OF SYSTEM LOG.
+#
+# Every action attaches the app's log lines since it began. Alone that is a few
+# lines; in a batch it multiplies, almost all of it `UIAccessibility: Attempting
+# to send notification` — more noise than the batch produced in signal, growing
+# with the length of the batch, which is the thing this verb exists to make
+# longer. So a step that worked loses its LOG block and the step that failed
+# keeps it, because that is the one anybody is reading.
+strip_in() { printf '%s\n' "$1" | strip_log_block; }
+LOGGY='TAP    label:X — resolved by label, Button at 24,600,327,50 → tapped 187,625
+SCREEN changed — "A" #1111 → "B" #2222
+LOG    2 lines
+       UIAccessibility: Attempting to send notification
+       UIAccessibility: Attempting to send notification
+
+SCREEN "B" #2222  428x926  portrait
+
+[1]  Button "Xác nhận"  (24,600)  327x50  enabled'
+# Four lines of substance survive: the action, the SCREEN verdict, the tree's
+# own SCREEN header and its one element. Three go: the LOG header and two log
+# lines.
+is "the log block goes, and nothing else does" \
+   "$(strip_in "$LOGGY" | grep -c .)" "4"
+case "$(strip_in "$LOGGY")" in
+  *UIAccessibility*) bad "the log lines themselves are dropped" "they survived" ;;
+  *) ok "the log lines themselves are dropped" ;;
+esac
+# The --snapshot tree is neither indented by seven nor introduced by LOG, so it
+# must come through whole — dropping it would take the point out of the flag.
+case "$(strip_in "$LOGGY")" in
+  *'[1]  Button "Xác nhận"'*) ok "a --snapshot tree survives the log stripping" ;;
+  *) bad "a --snapshot tree survives the log stripping" "$(strip_in "$LOGGY" | join_lines ' / ')" ;;
+esac
+
+# --- flow: the batch, kept ------------------------------------------------------
+
+flowsh() {
+  DEVICETOOLS_PROJECT="$RUNDIR" DEVICETOOLS_CONFIG="$RUNDIR/config.json" \
+    "$DT_HOME/scripts/flow.sh" "$@" 2>&1
+}
+flowsh_rc() {
+  DEVICETOOLS_PROJECT="$RUNDIR" DEVICETOOLS_CONFIG="$RUNDIR/config.json" \
+    "$DT_HOME/scripts/flow.sh" "$@" >/dev/null 2>&1; printf '%s' "$?"
+}
+
+case "$(flowsh list)" in
+  *'no flows yet'*) ok "an empty flows directory says so rather than failing" ;;
+  *) bad "an empty flows directory says so rather than failing" "$(flowsh list | join_lines ' / ')" ;;
+esac
+
+flowsh save login --description "log in" \
+  --steps '[{"wait":"screen:Auth.LoginView","timeout":2},{"type":"{{ password }}"}]' >/dev/null 2>&1 || true
+holds "a saved flow is a file in the project" test -f "$RUNDIR/flows/login.json"
+
+# THE VARIABLES A FLOW NEEDS ARE READ OUT OF ITS OWN STEPS, not declared by
+# hand. A hand-kept list is a second copy of the truth, and it is the copy that
+# goes stale.
+is "a flow records the variables its steps use" \
+   "$(jq -rc '.vars | join(",")' "$RUNDIR/flows/login.json" 2>/dev/null)" "password"
+
+is "a flow will not save steps that would not run" \
+   "$(flowsh_rc save broken --steps '[{"tap":"7"}]')" "1"
+holds_not "a refused flow leaves no file behind" test -f "$RUNDIR/flows/broken.json"
+
+# `flow list` could never run a flow called "list".
+is "a flow may not be named after a subcommand" "$(flowsh_rc save list --steps '[{"back":true}]')" "1"
+# The name becomes a filename, so it may not be a path.
+is "a flow name may not be a path" "$(flowsh_rc run ../../etc/passwd)" "1"
+is "an unknown flow is refused"    "$(flowsh_rc run nosuchflow)" "1"
+
+is "a bare name means run"         "$(flowsh_rc login --dry-run --var password=x)" "0"
+is "a flow refuses to run without the values it needs" "$(flowsh_rc login --dry-run)" "1"
+
+flowsh save outer --steps '[{"flow":"login"},{"back":true}]' >/dev/null 2>&1 || true
+case "$(flowsh outer --dry-run --var password=x)" in
+  *'STEP 1/2 flow login'*) ok "a flow can be a step in another flow" ;;
+  *) bad "a flow can be a step in another flow" "$(flowsh outer --dry-run --var password=x | join_lines ' / ')" ;;
+esac
+# `outer` has no placeholder of its own and still cannot run without login's
+# password. Declaring only its own would make `flow list` under-report it and
+# `flow run outer` fail at the step instead of at the door.
+is "a composing flow declares what its children need" \
+   "$(jq -rc '.vars | join(",")' "$RUNDIR/flows/outer.json" 2>/dev/null)" "password"
+is "and it refuses to run without them" "$(flowsh_rc outer --dry-run)" "1"
+
+# A FLOW THAT INCLUDES ITSELF IS REFUSED WHEN IT IS SAVED, not when it is run.
+# save validates with a dry run, the dry run descends into nested flows, and a
+# flow cannot include one that does not exist yet — so a cycle cannot be written
+# in the first place.
+is "a self-referential flow cannot be saved" \
+   "$(flowsh_rc save selfref --steps '[{"flow":"selfref"}]')" "1"
+
+# And the depth cap is still there underneath, for a cycle assembled some other
+# way — by editing two files by hand, say.
+is "a flow refuses to nest past the cap" \
+   "$(DT_FLOW_DEPTH=3 DEVICETOOLS_PROJECT="$RUNDIR" DEVICETOOLS_CONFIG="$RUNDIR/config.json" \
+      "$DT_HOME/scripts/flow.sh" login --dry-run >/dev/null 2>&1; printf '%s' "$?")" "1"
+
+is "delete removes it" "$(flowsh_rc delete login)" "0"
+holds_not "and the file is gone" test -f "$RUNDIR/flows/login.json"
+
+# --- nothing calls a function that was deleted ---------------------------------
+#
+# wait.sh guarded an early exit with `[ -n "$(baseline_file)" ]`, and
+# baseline_file belonged to the test layer that was demolished. So every poll ran
+# it as a command, put "command not found" on stderr, and read the condition as
+# false — eight lines of noise per wait, on a phone, guarding a block that had
+# not run since the day the function was removed. Nothing failed, which is why
+# it lasted.
+#
+# The demolition check above catches a deleted FILE being named. This catches a
+# deleted FUNCTION being called, which is the quieter half.
+for gonefn in baseline_file fingerprint_score repair_log record_step coverage_of; do
+  hits="$(grep -rn "\\b$gonefn\\b" "$DT_HOME/scripts" "$DT_HOME/bin" "$DT_HOME/integrations" 2>/dev/null \
+          | grep -v '/selftest\.sh:' | grep -vE ':[0-9]+: *#' || true)"
+  if [ -z "$hits" ]; then
+    ok "nothing calls $gonefn"
+  else
+    bad "nothing calls $gonefn" "$(printf '%s' "$hits" | awk -F: '{ printf "%s:%s ", $1, $2 }')"
+  fi
+done
+
+# --- --help is derived, never addressed by line number -------------------------
+#
+# `sed -n '2,31p'` is correct exactly until somebody adds a paragraph above the
+# range, and then it prints half a sentence and stops. Every verb in this tool
+# had one, and snapshot's was already cutting `--grep`'s description in two.
+# Nothing announces it: the flag is still mentioned, so even the check that
+# every flag appears in --help went on passing.
+ranged="$(grep -rln "sed -n '2,[0-9]*p' \"\${BASH_SOURCE\[0\]}\"" \
+            "$DT_HOME/scripts" "$DT_HOME/bin" "$DT_HOME/integrations" 2>/dev/null || true)"
+if [ -z "$ranged" ]; then
+  ok "no script prints its help by line number"
+else
+  bad "no script prints its help by line number" \
+      "$(printf '%s' "$ranged" | join_lines ' ')"
+fi
+
+# --- nothing writes into a reader that leaves early ----------------------------
+#
+# `printf … | grep -q "$x"` prints a broken pipe on every match. grep -q exits
+# the instant it finds the string, the shell's own printf is still writing, and
+# bash puts `lib.sh: line N: printf: write error: Broken pipe` on stderr.
+# Doctor leaked two of those on every run against a healthy phone — a message
+# that reads like a fault, next to a column of OKs, in the one command people
+# run when they already suspect something is broken.
+#
+# Only the SHELL's printf is caught here, and only when it feeds the early
+# exiter directly. `printf | jq | head` is a different shape: jq reads its input
+# to the end before it emits anything, so the write completes.
+# Comment lines are dropped, or this check fails on the paragraphs explaining
+# it — including the two above the real fixes, which name the shape they are
+# there to stop somebody writing again.
+pipebug="$(grep -rnE "printf[^|]*\| *(grep -q|head )" \
+             "$DT_HOME/scripts" "$DT_HOME/bin" "$DT_HOME/integrations" 2>/dev/null \
+           | grep -v '/selftest\.sh:' | grep -vE ':[0-9]+: *#' || true)"
+if [ -z "$pipebug" ]; then
+  ok "no shell printf writes into grep -q or head"
+else
+  bad "no shell printf writes into grep -q or head" \
+      "$(printf '%s' "$pipebug" | awk -F: '{ printf "%s:%s ", $1, $2 }')"
+fi
+
+# --- the link manifest cannot drift from the tree ------------------------------
+#
+# scripts/links.tsv is what puts the verb surface back after a package manager
+# throws it away, and it is generated from the tree — so the only way it goes
+# wrong is by being generated once and then forgotten. Regenerating and
+# comparing is the same rule the recorded screen lives under.
+if diff <(cd "$DT_HOME/scripts" && find . -type l | sed 's|^\./||' | sort \
+          | while IFS= read -r l; do printf '%s\t%s\n' "$l" "$(readlink "$l")"; done) \
+        "$DT_HOME/scripts/links.tsv" >/dev/null 2>&1; then
+  ok "the link manifest matches the symlinks in the tree"
+else
+  bad "the link manifest matches the symlinks in the tree" \
+      "run scripts/relink.sh --write"
+fi
+
+# A checkout with its links intact must find nothing to do — this runs from both
+# entry points on every invocation, and one that did work every time would be a
+# tool rewriting its own installation directory for no reason.
+is "relink is a no-op on a complete tree" \
+   "$("$DT_HOME/scripts/relink.sh" --check >/dev/null 2>&1; printf '%s' "$?")" "0"
+
+# The restore itself, on a copy — never on the tree the suite is running from.
+LINKDIR="$(mktemp -d)"
+dt_cleanup_add "$LINKDIR"
+cp -R "$DT_HOME/scripts" "$LINKDIR/scripts"
+find "$LINKDIR/scripts" -type l -delete
+is "a tree with no links at all is reported incomplete" \
+   "$("$LINKDIR/scripts/relink.sh" --check >/dev/null 2>&1; printf '%s' "$?")" "2"
+is "and relink puts every one of them back" \
+   "$("$LINKDIR/scripts/relink.sh" >/dev/null 2>&1 && "$LINKDIR/scripts/relink.sh" --check >/dev/null 2>&1; printf '%s' "$?")" "0"
+is "the restored links point where the manifest says" \
+   "$(readlink "$LINKDIR/scripts/ios/tap.sh"),$(readlink "$LINKDIR/scripts/tap.sh")" \
+   "../common/tap.sh,dispatch.sh"
+
+# A REGULAR FILE IN THE WAY IS NOT REPLACED. Somebody may have made a verb into
+# a real script on purpose, and an installer may have dereferenced a link into a
+# copy; overwriting either to restore a symlink is worse than saying what is there.
+find "$LINKDIR/scripts" -type l -delete
+printf '#!/usr/bin/env bash\n' > "$LINKDIR/scripts/tap.sh"
+"$LINKDIR/scripts/relink.sh" >/dev/null 2>&1 || true
+is "a real file where a link belongs is left alone" \
+   "$(head -1 "$LINKDIR/scripts/tap.sh")" "#!/usr/bin/env bash"
+
+# --- the two config resolvers agree --------------------------------------------
+#
+# lib.sh and the MCP server each work out where config.json is, and the server
+# deliberately sources nothing — it owns its own EXIT trap. Two copies of an
+# order is two chances for them to answer differently, and a session where the
+# CLI and the agent are driving different apps is a long way from obvious.
+CFGSEQ="$(mktemp -d)"; dt_cleanup_add "$CFGSEQ"
+mkdir -p "$CFGSEQ/xdg/devicetools" "$CFGSEQ/proj"
+cp "$DT_HOME/config.example.json" "$CFGSEQ/xdg/devicetools/config.json"
+cp "$DT_HOME/config.example.json" "$CFGSEQ/proj/config.json"
+printf 'devicetools-project 1\n' > "$CFGSEQ/proj/.devicetools"
+
+lib_config() {  # lib_config <env-assignments...> — what lib.sh resolves to
+  env "$@" bash -c 'source "$0" >/dev/null 2>&1; printf "%s" "$DT_CONFIG"' \
+    "$DT_HOME/scripts/lib.sh" 2>/dev/null
+}
+is "an explicit DEVICETOOLS_CONFIG wins" \
+   "$(lib_config DEVICETOOLS_CONFIG=/named/config.json XDG_CONFIG_HOME="$CFGSEQ/xdg")" \
+   "/named/config.json"
+is "then the project" \
+   "$(lib_config DEVICETOOLS_PROJECT="$CFGSEQ/proj" XDG_CONFIG_HOME="$CFGSEQ/xdg")" \
+   "$CFGSEQ/proj/config.json"
+# The npx case: the package directory has no config, so the per-user one is what
+# is left — and it must be found rather than reported as missing beside a cache
+# directory npm may delete before the next run.
+is "then the per-user one" \
+   "$(lib_config DEVICETOOLS_PROJECT="$CFGSEQ" XDG_CONFIG_HOME="$CFGSEQ/xdg")" \
+   "$CFGSEQ/xdg/devicetools/config.json"
+
+# --- the verb surface ---------------------------------------------------------
+#
+# Every scripts/<verb>.sh is a symlink to dispatch.sh, and dispatch execs
+# scripts/<platform>/<verb>.sh. A verb whose adapter file was deleted still
+# looks fine in `ls` and fails only when somebody calls it, which during a
+# demolition is exactly the mistake worth catching.
+
+# A SYMLINK IS THE TEST, NOT A LIST OF EXCEPTIONS. Every dispatched verb is a
+# symlink to dispatch.sh; a real file in scripts/ is platform-neutral by
+# construction — lib.sh, selftest.sh, run.sh, flow.sh — and has no adapter to
+# be missing. Naming them would be a second list to keep, and it is the list
+# that would not be kept.
+for v in "$DT_HOME"/scripts/*.sh; do
+  [ -L "$v" ] || continue
+  b="$(basename "$v" .sh)"
+  missing=""
+  for p in ios android; do
+    [ -e "$DT_HOME/scripts/$p/$b.sh" ] || missing="$missing $p"
+  done
+  if [ -z "$missing" ]; then
+    ok "verb '$b' exists for both platforms"
+  else
+    bad "verb '$b' exists for both platforms" "missing for:$missing"
+  fi
+done
+
+# And nothing in scripts/ may still reference something that was deleted — not
+# in a call, and not in a comment either. A comment pointing at a script that is
+# gone is a wrong answer to somebody reading the file to learn how this works.
+#
+# Two rounds of demolition are listed here: the test layer, and then the parts
+# that were not the debugger — the studio window, screen streaming, video.
+#
+# This file is excluded because the list below names every one of them.
+# run.sh is NOT on this list any more. The name belonged to the deleted test
+# runner and has been reclaimed by the batch verb, which is a different thing
+# that happens to be the obvious word for it.
+for gone in report.sh repair.sh resolve.awk coverage.sh audit.sh \
+            explore.sh quickstart.sh fleet.sh diagnose.sh record.sh \
+            studio.sh stream.sh capture.sh video.sh inspect.sh \
+            mjpeg-oneshot.js StudioApp.swift; do
+  # -F, because these names contain a dot. Without it `stream.sh` matches the
+  # phrase "Upstream ships", and the check reports a dangling reference that is
+  # nothing of the kind — a false alarm in a demolition check is how a real one
+  # gets ignored.
+  hits="$(grep -rlF "$gone" "$DT_HOME/scripts" "$DT_HOME/bin" 2>/dev/null \
+          | grep -v '/selftest\.sh$' || true)"
+  if [ -z "$hits" ]; then
+    ok "nothing references $gone"
+  else
+    bad "nothing references $gone" "still named in: $(printf '%s' "$hits" | tr '\n' ' ')"
+  fi
+done
+
+# --- verdict ------------------------------------------------------------------
+
+DT_REACHED_END=1
+if [ "$FAILED" -eq 0 ]; then
+  printf 'RESULT PASS neutral-layer selftest\n'
+  exit 0
+fi
+printf 'RESULT FAIL %d check(s)\n' "$FAILED"
+exit 5