@mmerterden/multi-agent-pipeline 16.29.0 → 16.31.0

package/pipeline/scripts/probe-evidence-capability.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+#
+# probe-evidence-capability.sh  -  measure what visual evidence this machine and
+# this repo can actually produce, BEFORE the user is asked to choose a test depth.
+#
+# Contract: multi-agent-refs/features/visual-evidence.md section 4.
+#
+# The order is probe, then question, then run. Offering "unit + UI test with a
+# screen recording" and only then discovering there is no UI test target, or no
+# booted simulator, spends the user's answer on something that cannot happen. So
+# the options are built from what this prints.
+#
+# Three rules this file exists to keep:
+#
+#   1. Absence carries a reason. Every empty value is paired with a *_REASON, so
+#      a closed option can say why it is closed instead of vanishing from the menu.
+#   2. Unmeasurable is `unknown`, never `false`. A probe that could not look and a
+#      probe that looked and found nothing are different facts, and collapsing
+#      them lets a missing tool read as a clean negative.
+#   3. Detection is not reimplemented here. The UI test answer comes from
+#      run-ui-tests.sh detect, which is also what actually runs the tests; a
+#      second copy is a second place for the answer to drift.
+#
+# Usage:
+#   probe-evidence-capability.sh --platform <ios|android> [--repo <path>]
+#                                [--changed <f>[,<f>...]] [--json]
+#                                [--json-out <path>] [--only all|device]
+#
+# Output: KEY='VALUE' lines (eval-able; every value is shell-quoted), or a JSON object with --json (shaped for
+# state.evidenceCapability). --json-out writes that JSON to a file while stdout
+# stays KEY=VALUE, so one run serves both the shell that builds the menu and the
+# state that records the measurement - two runs would mean two repo scans and
+# two chances to disagree.
+#
+# --only device skips the UI-test detection. Phase 3 re-checks the device right
+# before recording, and nothing else it would re-scan can have changed.
+#
+# Exit: 0 probed (whatever the verdicts), 2 usage.
+#       Never non-zero for an absent capability: absence is the finding.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLATFORM=""; REPO="$PWD"; CHANGED=""; AS_JSON=0; JSON_OUT=""; ONLY="all"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform) PLATFORM="${2:-}"; shift 2 ;;
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --changed) CHANGED="${CHANGED:+$CHANGED,}${2:-}"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    --json-out) JSON_OUT="${2:-}"; shift 2 ;;
+    --only) ONLY="${2:-all}"; shift 2 ;;
+    *) echo "probe-evidence-capability: unknown option $1" >&2; exit 2 ;;
+  esac
+done
+case "$ONLY" in all | device) ;; *)
+  echo "probe-evidence-capability: --only takes 'all' or 'device'" >&2; exit 2 ;;
+esac
+
+case "$PLATFORM" in ios | android) ;; *)
+  echo "usage: probe-evidence-capability.sh --platform <ios|android> [--repo <path>] [--changed <f>] [--json]" >&2
+  exit 2 ;;
+esac
+[ -d "$REPO" ] || { echo "probe-evidence-capability: no such repo directory: $REPO" >&2; exit 2; }
+
+UI_TEST_TARGET=""; UI_TEST_TARGETS=""; UI_TEST_TARGET_REASON=""
+UI_TEST_MATCHES=""; UI_TEST_MATCH_REASON=""
+DEVICE=""; DEVICE_REASON=""
+RECORDER="unknown"; RECORDER_REASON=""
+MCP="unknown"; MCP_REASON=""
+
+# ---- UI test target, delegated ------------------------------------------------
+RUNNER="$HERE/run-ui-tests.sh"
+if [ "$ONLY" = "device" ]; then
+  # Phase 3 re-checks the device right before recording, and only the device.
+  # Delegating detection there would re-walk the whole repo for a row that
+  # cannot have changed, which cost 5 seconds of a phase that is already holding
+  # a green build.
+  UI_TEST_TARGET_REASON="not probed (--only device)"
+elif [ ! -x "$RUNNER" ] && [ ! -f "$RUNNER" ]; then
+  UI_TEST_TARGET_REASON="run-ui-tests.sh not found beside this script"
+else
+  DETECT_ARGS=(detect --platform "$PLATFORM" --repo "$REPO")
+  [ -n "$CHANGED" ] && DETECT_ARGS+=(--changed "$CHANGED")
+  while IFS='=' read -r k v; do
+    case "$k" in
+      UI_TEST_TARGET) UI_TEST_TARGET="$v" ;;
+      UI_TEST_TARGETS) UI_TEST_TARGETS="$v" ;;
+      UI_TEST_TARGET_REASON) UI_TEST_TARGET_REASON="$v" ;;
+      UI_TEST_MATCHES) UI_TEST_MATCHES="$v" ;;
+      UI_TEST_MATCH_REASON) UI_TEST_MATCH_REASON="$v" ;;
+    esac
+  done < <(bash "$RUNNER" "${DETECT_ARGS[@]}" 2>/dev/null)
+fi
+
+# ---- Device -------------------------------------------------------------------
+case "$PLATFORM" in
+  ios)
+    if ! command -v xcrun >/dev/null 2>&1; then
+      DEVICE_REASON="xcrun unavailable; cannot tell whether a simulator exists"
+    else
+      DEVICE=$(xcrun simctl list devices booted 2>/dev/null | grep -oE '[0-9A-F-]{36}' | head -1)
+      if [ -z "$DEVICE" ]; then
+        # Bootable is not booted, and the difference is a question the user can
+        # act on: one is "start your simulator", the other is "this machine has
+        # no iOS runtime installed".
+        if xcrun simctl list devices available 2>/dev/null | grep -q "([0-9A-F-]\{36\})"; then
+          DEVICE_REASON="no booted simulator, but one is available to boot"
+        else
+          DEVICE_REASON="no iOS simulator available on this machine"
+        fi
+      fi
+    fi
+    ;;
+  android)
+    if ! command -v adb >/dev/null 2>&1; then
+      DEVICE_REASON="adb unavailable; cannot tell whether a device is attached"
+    else
+      DEVICE=$(adb devices 2>/dev/null | awk 'NR>1 && $2=="device" {print $1; exit}')
+      [ -n "$DEVICE" ] || DEVICE_REASON="no attached device or running emulator"
+    fi
+    ;;
+esac
+
+# ---- Recorder -----------------------------------------------------------------
+# The recorder is the same CLI the capture needs, so this answers "would
+# capture-evidence.sh video start work" rather than "is some recorder installed".
+case "$PLATFORM" in
+  ios)
+    if command -v xcrun >/dev/null 2>&1; then RECORDER="true"; else
+      RECORDER="false"; RECORDER_REASON="xcrun unavailable"
+    fi
+    ;;
+  android)
+    if command -v adb >/dev/null 2>&1; then RECORDER="true"; else
+      RECORDER="false"; RECORDER_REASON="adb unavailable"
+    fi
+    ;;
+esac
+if [ "$RECORDER" = "true" ] && ! command -v ffprobe >/dev/null 2>&1; then
+  # Not fatal. ffprobe only verifies the result, so its absence downgrades what
+  # can be CHECKED about a recording, never whether one can be made.
+  RECORDER_REASON="ffprobe unavailable; a recording cannot be verified after capture"
+fi
+
+# ---- Toolkit MCP --------------------------------------------------------------
+# Registration only, never a handshake: a probe that spawns the server costs
+# seconds at intake, and the question this answers is whether tier 2 may be
+# offered at all.
+CLAUDE_JSON="$HOME/.claude.json"
+SETTINGS_JSON="$HOME/.claude/settings.json"
+if command -v node >/dev/null 2>&1; then
+  MCP=$(node -e '
+    const fs = require("fs");
+    const hit = (p) => {
+      try {
+        const j = JSON.parse(fs.readFileSync(p, "utf8"));
+        return Object.keys(j.mcpServers || {}).some((k) => /toolkit/i.test(k));
+      } catch { return false; }
+    };
+    process.stdout.write(process.argv.slice(1).some(hit) ? "true" : "false");
+  ' "$CLAUDE_JSON" "$SETTINGS_JSON" 2>/dev/null)
+  [ -n "$MCP" ] || MCP="unknown"
+  [ "$MCP" = "false" ] && MCP_REASON="no mcpServers entry matching /toolkit/i"
+  [ "$MCP" = "unknown" ] && MCP_REASON="could not read the MCP registration files"
+else
+  MCP="unknown"; MCP_REASON="node unavailable; cannot read the MCP registration"
+fi
+
+# ---- Tier verdicts ------------------------------------------------------------
+# Computed before the report so both output forms carry them: a caller that
+# persists the JSON and a caller that evals the KEY=VALUE lines must not have to
+# re-derive the same booleans and risk deriving them differently.
+# TIER1 needs a target AND a device AND a recorder; TIER2 drops the target and
+# adds MCP; tier 3 is always reachable because "record nothing and say why" is.
+T1=closed; T2=closed
+[ -n "$UI_TEST_TARGET$UI_TEST_TARGETS" ] && [ -n "$DEVICE" ] && [ "$RECORDER" = "true" ] && T1=open
+[ -n "$DEVICE" ] && [ "$RECORDER" = "true" ] && [ "$MCP" = "true" ] && T2=open
+
+# --only device did not look for a target, so tier 1 is UNKNOWN here, not closed.
+# Reporting it closed would be rule 2 broken by the file that states it: a caller
+# re-checking the device before recording would read "tier 1 unavailable" from a
+# measurement that never ran and downgrade a recording it could have made. Tier 2
+# does not depend on the target, so it stays a real verdict.
+[ "$ONLY" = "device" ] && T1=unknown
+
+emit_json() {
+  UI_TEST_TARGET="$UI_TEST_TARGET" UI_TEST_TARGETS="$UI_TEST_TARGETS" \
+  UI_TEST_TARGET_REASON="$UI_TEST_TARGET_REASON" UI_TEST_MATCHES="$UI_TEST_MATCHES" \
+  UI_TEST_MATCH_REASON="$UI_TEST_MATCH_REASON" DEVICE="$DEVICE" DEVICE_REASON="$DEVICE_REASON" \
+  RECORDER="$RECORDER" RECORDER_REASON="$RECORDER_REASON" MCP="$MCP" MCP_REASON="$MCP_REASON" \
+  PLATFORM="$PLATFORM" TIER1="$T1" TIER2="$T2" \
+  node -e '
+    const e = process.env;
+    const list = (s) => (s ? s.split(",").filter(Boolean) : []);
+    const tri = (s) => (s === "true" ? true : s === "false" ? false : null);
+    process.stdout.write(JSON.stringify({
+      platform: e.PLATFORM,
+      uiTestTarget: e.UI_TEST_TARGET || null,
+      uiTestTargets: list(e.UI_TEST_TARGETS),
+      uiTestTargetReason: e.UI_TEST_TARGET_REASON || null,
+      matchingTests: list(e.UI_TEST_MATCHES),
+      matchingTestsReason: e.UI_TEST_MATCH_REASON || null,
+      device: e.DEVICE || null,
+      deviceReason: e.DEVICE_REASON || null,
+      recorder: tri(e.RECORDER),
+      recorderReason: e.RECORDER_REASON || null,
+      mcp: tri(e.MCP),
+      mcpReason: e.MCP_REASON || null,
+      tier1: e.TIER1,
+      tier2: e.TIER2,
+    }, null, 2) + "\n");
+  '
+}
+
+if [ -n "$JSON_OUT" ]; then
+  mkdir -p "$(dirname "$JSON_OUT")" 2>/dev/null || true
+  emit_json > "$JSON_OUT" || {
+    echo "probe-evidence-capability: could not write $JSON_OUT" >&2
+    exit 2
+  }
+fi
+
+if [ "$AS_JSON" -eq 1 ]; then
+  emit_json
+  exit 0
+fi
+
+# Every value is single-quoted, because the caller EVALS this. The reasons are
+# prose - "no booted simulator, but one is available to boot" - and an unquoted
+# assignment makes eval run `booted` as a command and assign the first word. The
+# bug is invisible on a machine where the reasons happen to be empty, which is
+# exactly the machine a developer tests on.
+q() { printf "%s='%s'" "$1" "$(printf '%s' "$2" | sed "s/'/'\\\\''/g")"; printf '\n'; }
+
+q EVIDENCE_PLATFORM "$PLATFORM"
+q EVIDENCE_UI_TEST_TARGET "$UI_TEST_TARGET"
+q EVIDENCE_UI_TEST_TARGETS "$UI_TEST_TARGETS"
+q EVIDENCE_UI_TEST_TARGET_REASON "$UI_TEST_TARGET_REASON"
+q EVIDENCE_MATCHING_TESTS "$UI_TEST_MATCHES"
+q EVIDENCE_MATCHING_TESTS_REASON "$UI_TEST_MATCH_REASON"
+q EVIDENCE_DEVICE "$DEVICE"
+q EVIDENCE_DEVICE_REASON "$DEVICE_REASON"
+q EVIDENCE_RECORDER "$RECORDER"
+q EVIDENCE_RECORDER_REASON "$RECORDER_REASON"
+q EVIDENCE_MCP "$MCP"
+q EVIDENCE_MCP_REASON "$MCP_REASON"
+
+q EVIDENCE_TIER1 "$T1"
+q EVIDENCE_TIER2 "$T2"

package/pipeline/scripts/purge.sh

@@ -231,5 +231,16 @@ fi
 # Drop the now-empty .worktrees/ shell (only when truly empty).
 [ -d "$WT_ROOT" ] && rmdir "$WT_ROOT" 2>/dev/null
 
+# purge is the whole-repo teardown, so it is the one place the managed exclude
+# block should come back out - a per-task finalize must not, because other tasks
+# in the same repo still need the guard. Empty artefact parents go with it.
+# Only the marker-delimited block is removed; lines a human added stay.
+_MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+if [ -f "$_MA_HYG" ]; then
+  . "$_MA_HYG"
+  ma_hygiene_prune_empty "$MAIN_WT"
+  ma_hygiene_release_exclusions "$MAIN_WT"
+fi
+
 echo "══ purge: removed $removed_wt worktree(s) and $removed_br local branch(es) in $MAIN_WT ══"
 exit 0

package/pipeline/scripts/run-ui-tests.sh

@@ -0,0 +1,380 @@
+#!/usr/bin/env bash
+#
+# run-ui-tests.sh  -  find the repo's own UI test target, pick the tests that
+# cover the files this task changed, and run them.
+#
+# Contract: multi-agent-refs/features/visual-evidence.md section 4 (video tier 1).
+#
+# Tier 1 of the flow video is "the repo's own UI test drove the screen". That is
+# worth more than a generated flow for one reason: the test already runs in CI,
+# so the recording shows a path somebody committed to keeping green. This script
+# is the half that finds and runs it; capture-evidence.sh records around it.
+#
+# Two sub-commands, deliberately in one file so detection has exactly one
+# implementation. The capability probe needs the same answer BEFORE the user is
+# asked which test depth to run, and a second copy of "does this repo have a UI
+# test target" is a second place for the answer to drift.
+#
+#   run-ui-tests.sh detect --platform <ios|android> [--repo <path>] [--changed <f>[,<f>...]]
+#       Print KEY=VALUE lines and exit. Never builds, never runs a test.
+#         UI_TEST_TARGET=<name>|            (empty until one candidate is chosen)
+#         UI_TEST_TARGETS=<name[,name...]> (every candidate found)
+#         UI_TEST_TARGET_REASON=<why it is empty>
+#         UI_TEST_MATCHES=<Target/Class[,Target/Class...]>|
+#         UI_TEST_MATCH_REASON=<why it is empty>
+#         UI_TEST_CONTAINER=<-project X|-workspace X>|
+#         UI_TEST_SCHEME=<name>|
+#
+#   run-ui-tests.sh run --platform <ios|android> [--repo <path>] [--changed <f>...]
+#                       [--device <udid|serial>] [--log <path>] [--all]
+#       Run the matching tests (or the whole UI suite with --all).
+#
+# Env:
+#   UI_TEST_LOG   default "$PWD/.pipeline/ui-test.log"
+#
+# Exit:
+#   0  ran, and the run passed
+#   1  ran, and the run failed
+#   2  usage / environment
+#   3  a UI test target exists but nothing matches the changed files
+#   4  no UI test target in this project
+#
+# 3 and 4 are reasons to fall to video tier 2, not failures. Only 1 is a red test.
+set -uo pipefail
+
+MODE="${1:-}"
+shift 2>/dev/null || true
+
+PLATFORM=""; REPO="$PWD"; CHANGED=""; DEVICE=""; LOG=""; RUN_ALL=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform) PLATFORM="${2:-}"; shift 2 ;;
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --changed) CHANGED="${CHANGED:+$CHANGED,}${2:-}"; shift 2 ;;
+    --device) DEVICE="${2:-}"; shift 2 ;;
+    --log) LOG="${2:-}"; shift 2 ;;
+    --all) RUN_ALL=1; shift ;;
+    *) echo "run-ui-tests: unknown option $1" >&2; exit 2 ;;
+  esac
+done
+
+case "$MODE" in detect | run) ;; *)
+  echo "usage: run-ui-tests.sh detect|run --platform <ios|android> [--repo <path>] [--changed <f>]" >&2
+  exit 2 ;;
+esac
+case "$PLATFORM" in ios | android) ;; *)
+  echo "run-ui-tests: unsupported platform '$PLATFORM'" >&2; exit 2 ;;
+esac
+[ -d "$REPO" ] || { echo "run-ui-tests: no such repo directory: $REPO" >&2; exit 2; }
+
+LOG="${LOG:-${UI_TEST_LOG:-$PWD/.pipeline/ui-test.log}}"
+
+TARGET=""; TARGET_REASON=""; TARGETS=""; SOURCES=""
+CONTAINER_ARGV=()
+MATCHES=""; MATCH_REASON=""
+CONTAINER=""; SCHEME=""
+
+# The names a changed UI file can be known by inside a UI test: the type it
+# declares, and the file's own basename. A UI test refers to a screen by its
+# accessibility identifier far more often than by its type name, and identifiers
+# are generated from the same names, so both land on the same string often enough
+# to be worth trying. This is a heuristic and the caller is told so: an empty
+# match set falls to tier 2 rather than claiming the screen is untested.
+changed_names() {
+  # The trailing newline matters: `while read` returns non-zero on an
+  # unterminated final line and drops it, so a one-element list read this way
+  # yields nothing at all and every change looks like it has no testable name.
+  printf '%s\n' "$CHANGED" | tr ',' '\n' | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    b="${f##*/}"
+    printf '%s\n' "${b%.*}"
+  done | sort -u
+}
+
+# Detection reads the filesystem, never `xcodebuild -list`. On a real app
+# workspace that call resolves the SPM graph first and took 72 seconds here,
+# and detection runs at intake while the user is waiting for a question. The
+# scheme it would have told us is only needed to RUN, so it is resolved there,
+# behind a timeout.
+resolve_ios_container() {
+  local ws proj
+  # CONTAINER is reported as text for the detect contract, but the RUN path uses
+  # CONTAINER_ARGV: a checkout under "~/My Projects/" splits an unquoted
+  # -project /path/with space into two arguments and xcodebuild is handed a
+  # project that does not exist.
+  # A standalone .xcworkspace wins, but *.xcodeproj/project.xcworkspace is the
+  # implicit one Xcode keeps inside every project. Passing that to -workspace
+  # builds a different, schemeless container, so it must never be treated as a
+  # workspace the repo chose.
+  ws=$(find "$REPO" -maxdepth 2 -name "*.xcworkspace" -not -path "*/.*" \
+       -not -path "*.xcodeproj/*" 2>/dev/null | head -1)
+  proj=$(find "$REPO" -maxdepth 2 -name "*.xcodeproj" -not -path "*/.*" 2>/dev/null | head -1)
+  if [ -n "$ws" ]; then
+    CONTAINER="-workspace $ws"
+    CONTAINER_ARGV=(-workspace "$ws")
+  elif [ -n "$proj" ]; then
+    CONTAINER="-project $proj"
+    CONTAINER_ARGV=(-project "$proj")
+  fi
+}
+
+# Prune every dotted directory, not a hand-listed few. `.worktrees` is where the
+# pipeline puts other tasks' checkouts: scanning it makes this run match a UI test
+# belonging to somebody else's branch, and the name `worktrees` in a prune list
+# does not match `.worktrees`.
+swift_sources() {
+  find "$REPO" \
+    -name ".*" -type d -prune -o \
+    -type d \( -name .build -o -name Pods -o -name build -o -name DerivedData \
+               -o -name node_modules \) -prune -o \
+    -type f -name "*.swift" -print0 2>/dev/null
+}
+
+# The signal is XCUIApplication, not a directory called *UITests. In the
+# reference app 477 files sit under a *UITests path and exactly 2 drive the UI;
+# the other 475 are snapshot tests, which render a view and compare pixels
+# without ever launching the app. Recording video around one of those produces a
+# still frame and calls it a flow. XCUIApplication is the only API that drives
+# another process's UI, which is precisely the precondition a flow recording has.
+# Computed once into SOURCES by detect_ios, never memoised inside a function: the
+# consumers read it through $(...) and a variable a subshell assigns is gone by
+# the time the parent looks. It is a repo-wide grep, and running it twice put the
+# intake probe at 13 seconds with the user waiting on a question.
+ui_test_sources() {
+  printf '%s\n' "$SOURCES" | grep -v '^$'
+}
+
+# The target is the nearest ancestor directory whose name ends in Tests - the
+# test bundle, by Apple's own template convention. Derived from the path because
+# `xcodebuild -list` costs over a minute on a real workspace and detection runs
+# while the user waits for a question.
+target_of() {
+  printf '%s\n' "$1" | awk -F/ '{
+    for (i = NF - 1; i > 0; i--)
+      if (tolower($i) ~ /tests$/) { print $i; exit }
+  }'
+}
+
+ios_targets() {
+  ui_test_sources | while IFS= read -r f; do target_of "$f"; done | sort -u
+}
+
+detect_ios() {
+  resolve_ios_container
+  [ -n "$CONTAINER" ] || { TARGET_REASON="no xcodeproj or xcworkspace under $REPO"; return; }
+
+  SOURCES=$(swift_sources | xargs -0 grep -l "XCUIApplication" 2>/dev/null)
+  TARGETS=$(ios_targets | paste -sd, -)
+  [ -n "$TARGETS" ] || { TARGET_REASON="no swift test source drives XCUIApplication under $REPO"; return; }
+
+  # One candidate is an answer on its own; several are not, until a match names
+  # one. Reporting a single target when there are several would be the same guess
+  # with a more confident face on it.
+  case "$TARGETS" in
+    *,*) TARGET="" ;;
+    *) TARGET="$TARGETS" ;;
+  esac
+
+  [ -n "$CHANGED" ] || { MATCH_REASON="no changed-file list supplied"; return; }
+
+  local names hits=""
+  names=$(changed_names)
+  [ -n "$names" ] || { MATCH_REASON="changed-file list held no usable names"; return; }
+
+  while IFS= read -r src; do
+    [ -n "$src" ] || continue
+    local tgt cls
+    tgt=$(target_of "$src")
+    [ -n "$tgt" ] || continue
+    cls=$(grep -oE 'class[[:space:]]+[A-Za-z0-9_]+' "$src" 2>/dev/null | head -1 | awk '{print $2}')
+    [ -n "$cls" ] || continue
+    while IFS= read -r n; do
+      [ -n "$n" ] || continue
+      if grep -qF "$n" "$src" 2>/dev/null; then
+        case ",$hits," in *",$tgt/$cls,"*) ;; *) hits="${hits:+$hits,}$tgt/$cls" ;; esac
+        break
+      fi
+    done <<EOF
+$names
+EOF
+  done <<EOF
+$(ui_test_sources)
+EOF
+
+  MATCHES="$hits"
+  if [ -n "$MATCHES" ]; then
+    [ -n "$TARGET" ] || TARGET="${MATCHES%%/*}"
+  else
+    MATCH_REASON="no UI test class mentions any changed file name"
+    [ -n "$TARGET" ] || TARGET_REASON="$(printf '%s\n' "$TARGETS" | tr ',' '\n' | wc -l | tr -d ' ') candidates and no match to choose between them"
+  fi
+}
+
+android_test_dirs() {
+  find "$REPO" \
+    -name ".*" -type d -prune -o \
+    -type d -name build -prune -o \
+    -type d -name "androidTest" -print 2>/dev/null
+}
+
+# module path -> Gradle task path, e.g. feature/auth/impl -> :feature:auth:impl
+android_module_of() {
+  printf '%s\n' "${1#"$REPO"/}" | sed 's#/src/androidTest.*##; s#^#:#; s#/#:#g'
+}
+
+detect_android() {
+  local dirs
+  dirs=$(android_test_dirs)
+  [ -n "$dirs" ] || { TARGET_REASON="no src/androidTest source set under $REPO"; return; }
+
+  CONTAINER="$REPO"
+  TARGETS=$(printf '%s\n' "$dirs" | while IFS= read -r d; do
+    [ -n "$d" ] || continue
+    printf '%s:connectedAndroidTest\n' "$(android_module_of "$d")"
+  done | sort -u | paste -sd, -)
+
+  # Same rule as iOS: several candidates is not an answer until a match picks
+  # one. The reference app has eight instrumentation source sets.
+  case "$TARGETS" in
+    *,*) TARGET="" ;;
+    *) TARGET="$TARGETS"; SCHEME="${TARGET%:connectedAndroidTest}" ;;
+  esac
+
+  [ -n "$CHANGED" ] || { MATCH_REASON="no changed-file list supplied"; return; }
+
+  local names hits="" hit_target=""
+  names=$(changed_names)
+  [ -n "$names" ] || { MATCH_REASON="changed-file list held no usable names"; return; }
+
+  while IFS= read -r src; do
+    [ -n "$src" ] || continue
+    local cls pkg
+    cls=$(grep -oE 'class[[:space:]]+[A-Za-z0-9_]+' "$src" 2>/dev/null | head -1 | awk '{print $2}')
+    pkg=$(grep -oE '^package[[:space:]]+[A-Za-z0-9_.]+' "$src" 2>/dev/null | head -1 | awk '{print $2}')
+    [ -n "$cls" ] || continue
+    while IFS= read -r n; do
+      [ -n "$n" ] || continue
+      if grep -qF "$n" "$src" 2>/dev/null; then
+        local fq="${pkg:+$pkg.}$cls"
+        case ",$hits," in *",$fq,"*) ;; *) hits="${hits:+$hits,}$fq" ;; esac
+        # The module that owns the matched test is the one to run.
+        [ -n "$hit_target" ] || hit_target="$(android_module_of "$src"):connectedAndroidTest"
+        break
+      fi
+    done <<EOF
+$names
+EOF
+  done <<EOF
+$(android_test_dirs | while IFS= read -r d; do find "$d" -type f \( -name "*.kt" -o -name "*.java" \) 2>/dev/null; done)
+EOF
+
+  MATCHES="$hits"
+  if [ -n "$MATCHES" ]; then
+    [ -n "$TARGET" ] || { TARGET="$hit_target"; SCHEME="${TARGET%:connectedAndroidTest}"; }
+  else
+    MATCH_REASON="no instrumentation test class mentions any changed file name"
+    [ -n "$TARGET" ] || TARGET_REASON="$(printf '%s\n' "$TARGETS" | tr ',' '\n' | wc -l | tr -d ' ') candidates and no match to choose between them"
+  fi
+}
+
+case "$PLATFORM" in
+  ios) detect_ios ;;
+  android) detect_android ;;
+esac
+
+if [ "$MODE" = "detect" ]; then
+  printf 'UI_TEST_TARGET=%s\n' "$TARGET"
+  printf 'UI_TEST_TARGETS=%s\n' "$TARGETS"
+  printf 'UI_TEST_TARGET_REASON=%s\n' "$TARGET_REASON"
+  printf 'UI_TEST_MATCHES=%s\n' "$MATCHES"
+  printf 'UI_TEST_MATCH_REASON=%s\n' "$MATCH_REASON"
+  printf 'UI_TEST_CONTAINER=%s\n' "$CONTAINER"
+  printf 'UI_TEST_SCHEME=%s\n' "$SCHEME"
+  exit 0
+fi
+
+# run
+#
+# 4 and 3 are different facts and the caller acts on them differently: 4 means
+# this repo has nothing to record a flow from, 3 means it does but nothing covers
+# what changed. Keying 4 off TARGET rather than TARGETS conflated them, because
+# TARGET is deliberately empty while several candidates exist and no match has
+# chosen between them.
+[ -n "$TARGETS$TARGET" ] || { echo "run-ui-tests: ${TARGET_REASON:-no ui test target}" >&2; exit 4; }
+if [ -z "$MATCHES" ] && [ "$RUN_ALL" -eq 0 ]; then
+  echo "run-ui-tests: ${MATCH_REASON:-no matching test}" >&2
+  exit 3
+fi
+[ -n "$TARGET" ] || {
+  echo "run-ui-tests: ${TARGET_REASON:-several candidates and no match to choose between them}" >&2
+  exit 3
+}
+
+mkdir -p "$(dirname "$LOG")"
+
+case "$PLATFORM" in
+  ios)
+    ONLY_ARGV=()
+    if [ "$RUN_ALL" -eq 0 ]; then
+      OLDIFS="$IFS"; IFS=','
+      for m in $MATCHES; do ONLY_ARGV+=("-only-testing:$m"); done
+      IFS="$OLDIFS"
+    else
+      ONLY_ARGV=("-only-testing:$TARGET")
+    fi
+    # The scheme is resolved here and not in detect: `xcodebuild -list` walks the
+    # SPM graph and can take over a minute on a real app, which detect cannot
+    # afford. Behind a timeout, because a resolver that hangs would otherwise hang
+    # the phase; on timeout fall back to the target name, which is the scheme name
+    # under Apple's own template.
+    if [ -z "$SCHEME" ]; then
+      TO=""
+      command -v timeout >/dev/null 2>&1 && TO="timeout 180"
+      # shellcheck disable=SC2086
+      LIST=$(cd "$REPO" && $TO xcodebuild -list -json "${CONTAINER_ARGV[@]}" 2>/dev/null)
+      SCHEME=$(printf '%s' "$LIST" | node -e '
+        let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{
+          let j={}; try{j=JSON.parse(s)}catch{ process.exit(0) }
+          const c=j.project||j.workspace||{};
+          const sch=c.schemes||[];
+          process.stdout.write(sch.find(n=>/uitests?$/i.test(n))||sch[0]||"");
+        });' 2>/dev/null)
+      [ -n "$SCHEME" ] || SCHEME="$TARGET"
+    fi
+
+    # `id=booted` is not a destination xcodebuild accepts, so resolve the udid
+    # rather than assigning a placeholder and hoping it is overwritten.
+    if [ -z "$DEVICE" ]; then
+      DEVICE=$(xcrun simctl list devices booted 2>/dev/null | grep -oE '[0-9A-F-]{36}' | head -1)
+      [ -n "$DEVICE" ] || { echo "run-ui-tests: no booted simulator and no --device" >&2; exit 2; }
+    fi
+    DEST="platform=iOS Simulator,id=$DEVICE"
+    (cd "$REPO" && xcodebuild test "${CONTAINER_ARGV[@]}" -scheme "$SCHEME" \
+      -destination "$DEST" "${ONLY_ARGV[@]}") >"$LOG" 2>&1
+    RC=$?
+    ;;
+  android)
+    command -v adb >/dev/null 2>&1 || { echo "run-ui-tests: adb unavailable" >&2; exit 2; }
+    adb shell true >/dev/null 2>&1 || { echo "run-ui-tests: no attached device" >&2; exit 2; }
+    GRADLE="$REPO/gradlew"
+    [ -x "$GRADLE" ] || { echo "run-ui-tests: no executable gradlew at $GRADLE" >&2; exit 2; }
+    ARGS=""
+    if [ "$RUN_ALL" -eq 0 ]; then
+      ARGS="-Pandroid.testInstrumentationRunnerArguments.class=$MATCHES"
+    fi
+    # shellcheck disable=SC2086
+    (cd "$REPO" && "$GRADLE" "$TARGET" $ARGS) >"$LOG" 2>&1
+    RC=$?
+    ;;
+esac
+
+printf 'UI_TEST_LOG=%s\n' "$LOG"
+printf 'UI_TEST_SELECTED=%s\n' "${MATCHES:-$TARGET}"
+
+# The exit code alone is not the verdict here for the same reason it is not one
+# for the build: a runner that died before it reached the tests also exits
+# non-zero, and a caller that reads only the code cannot tell "the UI test found
+# a bug" from "the simulator never booted". The log is the evidence; the caller
+# runs evidence-gate.mjs over it.
+[ "$RC" -eq 0 ] && exit 0
+exit 1

package/pipeline/scripts/worktree-finalize.sh

@@ -318,6 +318,15 @@ if git -C "$rp_pr" worktree remove "$rp_wt" 2>/dev/null; then
     ' 2>/dev/null || true
   fi
 
+  # The worktree is gone, but its parent `.worktrees/` stays behind as an empty
+  # directory and reads as leftover to anyone looking at the checkout. rmdir,
+  # never rm -rf: it fails harmlessly while any other task still has one.
+  _MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+  if [ -f "$_MA_HYG" ]; then
+    . "$_MA_HYG"
+    ma_hygiene_prune_empty "$rp_pr"
+  fi
+
   emit
   exit 0
 fi