@techierathore/techieflow 1.1.0 → 1.2.0

package/.tfcore/utils/tf-verify-boot.sh

@@ -13,15 +13,30 @@
 #            side that built it, reading its settings from the project folder as `dotnet run` does.
 #            Builders side by side never serve each other's half-written build (TF-043). A standalone
 #            WebAssembly project is still started with `dotnet run`. Prints BOOTED mode=base url=….
-#   windows  a MAUI Blazor Hybrid head (UseMaui + a net*-windows target): started Windows-side with
+#   windows  a MAUI Blazor Hybrid head (UseMaui + a net*-windows target + a BlazorWebView; a plain MAUI
+#            app is refused at once, NONE kind=no-webview, TechieRag TF-006): started Windows-side with
 #            WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222, the DevTools port
 #            relayed to every interface by tf-cdp-relay.ps1, and reached from WSL over CDP. Prints
 #            BOOTED mode=cdp url=http://<host>:9223. Proven on MyDiary, 2026-09-06.
 #   static   a folder of HTML served by python3 (the framework self-test, a mockup set).
-#   android, ios, maccatalyst: no driver ships in this framework version. NONE with that reason;
-#            their rows are recorded as not verified, never as static-only passes.
-# Without --head the script picks web when a web project exists, else windows when a MAUI project
-# with a windows target exists, else NONE. --project names the project when there are several.
+#   maccatalyst  a MAUI project with a net*-maccatalyst target, on a Mac only: built by tf-build.sh,
+#            its .app started here, and reached over Appium's mac2 driver at the address in
+#            core-config.yaml runtimeVerification.appium.maccatalyst.url (default
+#            http://localhost:4723; a local Appium that is down is started and later stopped).
+#            Prints BOOTED mode=appium url=<appium> bundle=<id>. An SDK that names an older Xcode
+#            is built again with -p:ValidateXcodeVersion=false, and the state says so. A Blazor Hybrid
+#            head is driven without control names (its data-testid is not readable on a Mac): the
+#            state says webview, and those rows say the name check was not measured.
+#            BOOTED only once a mac2 session has opened and the app shows a window of its own, not a
+#            system dialog; that window is saved as boot-<port>-window.png (Lekhak TF-026). Before the
+#            build it checks the two things a fresh macOS 27 / Xcode 27 machine lacks, and names the fix:
+#            Automation Mode allowed without a password, and a mac2 driver new enough for this Xcode.
+#            `stop` quits the app as Cmd-Q does, and kills it only when it has not quit in 15 s.
+#   android, ios: no driver ships in this framework version. NONE with that reason; their rows
+#            are recorded as not verified, never as static-only passes.
+# Without --head the script picks web when a web project exists, else (on a Mac) maccatalyst when a
+# MAUI project with that target exists, else windows when a MAUI project with a windows target
+# exists, else NONE. --project names the project when there are several.
 # The state goes to tests/.artifacts/verify/boot-<port>.json and the app log to app-<port>.log, one pair
 # per app, so builders booting side by side never empty or stop each other's (TF-034); boot.json is a
 # copy of the latest start's, which the verdict reads. `stop --port N` stops that app only; a bare
@@ -71,6 +86,14 @@ find_projects() { # prints csproj paths under src/, source/, the root and one le
 }
 is_web()  { grep -qE 'Microsoft\.NET\.Sdk\.Web|Microsoft\.NET\.Sdk\.BlazorWebAssembly' "$1"; }
 is_maui_win() { grep -qiE '<UseMaui>[[:space:]]*true|Microsoft\.NET\.Sdk\.Maui' "$1" && grep -qE 'net[0-9.]+-windows' "$1"; }
