Unit-test the conversion toolchain, and fix the four defects that found (MTE-5766, MTE-5827)

The toolchain had no tests. Its verdicts are what we decide "done" on, and the way we checked them
was to run a tool, read its output, and judge whether it looked right — which is how two confidently
wrong diagnoses survived review. Both were in the gates written to prevent exactly that.

44 tests, stdlib unittest, no device or Firefox checkout needed: ps/lsof/adb/git are stubbed and the
edge cases build synthetic batch dirs. The efftriage rule tests instead run against REAL labelled
conversion runs, now checked in under tests/fixtures/corpus with a labels.json manifest. That
distinction is the point: hand-written traces only exercise the shapes their author imagined, so they
go green while the tool mismatches real output — a false green in the suite meant to prevent false
greens. The corpus also existed only as batch dirs in one person's conversion-runs/, unversioned and
impossible to run in CI, which is a poor home for the campaign's main diagnostic asset.

Four defects, three of them in code already reviewed by eye and pronounced fine:

- efftriage diagnosed GREEN runs. Traces normally carry non-fatal [ERR] lines (nav-graph polling,
  tolerated absence checks) and the rules scanned them whatever the outcome, so a passing run was
  reported as an absence-assertion failure. Two labelled runs in our own corpus were affected. Still
  triaged on purpose: a retry-pass, where attempt 1 did fail and clean=false means flaky-not-done,
  and a crash, since crash mode is where `outcome: pass` is itself the lie (MTE-5822).
- efftriage blamed the harness for a typo: a nonexistent batch dir came back as gotcha A24, sending
  the reader to check effpretty resolution and pull dumps off a device. It also tracebacked.
- effdoctor named the wrong queue — the failure it exists to prevent. effwatch is launched by a
  relative path, resolved with abspath against effdoctor's cwd instead of the watcher's, so from a
  Firefox checkout it reported a queue under firefox/tae-conversion/ that has never existed and told
  us to use it. Requests there are never consumed and never error. Now reads the watcher's own cwd
  (/proc, then lsof); a computed queue that is not on disk is a FAIL and an unreadable cwd is
  "undetermined", because declining to answer beats answering wrongly.
- effdoctor's self-exclusion skipped any ps line containing the substring "effdoctor", so a watcher
  under a directory with that name was invisible. Unnoticed watchers are the whole point of the tool.

Recorded as known gaps rather than papered over: rules T3/T4/T5 have no labelled example in the
53-run corpus, so they are unvalidated rather than known-good, and 3 of 28 failures still get no
diagnosis. Both are asserted, so the lists cannot go stale in either direction.

Author: jjSDET

.github/workflows/tae-conversion-tests.yml

@@ -0,0 +1,45 @@
+name: tae-conversion-tests
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "tae-conversion/**"
+      - ".github/workflows/tae-conversion-tests.yml"
+  pull_request:
+    paths:
+      - "tae-conversion/**"
+      - ".github/workflows/tae-conversion-tests.yml"
+
+jobs:
+  test:
+    name: Run unit tests
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # No dependency install step: the eff* tools are stdlib-only, and the tests
+      # need no device, no emulator, no Firefox checkout and no network. The rule
+      # tests run against real conversion runs checked in under
+      # tae-conversion/tests/fixtures/corpus; everything that shells out to ps,
+      # lsof, adb or git is stubbed.
+      - name: Run tests
+        run: python -m unittest discover -s tae-conversion/tests -p '*tests.py' -v
+
+      # ResourceWarnings are errors here: an unclosed file in a tool that is run
+      # hundreds of times a session is a real leak, and warning noise in the output
+      # is what makes people stop reading it.
+      - name: Run tests with warnings as errors
+        run: python -W error::ResourceWarning -m unittest discover -s tae-conversion/tests -p '*tests.py'

tae-conversion/CHANGELOG.md

@@ -25,12 +25,41 @@ verdict semantics, changed flags. `git log` has the rest.
   resolving it against the caller's cwd yields a directory that never existed. A computed queue that is not on
   disk is reported as a failure, and an unreadable cwd as "undetermined": naming the wrong queue confidently is
   worse than declining to name one. (MTE-5766)