+# A Windows head is driven over its web view's DevTools port, so only a Blazor Hybrid app has one. A
+# plain MAUI app (TechieRag's samples/TechieRag.Probe) was picked as the windows head and waited the
+# full 300 s for a port it can never open (TechieRag TF-006).
+is_hybrid() {
+  grep -qE 'Microsoft\.AspNetCore\.Components\.WebView\.Maui' "$1" && return 0
+  grep -rqlE 'AddMauiBlazorWebView|BlazorWebView' --include='*.cs' --include='*.xaml' --exclude-dir=bin --exclude-dir=obj "$(dirname "$1")" 2>/dev/null
+}
+is_maui_mac() { grep -qiE '<UseMaui>[[:space:]]*true|Microsoft\.NET\.Sdk\.Maui' "$1" && grep -qE 'net[0-9.]+-maccatalyst' "$1"; }
 
 poll_http() { # url seconds pid-to-watch(optional) -> 0 when it answers
   local url="$1" secs="$2" pid="${3:-}" i=0 code
@@ -129,6 +152,24 @@ d, port = sys.argv[1], sys.argv[2]
 main = os.path.join(d, "boot.json")
 path = os.path.join(d, f"boot-{port}.json") if port else main
 s = json.load(open(path))
+# A Mac Catalyst head is quit the way Cmd-Q quits it. Killed, macOS offered at the next start to reopen
+# the windows of a run that "quit unexpectedly", and that dialog stood in front of the first screen
+# (Lekhak TF-026). It is killed below only when it has not quit within 15 s.
+if s.get("bundle_id") and s.get("app_path") and not s.get("stopped"):
+    exe_dir = os.path.join(s["app_path"], "Contents", "MacOS") + os.sep
+    def mac_running():
+        out = subprocess.run(["ps", "-A", "-ww", "-o", "command="], capture_output=True).stdout.decode(errors="replace")
+        return any(exe_dir in line for line in out.splitlines())
+    if mac_running():
+        bid = s["bundle_id"].replace('"', "")
+        try:
+            subprocess.run(["osascript", "-e", f'if application id "{bid}" is running then tell application id "{bid}" to quit'], capture_output=True, timeout=30)
+        except Exception:
+            pass
+        for _ in range(15):
+            if not mac_running():
+                break
+            time.sleep(1)
 for pid in s.get("pids", []):
     for sig in (signal.SIGTERM, signal.SIGKILL):
         try:
@@ -140,8 +181,23 @@ for pid in s.get("pids", []):
             pass
         time.sleep(1)
 image = s.get("win_image") or ""
-if image:
-    subprocess.run(["taskkill.exe", "/F", "/T", "/IM", image], capture_output=True)
+if s.get("win_pids"):
+    # this boot's own processes only (Sevak TF-003: /IM stopped every copy, another agent's included)
+    for wp in s["win_pids"]:
+        subprocess.run(["taskkill.exe", "/F", "/T", "/PID", str(wp)], capture_output=True)
+elif image:
+    # a state written before win_pids: by name, as before, unless another start of it is still up
+    others = []
+    for f in os.listdir(d):
+        if f.startswith("boot-") and f.endswith(".json") and os.path.join(d, f) != path:
+            try:
+                o = json.load(open(os.path.join(d, f)))
+                if o.get("win_image") == image and not o.get("stopped") and o.get("pids") != s.get("pids"):
+                    others.append(f)
+            except Exception:
+                pass
+    if not others:
+        subprocess.run(["taskkill.exe", "/F", "/T", "/IM", image], capture_output=True)
 if s.get("win_port"):
     ps = f"Get-NetTCPConnection -LocalPort {s['win_port']} -State Listen -ErrorAction SilentlyContinue | ForEach-Object {{ Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }}"
     subprocess.run(["powershell.exe", "-NoProfile", "-Command", ps], capture_output=True)
@@ -149,8 +205,12 @@ if s.get("win_port"):
 # port and its files. The published copy names it: stop whatever runs from run-<port>/ (TF-043).
 m = re.search(r":(\d+)$", s.get("url") or "")
 run_port = port or (m.group(1) if m else "")
-if run_port:
-    mark = os.path.join(os.getcwd(), d, f"run-{run_port}") + os.sep
+marks = [os.path.join(os.getcwd(), d, f"run-{run_port}") + os.sep] if run_port else []
+# A Mac Catalyst head: opening an Appium session starts the app again under a new process, so the
+# pid written at boot is gone and the app is not; stop whatever runs from this boot's .app.
+if s.get("app_path"):
+    marks.append(os.path.join(s["app_path"], "Contents", "MacOS") + os.sep)
+if marks:
     try:
         procs = [p for p in os.listdir("/proc") if p.isdigit()]
     except Exception:
@@ -173,7 +233,7 @@ if run_port:
             if pid.isdigit():
                 cmds.append((int(pid), cmd))
     for pid, cmd in cmds:
-        if mark in cmd and pid != os.getpid():
+        if any(mk in cmd for mk in marks) and pid != os.getpid():
             try:
                 os.kill(pid, signal.SIGKILL)
             except Exception:
@@ -194,7 +254,7 @@ print(f"STOPPED head={s.get('head')} mode={s.get('mode')} pids={s.get('pids')}")
 PY
     exit 0 ;;
   start) ;;
-  *) sed -n '2,30p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 3 ;;
+  *) sed -n '2,39p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 3 ;;
 esac
 
 HEAD=""; PROJECT=""; PORT=""; CONFIG=""; STATIC=""; PROBE="/"; DRYRUN=0; ENVNAME=""
@@ -232,8 +292,14 @@ fi
 
 # ---- pick the project and the head ------------------------------------------------------
 tf_read_lines ALL < <(find_projects)
-WEB=(); WIN=()
-for p in ${ALL[@]+"${ALL[@]}"}; do is_web "$p" && WEB+=("$p"); is_maui_win "$p" && WIN+=("$p"); done
+WEB=(); WIN=(); MAC=()
+WIN_NATIVE=()
+for p in ${ALL[@]+"${ALL[@]}"}; do
+  is_web "$p" && WEB+=("$p"); is_maui_mac "$p" && MAC+=("$p")
+  if is_maui_win "$p"; then if is_hybrid "$p"; then WIN+=("$p"); else WIN_NATIVE+=("$p"); fi; fi
+done
+# a Mac Catalyst head is picked unasked only on a Mac, the one host that runs it
+[[ "$PLATFORM" == "macos" ]] || MAC=()
 # Several web projects: the one that serves screens. The first in sorted order booted AppManager's
 # external API, which has no screens, in front of its admin site (AppManager TF-010). A project
 # serves screens when its own folder holds .razor or .cshtml pages, or it references a project