+- **Unit tests** (`tae-conversion/tests/`, 44 of them) and a CI job, where previously the toolchain had none.
+  Run them with `python -m unittest discover -s tae-conversion/tests -p '*tests.py'`; no device, emulator,
+  Firefox checkout or network needed, since `ps`/`lsof`/`adb`/`git` are stubbed. The efftriage rule tests run
+  against **real labelled conversion runs** checked in under `tests/fixtures/corpus` with a `labels.json`
+  manifest: hand-written traces only test the shapes their author imagined, so they pass while the tool
+  mismatches real output — a false green in the suite meant to prevent false greens. That corpus previously
+  existed only as batch dirs in one person's `conversion-runs/`, unversioned and unrunnable in CI. Writing
+  these found four defects, three of them in code that had already been reviewed by eye and pronounced fine.
+- `ALT_TOOLS` env var on `effdoctor`, so the alt-checkout divergence check works for checkouts that are not at
+  `~/Workspace/ui-test-modernization`.
 - `VERSION` + this changelog, and `--version` on all 12 tools. Version lookup resolves symlinks, so it stays
   correct when a tool is invoked through another checkout's `tools/` dir. (MTE-5770 slice 1)
 - Docs: lessons **K13** (ad surfaces are testable offline by faking the app-services client at the seam
   app-services itself uses in its unit tests) and gotchas **A37–A43**.
 
 ### Fixed
+- `efftriage.py` — **a green run was handed a failure diagnosis.** Traces routinely carry non-fatal `[ERR]`
+  lines (nav-graph polling, tolerated absence checks), and the rules scanned them regardless of outcome, so a
+  passing run was reported as an absence-assertion failure. Two of the campaign's own labelled runs were
+  affected. A passing single-attempt run is no longer triaged; its non-fatal error count is reported as a note
+  instead. Deliberately still triaged: a **retry-pass**, where attempt 1 really did fail and `clean=false`
+  means flaky-not-done (now labelled `PASSED ONLY ON RETRY`), and a **crash**, because crash mode is where
+  `outcome: pass` is itself the lie (MTE-5822). (MTE-5827)
+- `efftriage.py` — a nonexistent batch dir was diagnosed as gotcha A24 ("run-report.txt is missing"), sending
+  the reader to check effpretty resolution and pull dumps off a device on account of a mistyped path. It is now
+  reported as `no-such-batch`, and no longer tracebacks with a `KeyError`.
+- `effdoctor.py` — **named the wrong queue, which is the failure it exists to prevent.** effwatch is normally
+  launched by a relative path, and that path was resolved with `os.path.abspath` — against effdoctor's cwd
+  rather than the watcher's. Run from a Firefox checkout it reported a live queue under
+  `firefox/tae-conversion/`, a directory that has never existed, and advised queueing into it; a request
+  dropped there is never consumed and never errors. The watcher's own cwd is now read (`/proc` first, `lsof`
+  fallback). A computed queue that is not on disk is a FAIL, and an unreadable cwd is reported as undetermined
+  with the command to run: declining to answer beats answering wrongly. (MTE-5766)
+- `effdoctor.py` — the self-exclusion filter skipped every `ps` line containing the substring `effdoctor`, so
+  a watcher running from a directory whose name contained it was invisible. Now skips only this process.
 - `effverify.py` — **a crashed test was scored as passed**, with `clean=true` and `failed_total=0`. Only
   `failed:` markers and the gradle status line were read, and a crash emits neither (`"gradle": null` was the
   tell). Now also reads the report's `FAILURES (n of m)` header and `CRASH:` lines, and refuses to report
@@ -47,6 +76,12 @@ verdict semantics, changed flags. `git log` has the rest.
   a `NameError` that is now fixed; gotcha **A24** now carries its root cause.
 
 ### Known gaps
+- `efftriage` rules **T3, T4 and T5 have no labelled example** anywhere in the 53-run corpus they were
+  hardened against, so they are unvalidated rather than known-good — a rule that has never fired on a real
+  failure may not match the shape it was written for at all. Listed in `UNVALIDATED_RULES` in the tests, which
+  fail if the list goes stale in either direction.
+- 3 of the 28 failed runs in the corpus get **no diagnosis** (`gap-*` fixtures). They are checked in as
+  tripwires: add a rule that explains one and the test fails, which is the reminder to record the win.
 - Mechanized coverage is not yet reported. `effgates --coverage` plus a `Gate:` line on every doc entry is
   MTE-5830; the `effcheck` verb × selector-strategy matrix is MTE-5828; `effparity` (legacy-vs-port assertion
   parity, gating lesson G1) is MTE-5829.