@@ -263,18 +329,31 @@ pick_web() { # sets PROJECT from WEB, or prints NONE and exits
 }
 if [[ -n "$PROJECT" ]]; then
   [[ -f "$PROJECT" ]] || { echo "NONE reason=--project $PROJECT does not exist"; exit 3; }
-  if [[ -z "$HEAD" ]]; then is_web "$PROJECT" && HEAD=web; [[ -z "$HEAD" ]] && is_maui_win "$PROJECT" && HEAD=windows; fi
+  if [[ -z "$HEAD" ]]; then
+    is_web "$PROJECT" && HEAD=web
+    [[ -z "$HEAD" && "$PLATFORM" == "macos" ]] && is_maui_mac "$PROJECT" && HEAD=maccatalyst
+    [[ -z "$HEAD" ]] && is_maui_win "$PROJECT" && HEAD=windows
+  fi
 elif [[ -z "$HEAD" ]]; then
   if [[ ${#WEB[@]} -gt 0 ]]; then HEAD=web; pick_web
-  elif [[ ${#WIN[@]} -gt 0 ]]; then HEAD=windows; PROJECT="${WIN[0]}"; fi
+  elif [[ ${#MAC[@]} -gt 0 ]]; then HEAD=maccatalyst; PROJECT="${MAC[0]}"
+  elif [[ ${#WIN[@]} -gt 0 ]]; then HEAD=windows; PROJECT="${WIN[0]}"
+  elif [[ ${#WIN_NATIVE[@]} -gt 0 ]]; then HEAD=windows; PROJECT="${WIN_NATIVE[0]}"; fi
 else
-  case "$HEAD" in web) pick_web ;; windows) PROJECT="${WIN[0]:-}" ;; esac
+  case "$HEAD" in web) pick_web ;; windows) PROJECT="${WIN[0]:-${WIN_NATIVE[0]:-}}" ;; maccatalyst) PROJECT="${MAC[0]:-}" ;; esac
+fi
+if [[ "$HEAD" == windows && -n "$PROJECT" ]] && ! is_hybrid "$PROJECT"; then
+  [[ $DRYRUN -eq 1 ]] || write_state windows none "" "" "" "$PROJECT" "a MAUI app with no BlazorWebView: no web view, not drivable over CDP" no-webview "$PLATFORM"
+  echo "NONE head=windows kind=no-webview reason=$PROJECT is a MAUI app with no BlazorWebView (no AddMauiBlazorWebView, no <BlazorWebView>): it has no web view, so it is not drivable over CDP; its rows are graded by their tests"; exit 2
 fi
 if [[ $DRYRUN -eq 1 ]]; then echo "PICK head=${HEAD:-none} project=${PROJECT:-none}"; exit 0; fi
 case "$HEAD" in
-  android|ios|maccatalyst)
+  android|ios)
     write_state "$HEAD" none "" "" "" "${PROJECT:-}" "no driver for the $HEAD head ships in this framework version" no-driver "$PLATFORM"
     echo "NONE head=$HEAD reason=no driver for the $HEAD head ships in this framework version; its rows are recorded as not verified"; exit 2 ;;
+  maccatalyst)
+    [[ "$PLATFORM" == "macos" ]] || { write_state maccatalyst none "" "" "" "${PROJECT:-}" "a Mac Catalyst head runs only on a Mac" host "$PLATFORM"
+      echo "NONE head=maccatalyst kind=host reason=a Mac Catalyst head runs only on a Mac, this is $PLATFORM"; exit 2; } ;;
   web|windows) ;;
   "") write_state none none "" "" "" "" "no web project and no MAUI project with a windows target found under src/, source/ or the root" host "$PLATFORM"
       echo "NONE head=none reason=no web project (Microsoft.NET.Sdk.Web) and no MAUI project with a windows target found; name one with --project"; exit 2 ;;
@@ -285,6 +364,165 @@ PDIR="$(dirname "$PROJECT")"; PNAME="$(basename "$PROJECT" .csproj)"
 ASM="$(grep -oE '<AssemblyName>[^<]+' "$PROJECT" 2>/dev/null | head -1 | sed 's/<AssemblyName>//')"; ASM="${ASM:-$PNAME}"
 CFGARGS=(); [[ -n "$CONFIG" ]] && CFGARGS=(-c "$CONFIG")
 
+# ---- maccatalyst (MAUI on this Mac, reached over Appium's mac2 driver) -----------------------
+if [[ "$HEAD" == "maccatalyst" ]]; then
+  # A Blazor Hybrid head draws its screens in a web view, and on a Mac neither data-testid nor an
+  # HTML id reaches mac2 or the macOS accessibility tree (probed 2026-10-07). It is driven all the
+  # same, without control names (owner decision A): the state says webview, the screen check skips
+  # the name check, and the verdict writes it as not measured.
+  WEBVIEW=0; grep -q 'Microsoft\.AspNetCore\.Components\.WebView\.Maui' "$PROJECT" && WEBVIEW=1
+  TFM="$(grep -oE 'net[0-9.]+-maccatalyst[0-9.]*' "$PROJECT" | head -1)"
+  # the endpoint the app registers (an uncommented maccatalyst: entry with a url), else this Mac
+  AURL="$(python3 - <<'PY'
+import re
+try:
+    t = open(".tfcore/core-config.yaml", encoding="utf-8").read()
+except Exception:
+    t = ""
+m = re.search(r"(?m)^[ \t]+maccatalyst:[ \t]*(?:\{[^}\n]*url:[ \t]*([^,}\s]+)|\n[ \t]+url:[ \t]*(\S+))", t)
+print((m.group(1) or m.group(2)) if m else "")
+PY
+)"
+  AURL="${AURL:-http://localhost:4723}"; AURL="${AURL%/}"
+  APORT="${AURL##*:}"; [[ "$APORT" =~ ^[0-9]+$ ]] || APORT=4723
+  keyed "$APORT"
+  mac_none() { # reason: a host fault found before anything was started
+    write_state maccatalyst none "" "" "" "$PROJECT" "$1" host "$PLATFORM"
+    echo "NONE head=maccatalyst kind=host reason=$1"; exit 2; }
+  # Lekhak TF-026: two set-up faults of a fresh macOS 27 / Xcode 27 machine, each of which stopped every
+  # mac2 session with an error that does not name its fix. Checked here, before a build of minutes.
+  # 1. mac2 turns Automation Mode on for each session; when that needs a password it never comes, and
+  #    the session fails with "Timed out while enabling automation mode".
+  if command -v automationmodetool >/dev/null 2>&1 && automationmodetool 2>&1 | grep -q '^This device REQUIRES user authentication'; then
+    mac_none "macOS asks for a password before Automation Mode comes on, so no mac2 session can open. Run once, with an administrator password: sudo automationmodetool enable-automationmode-without-authentication"
+  fi
+  # 2. mac2 builds its WebDriverAgentMac with the Xcode on this Mac. Before 4.1.1 that build fails
+  #    under Xcode 27 (deployment target 10.15 below its 12.0 minimum, xcodebuild exit 65). An
+  #    `appium driver update mac2` left the driver unloadable ("Cannot find package 'appium'");
+  #    uninstalling and installing again is what worked.
+  if command -v appium >/dev/null 2>&1; then
+    M2="$(appium driver list --installed --json 2>/dev/null | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("mac2", {}).get("version", ""))
+except Exception: print("?")' 2>/dev/null)"
+    XMAJ="$(xcodebuild -version 2>/dev/null | sed -n 's/^Xcode \([0-9]*\).*/\1/p' | head -1)"
+    REINSTALL="appium driver uninstall mac2; appium driver install mac2"
+    if [[ -z "$M2" ]]; then
+      mac_none "Appium's mac2 driver is not installed. Run: appium driver install mac2"
+    elif [[ "$M2" != "?" && "${XMAJ:-0}" -ge 27 ]] && python3 -c 'import sys
+v = tuple(int(x) for x in sys.argv[1].split("-")[0].split(".")[:3])
+sys.exit(0 if v < (4, 1, 1) else 1)' "$M2"; then
+      mac_none "the mac2 driver $M2 cannot build its helper with Xcode $XMAJ (4.1.1 is the first that can). Run: $REINSTALL"
+    fi
+  fi
+  ready() { curl -s -m 3 "$AURL/status" 2>/dev/null | grep -q '"ready":true'; }
+  APPIUM_PID=""
+  if ! ready; then
+    # boot it yourself: a local Appium that is down is started here and stopped by `stop`
+    if [[ "$AURL" =~ ^http://(localhost|127\.0\.0\.1): ]] && command -v appium >/dev/null 2>&1; then
+      nohup appium --address 127.0.0.1 --port "$APORT" > "$DIR/appium-$APORT.log" 2>&1 < /dev/null &
+      APPIUM_PID=$!; i=0
+      while [[ $i -lt 60 ]] && ! ready; do sleep 2; i=$((i+2)); done
+    fi
+    if ! ready; then
+      [[ -n "$APPIUM_PID" ]] && kill "$APPIUM_PID" 2>/dev/null
+      write_state maccatalyst none "" "" "" "$PROJECT" "Appium did not answer at $AURL/status" host "$PLATFORM"
+      echo "NONE head=maccatalyst kind=host reason=Appium did not answer at $AURL/status$([[ -z "$APPIUM_PID" ]] && ! command -v appium >/dev/null 2>&1 && echo '; appium is not installed (docs/TechieFlow-Setup.md §0b step 3)')"; exit 2
+    fi
+  fi
+  stop_appium() { [[ -n "$APPIUM_PID" ]] && kill "$APPIUM_PID" 2>/dev/null; }
+  # the Mac rules first (coding-standards-dotnet.md §9): a missing scene manifest is stopped here,
+  # before a build that macOS 27 would end at the first window; a WARN is printed and the boot goes on
+  chk="$(bash "$HERE/tf-maccatalyst-check.sh" "$PROJECT" 2>&1)"; crc=$?
+  printf '%s\n' "$chk" >> "$LOG"; grep -E '^WARN' <<<"$chk" >&2
+  OSMAJOR="$(sw_vers -productVersion 2>/dev/null | cut -d. -f1)"
+  if [[ $crc -eq 1 && "${OSMAJOR:-0}" -ge 27 ]]; then
+    stop_appium; first="$(grep -m1 -E '^FAIL' <<<"$chk" | sed -E 's/^FAIL [^:]+: //')"
+    write_state maccatalyst none "" "" "tf-maccatalyst-check.sh" "$PROJECT" "$first" build-error "$PLATFORM"
+    echo "NONE head=maccatalyst kind=build-error reason=$first (bash .tfcore/utils/tf-maccatalyst-check.sh)"; exit 2
+  fi
+  [[ $crc -eq 1 ]] && grep -E '^FAIL' <<<"$chk" | sed 's/^FAIL/WARN (fatal from macOS 27)/' >&2
+  BARGS=(-f "$TFM" -c "${CONFIG:-Debug}")
+  echo "### build $PROJECT -f $TFM" >> "$LOG"
+  out="$(bash "$HERE/tf-build.sh" build "$PROJECT" -- "${BARGS[@]}" 2>&1)"; brc=$?
+  # A Mac Catalyst SDK names the one Xcode it was made for and refuses a newer one; tf-build.sh builds
+  # again with the check off and says so in a note line (Lekhak TF-032), which the state carries.
+  XNOTE="$(grep -oE 'requires Xcode [0-9.]+[.] The current version of Xcode is [0-9.]+' <<<"$(grep '^note' <<<"$out")" | head -1)"
+  printf '%s\n' "$out" >> "$LOG"
+  verdict="$(grep -E '^(PASS|FAIL|NOT-RUN)' <<<"$out" | tail -1)"
+  if [[ $brc -ne 0 ]]; then
+    stop_appium
+    kind=host; [[ $brc -eq 1 ]] && kind=build-error
+    write_state maccatalyst none "" "" "tf-build.sh build -f $TFM" "$PROJECT" "${verdict:-the build failed}" "$kind" "$PLATFORM"
+    echo "NONE head=maccatalyst kind=$kind reason=${verdict:-the build failed} (log $LOG)"; exit 2
+  fi
+  APP="$(ls -td "$PDIR/bin/${CONFIG:-Debug}/$TFM"/*.app "$PDIR/bin/${CONFIG:-Debug}/$TFM"/*/*.app 2>/dev/null | head -1)"
+  if [[ -z "$APP" ]]; then
+    stop_appium; write_state maccatalyst none "" "" "tf-build.sh build -f $TFM" "$PROJECT" "the build wrote no .app under $PDIR/bin/${CONFIG:-Debug}/$TFM" host "$PLATFORM"
+    echo "NONE head=maccatalyst kind=host reason=the build wrote no .app under $PDIR/bin/${CONFIG:-Debug}/$TFM (log $LOG)"; exit 2
+  fi
+  APP="$(cd "$APP" && pwd)"
+  BUNDLE="$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$APP/Contents/Info.plist" 2>/dev/null)"
+  EXE="$(/usr/libexec/PlistBuddy -c 'Print CFBundleExecutable' "$APP/Contents/Info.plist" 2>/dev/null)"
+  if OLD="$(pgrep -f "$APP/Contents/MacOS/$EXE" | head -1)" && [[ -n "$OLD" ]]; then
+    stop_appium; write_state maccatalyst none "" "" "" "$PROJECT" "another copy of $EXE is already running (pid $OLD)" host "$PLATFORM"
+    echo "NONE head=maccatalyst kind=host reason=another copy of $EXE is already running (pid $OLD), and mac2 would attach to either; stop it first"; exit 2
+  fi
+  MARK="$DIR/.launch-$APORT"; : > "$MARK"; ROOT_LOG="$PWD/$LOG"
+  # Opened the way Finder opens it: macOS kills a sandboxed app started from its binary directly
+  # ("Killed: 9", Lekhak BlogAdmin, 2026-10-07). Its output goes to the log through open's own options.
+  # -ApplePersistenceIgnoreState: never offer to reopen the windows of an earlier run (Lekhak TF-026)
+  OPENERR="$(open -n -o "$ROOT_LOG" --stderr "$ROOT_LOG" "$APP" --args -ApplePersistenceIgnoreState YES 2>&1)"; printf '%s\n' "$OPENERR" >> "$LOG"
+  APP_PID=""; i=0
+  while [[ $i -lt 10 && -z "$APP_PID" ]]; do sleep 1; i=$((i+1)); APP_PID="$(pgrep -f "$APP/Contents/MacOS/$EXE" | head -1)"; done
+  i=0; while [[ -n "$APP_PID" && $i -lt 8 ]] && kill -0 "$APP_PID" 2>/dev/null; do sleep 1; i=$((i+1)); done
+  if [[ -z "$APP_PID" ]] || ! kill -0 "$APP_PID" 2>/dev/null; then
+    stop_appium
+    crash="$(find "$HOME/Library/Logs/DiagnosticReports" -name "$EXE-*.ips" -newer "$MARK" 2>/dev/null | head -1)"
+    hint=""; grep -qs NoSceneLifecycleAdoption "$crash" && hint="; macOS stops a UIKit app that has not adopted scenes: add UIApplicationSceneManifest to Platforms/MacCatalyst/Info.plist and a SceneDelegate : MauiUISceneDelegate"
+    # macOS refused to start it at all (Lekhak BlogAdmin, 2026-10-07: "Launch failed", POSIX 163): a
+    # locally signed build that asks for keychain-access-groups, which needs a provisioning profile
+    if grep -q 'Launch failed' <<<"$OPENERR"; then
+      hint="; macOS refused to start it ($(grep -oE 'Code=[0-9]+ "[^"]*"' <<<"$OPENERR" | tail -1))"
+      codesign -d --entitlements :- "$APP" 2>/dev/null | grep -q keychain-access-groups && hint="$hint: the build is signed locally (ad hoc) and asks for keychain-access-groups, which needs a provisioning profile; leave that entitlement out of Debug builds or set CodesignProvisioningProfile"
+    fi
+    write_state maccatalyst none "" "" "tf-build.sh build -f $TFM" "$PROJECT" "the app quit on start${crash:+ (crash report $crash)}$hint" build-error "$PLATFORM"
+    echo "NONE head=maccatalyst kind=build-error reason=the app quit on start${crash:+ (crash report $crash)}$hint (log $LOG)"; exit 2
+  fi
+  write_state maccatalyst appium "$AURL" "$APP_PID $APPIUM_PID" "tf-build.sh build -f $TFM" "$PROJECT" "" "" "$PLATFORM"
+  set_state bundle_id "$(json_escape "$BUNDLE")"
+  set_state app_path "$(json_escape "$APP")"
+  # Lekhak TF-026: a running process and an answering Appium are not a boot. A mac2 session has to open
+  # and find the app's own window on view, not a system dialog, before this says BOOTED.
+  SHOT="$PWD/$DIR/boot-$APORT-window.png"
+  FIRST="$(TF_A="$AURL" TF_B="$BUNDLE" TF_P="$APP" TF_S="$SHOT" node --input-type=module -e "
+import { firstScreen } from '$HERE/tf-appium.mjs';
+const r = await firstScreen(process.env.TF_A, { bundleId: process.env.TF_B, appPath: process.env.TF_P, shot: process.env.TF_S });
+console.log(JSON.stringify(r));" 2>&1 | tail -1)"
+  printf '### first screen: %s\n' "$FIRST" >> "$LOG"
+  fs() { python3 -c 'import json,sys
+try: print(json.loads(sys.argv[1]).get(sys.argv[2]) or "")
+except Exception: print("")' "$FIRST" "$1"; }
+  if [[ "$(fs ok)" != "True" ]]; then
+    why="$(fs reason)"; why="${why:-$(cut -c1-200 <<<"$FIRST")}"
+    fix=""
+    case "$why" in
+      *[Aa]utomation\ mode*) fix="; run once, with an administrator password: sudo automationmodetool enable-automationmode-without-authentication" ;;
+      *"Cannot find package"*|*"Could not find a driver"*|*xcodebuild*|*"code 65"*) fix="; the mac2 driver does not load or cannot build its helper: appium driver uninstall mac2; appium driver install mac2" ;;
+    esac
+    [[ "$(fs stage)" == session && -z "$fix" ]] && fix="; a mac2 session that cannot start is usually a permission: System Settings > Privacy & Security > Accessibility (the terminal, and WebDriverAgentRunner-Runner)"
+    bash "${BASH_SOURCE[0]}" stop --port "$APORT" >/dev/null 2>&1
+    write_state maccatalyst none "" "" "tf-build.sh build -f $TFM" "$PROJECT" "the app started but its first screen was not reached: $why$fix" host "$PLATFORM"
+    echo "NONE head=maccatalyst kind=host reason=the app started but its first screen was not reached: $why$fix (log $LOG)"; exit 2
+  fi
+  set_state first_screen "$(json_escape "$SHOT")"
+  DISMISSED="$(fs dismissed)"
+  [[ -n "$DISMISSED" ]] && { set_state dismissed "$(json_escape "$DISMISSED")"; echo "tf-verify-boot: $DISMISSED" >&2; }
+  [[ -n "$XNOTE" ]] && set_state xcode_check "$(json_escape "off: $XNOTE")"
+  [[ $WEBVIEW -eq 1 ]] && set_state webview true
+  echo "BOOTED head=maccatalyst mode=appium url=$AURL bundle=$BUNDLE project=$PROJECT tfm=$TFM$([[ $WEBVIEW -eq 1 ]] && echo ' webview=yes (control names not measured)') pid=$APP_PID${APPIUM_PID:+ appium-pid=$APPIUM_PID}${XNOTE:+ xcode-check=off ($XNOTE)} window=$DIR/boot-$APORT-window.png log=$LOG stop=\"bash .tfcore/utils/tf-verify-boot.sh stop --port $APORT\""
+  exit 0
+fi
+
 # ---- web ------------------------------------------------------------------------------
 if [[ "$HEAD" == "web" ]]; then
   if [[ -z "$PORT" ]]; then
@@ -432,10 +670,41 @@ fi
 [[ "$PLATFORM" == "wsl" || "$PLATFORM" == "windows" ]] || { write_state windows none "" "" "" "$PROJECT" "a Windows head runs only from WSL or Windows" host "$PLATFORM"; echo "NONE head=windows reason=a Windows head runs only from WSL or Windows, this is $PLATFORM"; exit 2; }
 command -v cmd.exe >/dev/null 2>&1 || { write_state windows none "" "" "" "$PROJECT" "cmd.exe not reachable" host "$PLATFORM"; echo "NONE head=windows reason=cmd.exe is not reachable from this shell"; exit 2; }
 TFM="$(grep -oE 'net[0-9.]+-windows[0-9.]*' "$PROJECT" | head -1)"
-CDP_PORT=9222; RELAY_PORT="${PORT:-9223}"; keyed "$RELAY_PORT"
+RELAY_PORT="${PORT:-9223}"; keyed "$RELAY_PORT"
+# Each boot drives its own embedded browser (Sevak TF-003). The DevTools port was 9222 for every
+# head, so with two up the relay on 9223 listed pages of both apps and a smoke drove the other
+# agent's window. The port now follows the relay port (9223 keeps 9222). A second head while one is
+# up also gets its own WebView2 data folder: two copies of one app would otherwise share one browser
+# process, whose single DevTools port lists both.
+if [[ "$RELAY_PORT" == "9223" ]]; then CDP_PORT=9222; else CDP_PORT=$((RELAY_PORT + 20000)); fi
+OTHERS="$(python3 - "$DIR" "$RELAY_PORT" <<'PY'
+import glob, json, os, sys
+n = 0
+for f in glob.glob(os.path.join(sys.argv[1], "boot-*.json")):
+    if f.endswith(f"boot-{sys.argv[2]}.json"):
+        continue
+    try:
+        s = json.load(open(f))
+    except Exception:
+        continue
+    if s.get("head") == "windows" and s.get("mode") == "cdp" and not s.get("stopped"):
+        n += 1
+print(n)
+PY
+)"
+UDF_SET=""
+if [[ "${OTHERS:-0}" -gt 0 ]]; then
+  UDF="$DIR/webview-$RELAY_PORT"; mkdir -p "$UDF"
+  UDF_SET="set WEBVIEW2_USER_DATA_FOLDER=$(wslpath -w "$UDF")&& "
+  echo "tf-verify-boot: $OTHERS other Windows head(s) up — this one gets DevTools port $CDP_PORT and its own WebView2 data folder ($UDF), so neither sees the other's pages" >&2
+fi
 WP="$(winarg "$(wslpath -w "$PROJECT")")"; RELAY="$(wslpath -w "$HERE/tf-cdp-relay.ps1")"
-echo "### windows head: $PROJECT -f $TFM" >> "$LOG"
-nohup cmd.exe /c "set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=$CDP_PORT&& dotnet run --project $WP -f $TFM ${CFGARGS[*]:-}" >> "$LOG" 2>&1 < /dev/null &
+echo "### windows head: $PROJECT -f $TFM (DevTools $CDP_PORT, relay $RELAY_PORT)" >> "$LOG"
+# this start's own Windows processes: the app's ids before it, so the new ones are this boot's and
+# stop kills them alone, never every copy of the program (taskkill /IM stopped another agent's app)
+win_ids() { powershell.exe -NoProfile -Command "Get-Process -Name '$ASM' -ErrorAction SilentlyContinue | ForEach-Object { \$_.Id }" 2>/dev/null | tr -d '\r' | grep -E '^[0-9]+$' | sort; }
+BEFORE_IDS="$(win_ids)"
+nohup cmd.exe /c "${UDF_SET}set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=$CDP_PORT&& dotnet run --project $WP -f $TFM ${CFGARGS[*]:-}" >> "$LOG" 2>&1 < /dev/null &
 APP_PID=$!
 nohup powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$RELAY" -ListenPort "$RELAY_PORT" -TargetPort "$CDP_PORT" >> "$DIR/relay.log" 2>&1 < /dev/null &
 RELAY_PID=$!
@@ -458,13 +727,19 @@ while [[ $i -lt 300 && -z "$URL" ]]; do
   fi
   sleep 3; i=$((i+3))
 done
+MINE="$(comm -13 <(printf '%s\n' "$BEFORE_IDS") <(win_ids) | tr '\n' ' ')"
 if [[ -z "$URL" ]]; then
   pkill -P "$APP_PID" 2>/dev/null; kill "$APP_PID" "$RELAY_PID" 2>/dev/null
-  taskkill.exe /F /T /IM "$ASM.exe" >/dev/null 2>&1
+  for w in $MINE; do taskkill.exe /F /T /PID "$w" >/dev/null 2>&1; done
+  # the relay runs Windows-side and outlives its WSL parent: a second try then failed "Only one usage
+  # of each socket address" (TechieRag TF-006)
+  powershell.exe -NoProfile -Command "Get-NetTCPConnection -LocalPort $RELAY_PORT -State Listen -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id \$_.OwningProcess -Force -ErrorAction SilentlyContinue }" >/dev/null 2>&1
   write_state windows none "" "" "cmd.exe /c dotnet run -f $TFM" "$PROJECT" "the DevTools port $RELAY_PORT never answered within 300 s" host "$PLATFORM"
   echo "NONE head=windows kind=host reason=the app's DevTools port never answered on ${HOSTS[*]}:$RELAY_PORT within 300 s (log $LOG, relay $DIR/relay.log)"; exit 2
 fi
 write_state windows cdp "$URL" "$APP_PID $RELAY_PID" "cmd.exe /c dotnet run -f $TFM" "$PROJECT" "" "" "$PLATFORM"
 set_state win_image "\"$ASM.exe\""
+set_state win_pids "[$(tr ' ' '\n' <<<"$MINE" | grep -E '^[0-9]+$' | paste -sd, -)]"
+set_state cdp_port "$CDP_PORT"
 echo "BOOTED head=windows mode=cdp url=$URL project=$PROJECT tfm=$TFM pids=$APP_PID,$RELAY_PID image=$ASM.exe log=$LOG"
 exit 0

package/.tfcore/utils/tf-verify-emit.sh

@@ -11,6 +11,8 @@
 #                 the row, looked up in runs.jsonl, or left out when there is none
 #   runs.jsonl    one `run` record for the verify pass: cmd verify-phase, the rows touched, the build
 #                 result, whether YOLO was on
+# Run and gate records carry app_phase, the phase whose checklist was graded (list.json). A second pass
+# of one *verify --phase all starts where the first one's record ended (Sevak TF-005).
 # Rows the run could not grade (not tested, not observable, not driven) get no record. Telemetry
 # never blocks: a refused record is printed and the script still exits 0.
 set -u
@@ -59,6 +61,30 @@ if own and run_id and own > run_id:
     print(f"tf-verify-emit: {run_id} is when {caller} started; this verify started {own} and is recorded from then")
     run_id = own
 
+def q(*args):
+    p = subprocess.run(["bash", EMIT, *args], capture_output=True, text=True)
+    return p.stdout.strip()
+
+runs_path = os.path.join(q("--where") or "docs/metrics", "runs.jsonl")
+runs = []
+if os.path.isfile(runs_path):
+    for line in open(runs_path, encoding="utf-8", errors="replace"):
+        try:
+            runs.append(json.loads(line))
+        except Exception:
+            pass
+
+# Sevak TF-005: *verify --phase all is one pass per phase inside one command, all handed the same
+# step-0 time. A pass that finds a run of this app already recorded since that time starts where it
+# ended, so the second pass is not refused as an overlap (SCHEMA §2.7b) and no window is counted twice.
+if run_id:
+    after = [r.get("ended", "") for r in runs if r.get("kind") == "run" and not r.get("backfilled")
+             and r.get("app") in (None, app) and r.get("started", "") >= run_id and r.get("ended", "") > run_id]
+    if after:
+        print(f"tf-verify-emit: a run of {app} was recorded since {run_id}; this pass is recorded from its end, {max(after)}")
+        run_id = max(after)
+phase = v.get("phase")
+
 def emit(stream, rec):
     p = subprocess.run(["bash", EMIT, stream], input=json.dumps(rec), capture_output=True, text=True)
     msg = (p.stdout + p.stderr).strip()
@@ -67,24 +93,14 @@ def emit(stream, rec):
         return False
     return True
 
-def q(*args):
-    p = subprocess.run(["bash", EMIT, *args], capture_output=True, text=True)
-    return p.stdout.strip()
-
 # origin lookup: the last build-phase or fix-issues run that touched the row
-runs_path = os.path.join(q("--where") or "docs/metrics", "runs.jsonl")
 origin = {}
-if os.path.isfile(runs_path):
-    for line in open(runs_path, encoding="utf-8", errors="replace"):
-        try:
-            r = json.loads(line)
-        except Exception:
-            continue
-        if r.get("kind") != "run" or r.get("backfilled") or r.get("cmd") not in ("build-phase", "fix-issues"):
-            continue
-        for rid in r.get("reqs_touched") or []:
-            if r.get("started", "") >= origin.get(rid, ("", ""))[0]:
-                origin[rid] = (r.get("started", ""), r.get("cmd"), (r.get("subagents") or ["flow-master"])[0] if r.get("subagents") else "flow-master")
+for r in runs:
+    if r.get("kind") != "run" or r.get("backfilled") or r.get("cmd") not in ("build-phase", "fix-issues"):
+        continue
+    for rid in r.get("reqs_touched") or []:
+        if r.get("started", "") >= origin.get(rid, ("", ""))[0]:
+            origin[rid] = (r.get("started", ""), r.get("cmd"), (r.get("subagents") or ["flow-master"])[0] if r.get("subagents") else "flow-master")
 
 gates = misses = 0
 for row in v["rows"]:
@@ -95,6 +111,8 @@ for row in v["rows"]:
     rec = {"kind": "gate", "app": app, "run_id": run_id, "req_id": rid, "req_class": row["class"],
            "attempt": int(att) if att.isdigit() else 1, "verdict": row["status"], "gate": row["gate"],
            "gates_run": row["gates_run"], "failure_class": row["failure_class"], "prior_verdict": row["prior_verdict"]}
+    if phase:
+        rec["app_phase"] = phase
     if emit("gates", rec):
         gates += 1
     if not row["gate"]:
@@ -124,7 +142,9 @@ rec = {"kind": "run", "app": app, "cmd": "verify-phase", "mode": mode, "yolo": y
        "build_result": v.get("build_result", "not-run")}
 if run_id:
     rec["started"] = run_id
+if phase:
+    rec["app_phase"] = phase
 ok = emit("runs", rec)
-print(f"telemetry: {gates} gate record(s), {misses} new miss(es), run record {'written' if ok else 'not written'} (cmd verify-phase, yolo {str(yolo).lower()})")
+print(f"telemetry: {gates} gate record(s), {misses} new miss(es), run record {'written' if ok else 'not written'} (cmd verify-phase, phase {phase or '?'}, yolo {str(yolo).lower()})")
 PY
 exit 0