@hienlh/ppm 0.23.11 → 0.23.12

package/docs/architecture/android-emulator-phase3-report-260921.md

@@ -0,0 +1,203 @@
+# Phase 3 report — Cài APK, chụp màn hình, logcat
+
+Ngày: 2026-09-21. Tiếp sau `android-emulator-phase2-report-260921.md`.
+Bản này ghi **những gì đo được**, trong đó có một RPC mà proto mô tả đầy đủ nhưng emulator
+**không cài đặt** và hỏng theo kiểu im lặng, cùng một chỗ chính tôi viết comment ngược với code.
+
+## 1. Kết quả
+
+| | |
+|---|---|
+| E2E mức dịch vụ (`tests/e2e/android-phase3-e2e.ts`) | **35/35** |
+| E2E qua server thật (`tests/e2e/android-ws-e2e.ts`) | **35/35** (17 check mới của Phase 3) |
+| E2E hai máy (`tests/e2e/android-two-device-install-e2e.ts`) | **9/9** |
+| Unit mới | **48** (logcat parse 8, apk 16, log filter 18, screenshot download 6) — cộng dồn **116** test Android trên 13 file |
+| `tsc --noEmit` | 0 lỗi |
+| `bun run build:web` | chunk `android-tab-*.js` 37.17 kB (gzip 11.16) — vẫn lazy, không ai trả giá nếu không mở tab |
+
+Số đo có ý nghĩa:
+
+| | |
+|---|---|
+| Upload + install thật qua HTTP | **78.75 MB**, upload → operation → `succeeded`, staging sạch sau đó |
+| Screenshot PNG | 1.87–1.94 MB, 1080×2400, emulator tự encode |
+| Logcat qua WS | 14 batch / 82 entry trong ~4 s, cửa sổ gộp 120 ms |
+| `getScreenshot` khi stream video đang chạy | 90 → 164 source frame, **không làm gián đoạn** |
+
+## 2. `sort: Parsed` không tồn tại, và nó hỏng bằng cách im lặng
+
+`emulator_controller.proto` có `LogMessage.LogType.Parsed`, trả về `LogcatEntry` đã tách sẵn
+level, tag, pid, tid — đúng thứ panel cần. Đo trên **emulator 36.5.10.0**:
+
+| Yêu cầu | Kết quả trong 8 giây |
+|---|---|
+| `streamLogcat({sort: "Parsed"})` | **334 message**, `entries` rỗng **và** `contents` rỗng, mỗi reply echo `sort: Text` |
+| `streamLogcat({sort: 1})` (enum số) | 57 message, cũng rỗng hoàn toàn |
+| `streamLogcat({})` (mặc định `Text`) | 41 message, **18 083 ký tự log thật** |
+| `getLogcat` (unary, đã deprecated) | **`12 UNIMPLEMENTED`** |
+
+Điểm đáng ghi không phải "Parsed hỏng" mà là **cách nó hỏng**: không lỗi, không `UNIMPLEMENTED`,
+chỉ là một stream bận rộn chở không có gì. Nhìn từ UI nó giống hệt một máy không log. Nếu tin
+theo proto thì panel logcat sẽ trống vĩnh viễn trên mọi máy và không có chỗ nào để bắt đầu tìm.
+
+Hệ quả thiết kế: `android-logcat.ts` xin `Text` và **tự parse**. Hai chi tiết nữa đo được, và
+chúng quyết định hình dạng parser:
+
+* Mỗi message gRPC mang **đúng một dòng**, **không có `\n` cuối** — nên không cần buffer dòng dở.
+  (Vẫn `split("\n")` phòng bản emulator sau gộp dòng, vì nếu gộp mà không split thì nhiều dòng
+  sẽ dính thành một entry, lại là một lỗi im lặng nữa.)
+* Định dạng là `threadtime` của logcat: `MM-DD HH:MM:SS.mmm PID TID L TAG: message` — **không có
+  năm**. Parser lấy năm hiện tại, và lùi một năm nếu như thế đẩy dòng log ra tương lai quá một
+  ngày (đọc log tháng 12 vào ngày 1 tháng 1).
+
+Dòng không parse được thì **giữ nguyên**, không bỏ: đó là dòng nối của stack trace hoặc banner
+`--------- beginning of main`, mất dòng nào cũng là cắt đôi một crash.
+
+### 2.1 Lệch so với plan, có chủ ý
+
+Plan §4 viết "ADB dùng discovery/boot readiness, cài APK và logcat". Logcat ở đây đi qua **gRPC
+`streamLogcat`**, không phải `adb logcat`. Lý do:
+
+* gRPC dùng lại đúng channel đã xác thực của session — không thêm một tiến trình con mỗi máy.
+* `adb logcat` cần adb serial, mà serial là `null` trong lúc máy còn boot; channel gRPC thì đã có.
+* Theo chính comment trong proto, `streamLogcat` **chạy `logcat` trong guest qua `AdbShellStream`**
+  — tức dữ liệu là một, chỉ khác đường vận chuyển.
+
+Cái mất: không đẩy được filter xuống thiết bị (`adb logcat -s TAG:E`), nên mọi dòng đều qua dây
+rồi mới lọc ở client. Đo thực tế ~40 message/8 s nên chưa đáng đổi. Cài APK thì **vẫn đi adb**
+đúng như plan, vì `EmulatorController` không có RPC install nào cả.
+
+## 3. `adb install` không chọn bừa — nó từ chối
+
+Comment đầu tiên tôi viết trong `android-apk.ts` nói `adb install` không `-s` sẽ "chọn máy nào
+tuỳ nó thích". Đo với hai emulator đang chạy:
+
+```
+$ adb install <file>
+adb: more than one device/emulator
+```
+
+Nó **từ chối, không cài gì cả**. Sửa lại comment. Điều này làm `-s` còn quan trọng hơn: trên máy
+một emulator thì thiếu `-s` vẫn chạy **nhờ may**, và hỏng đúng vào ngày người dùng mở máy thứ hai.
+
+Gate "install đúng target khi có hai máy" được chứng minh bằng
+`tests/e2e/android-two-device-install-e2e.ts`, 9/9. Chỗ khó là **làm cho test có thể fail**: hai
+AVD spike dùng chung một system image nên danh sách package giống hệt nhau, và cài một gói cả
+hai đều có sẵn thì pass dù `-s` có được tôn trọng hay không. Test tự tạo chênh lệch bằng
+`pm uninstall --user 0 com.google.android.deskclock` trên máy đích (`--user 0` vì đây là app hệ
+thống, uninstall thường bị từ chối), rồi kiểm tra cả hai máy trước và sau, và trả lại nguyên trạng.
+
+## 4. Huỷ upload không để lại temp
+
+Gate của plan. Không tự nhiên mà có: request bị abort làm phép đọc **fail giữa chừng file**, nên
+phần đã ghi phải bị xoá trên mọi nhánh lỗi.
+
+`stageApkUpload` xoá file dở khi abort, khi quá hạn mức, và khi header không phải zip — kiểm tra
+4 byte đầu **trong lúc** stream, nên một body 5 GB bị cắt tại ngưỡng chứ không phải sau khi đã
+ghi xong. PPM bị kill giữa chừng upload thì `sweepApkStaging()` dọn ở lần sau (quá 1 giờ).
+
+Đo qua server thật: abort giữa upload → `AbortError`, thư mục staging **0 file**; upload 78.75 MB
+thành công → install `succeeded` → staging lại **0 file**.
+
+## 5. Giết tiến trình **không** làm đóng pipe của nó
+
+Deadline cho `adb install` (plan §7 yêu cầu) tưởng là một dòng `setTimeout(() => proc.kill())`.
+Test bằng một `adb` giả là script `#!/bin/sh\nsleep 30`: kill xong, `reader.read()` **vẫn không
+bao giờ resolve** — `sh` chết nhưng `sleep` con thừa kế pipe và giữ nó mở. Test timeout 5 s.
+
+Tức là bản đầu tiên của tôi có deadline nhưng deadline không thoát được: hàm vẫn treo đúng chỗ nó
+định cứu. Sửa bằng cùng hình dạng `Encoder.stop()` trong `android-video.ts` đã phải dùng cho
+ffmpeg — **race**, không chờ:
+
+```ts
+const outcome = await Promise.race([collected, expired, aborted]);
+```
+
+`cancelled` cũng phải nằm trong race vì cùng một lý do: một cancel chờ read kết thúc sẽ treo tới
+tận deadline 10 phút thay vì trả lời ngay. Hai unit test giữ cả hai nhánh, và cả hai đều **đo thời
+gian** chứ không chỉ đo kết quả — một bản sửa sai vẫn trả đúng message, chỉ là sau 10 phút.
+
+## 6. `DeviceEntry.state` không bao giờ báo `booting`
+
+Plan §6 nói "install APK chỉ khi guest ready". Cách hiển nhiên là `if (device.state !== "ready")`.
+Nhưng `listDevices` là hàm **đồng bộ** và đặt `state: e ? "ready" : "stopped"` — tức mọi máy có
+tiến trình đều là `ready`, và giá trị `"booting"` khai báo ở dòng 27 của `device-registry.ts`
+chưa từng được sinh ra. Check đó là một tautology.
+
+Câu trả lời thật là `getStatus().booted` của chính emulator, tốn một RPC trước mỗi lần install.
+Đây là lỗ hổng của Phase 1, không sửa ở Phase 3 vì làm `listDevices` thành async sẽ chạm mọi
+caller; ghi lại ở đây để Phase 4 xử lý khi làm device manager.
+
+## 7. Chỗ tôi viết comment ngược với code, và e2e bắt được
+
+`case "logcat"` trong `android-session.ts` nằm **dưới** cổng kiểm tra lease, trong khi comment
+ngay trên nó viết "Not gated on the controller lease". Tức là viewer không giữ lease — đúng
+người cần đọc log khi người khác đang điều khiển — bị từ chối im lặng.
+
+Không unit test nào bắt được: nó chỉ sai khi có **hai** viewer và lease đã chuyển. `android-ws-e2e.ts`
+gửi `logcat` từ viewer A **sau khi** B đã cướp lease, và trả về `0 batches, 0 entries`. Đây là lý
+do e2e hai-viewer đáng viết chứ không phải là thừa.
+
+## 8. Quyết định thiết kế
+
+* **Ring buffer sống qua lần đóng panel.** Gate nói "logs hidden ngừng subscription" — stream gRPC
+  dừng thật. Nhưng vứt luôn backlog là chuyện khác và tệ hơn: đóng panel để đọc stack trace ở chỗ
+  khác rồi mở lại sẽ thấy hộp rỗng. Ring (2000 entry) chỉ mất khi session của máy đóng. Giá phải
+  trả: khoảng trống trong log ở quãng không ai xem — timestamp nói rõ điều đó.
+* **Batch log 120 ms.** Một WS frame mỗi message gRPC sẽ vừa ngập socket vừa tranh chỗ với video
+  trên cùng một dây. Viewer nào đang tắc socket thì bỏ qua batch — ring ở server giữ lại rồi.
+* **Screenshot là PNG, không phải RGBA thô.** Emulator tự encode, nên không chỗ nào ở đây phải
+  biết layout buffer — mà đó đúng là chỗ proto nói sai (Phase 2 §2.1: proto ghi "bottom up",
+  đo ra top-down). File người dùng tải về không phải chỗ để phát hiện lại chuyện đó.
+* **Panel công cụ nằm **dưới** màn hình ở mọi kích thước.** Không phải nhượng bộ cho mobile: log
+  phải đọc được *đồng thời* với việc chạm vào guest, mà modal thì không — và dưới cùng cũng là
+  thumb zone mà design guidelines yêu cầu, nên layout điện thoại ra từ cùng một quyết định.
+* **Không panel nào được mount khi tab của nó đóng**, nên subscription logcat bám theo panel:
+  chuyển sang tab Install là dừng stream log thật sự.
+* **Cài từ project nhận `{project, path}`, không nhận đường dẫn tuyệt đối.** Nhận tuyệt đối thì
+  route này thành trình đọc file tuỳ ý. Path được resolve *bên trong* project rồi từ chối nếu
+  thoát ra (400) — cùng luật `extension-rpc-handlers.ts` đang dùng.
+* **Quét APK trong project bị giới hạn**: sâu tối đa 8 cấp, prune `node_modules`/`.git`/`.gradle`…
+  Cùng lý do với lệnh cấm `fs.watch` đệ quy trong CLAUDE.md.
+* **Hai hạn mức, không phải một.** `MAX_APK_BYTES` (2 GB) chặn một file vô lý; `MAX_STAGING_BYTES`
+  (4 GB) chặn nhiều file hợp lệ cùng lúc. Thiếu cái thứ hai thì hai upload 2 GB song song đều hợp
+  lệ theo hạn mức riêng và cùng nhau làm đầy đĩa mà database đang nằm trên đó.
+
+## 9. Không log nội dung input/clipboard
+
+Gate cuối. Kiểm tra bằng hai cách: `grep` mọi `console.*` trong `src/services/android/`,
+`src/server/ws/android.ts`, `src/server/routes/android.ts` — ba chỗ duy nhất đều là thông báo lỗi
+(`could not persist ownership`, `logcat stream … failed`, `failed to start a session`), không chỗ
+nào chạm vào `text`/`entries`. Và grep chuỗi bí mật của e2e clipboard trong log server sau khi
+chạy: **0 lần xuất hiện**.
+
+## 10. Chưa đo — không được coi là đã đạt
+
+* Split APK (`install-multiple`). Plan cho phép bỏ qua nếu chưa có workflow rõ ràng; hiện **không
+  hỗ trợ**, và một file `.apks`/`.aab` sẽ bị adb từ chối với `INSTALL_FAILED_INVALID_APK` — thông
+  báo có giải thích, nhưng vẫn là từ chối.
+* Cài APK **lỗi ABI / minSdk / chữ ký thật**. Bảng `FAILURES` được unit test bằng output adb dựng
+  sẵn, chưa chạy với APK thật gây ra từng lỗi đó (cần APK arm-only và APK ký khác — chưa có).
+* Upload qua tunnel Cloudflare (timeout idle của proxy với body 78 MB).
+* Logcat trên máy **nói nhiều** (app đang crash-loop): mới đo ~40 msg/8 s trên máy nhàn rỗi.
+* Panel trên trình duyệt mobile thật.
+
+## 11. Tái lập
+
+```bash
+# 1. AVD thử nghiệm riêng, không đụng Pixel_9 / Pixel_Tablet của người dùng
+bash spikes/android/boot-test-avd.sh &
+AVD=ppm_spike_test2 LOG=/tmp/ppm-android-spike/emulator2.log bash spikes/android/boot-test-avd.sh &
+
+# 2. E2E mức dịch vụ
+ANDROID_EMULATOR_ENABLED=1 PPM_HOME=$(mktemp -d) bun tests/e2e/android-phase3-e2e.ts
+
+# 3. Gate hai máy
+ANDROID_EMULATOR_ENABLED=1 PPM_HOME=$(mktemp -d) bun tests/e2e/android-two-device-install-e2e.ts
+
+# 4. E2E qua server thật (PPM_SERVER_HOME để check staging đúng PPM_HOME của server)
+SRV=$(mktemp -d)
+ANDROID_EMULATOR_ENABLED=1 PPM_HOME=$SRV bun src/server/index.ts __serve__ 8099 127.0.0.1 &
+PPM_SERVER_HOME=$SRV PPM_BASE=http://127.0.0.1:8099 PPM_TOKEN=<token> \
+  PPM_HOME=$(mktemp -d) bun tests/e2e/android-ws-e2e.ts
+```

package/docs/architecture/android-emulator-phase4-report-260921.md

@@ -0,0 +1,191 @@
+# Phase 4 report — Tạo, wipe, xoá AVD ngay trong PPM
+
+Ngày: 2026-09-21. Tiếp sau `android-emulator-phase3-report-260921.md`.
+
+Bản này ghi **những gì đo được**. Trong Phase 4 có ba lỗi đáng kể, và cả ba đều **im lặng**:
+một lỗi ghi AVD vào thư mục AVD **thật của người dùng**, một lỗi khiến mọi emulator đang chạy
+đều bị báo là "không ai khoá", và một lỗi của chính bài test chứ không phải của sản phẩm.
+
+## 1. Kết quả
+
+| | |
+|---|---|
+| E2E gate Phase 4 (`tests/e2e/android-avd-crud-e2e.ts`) | **34/34** — tạo → boot → ghi dữ liệu → stop → boot lại → wipe → boot lại → xoá |
+| E2E qua server thật (`tests/e2e/android-ws-e2e.ts`) | **48/48** — 34 check cũ + **14 check mới** cho route Phase 4 |
+| Unit mới | **34** (avd-manager 20, system-images 13, lock NUL 1) — cộng dồn **143** test Android trên 15 file |
+| `tsc --noEmit` | 0 lỗi |
+| `bun run build:web` | chunk `android-tab-*.js` **48.35 kB** (gzip 14.08) — tăng ~11 kB so với Phase 3, vẫn lazy |
+| Toàn bộ `bun test` | 7146 pass / 33 fail — **không có test Android nào đỏ**; 33 lỗi nằm trong các nhóm đã biết từ trước (codex 18, tunnel 7, cloud-ws 2, 6 lỗi lẻ), số lượng dao động giữa các lần chạy ở nhóm tunnel |
+
+Số đo có ý nghĩa:
+
+- `avdmanager list device` mất **~730 ms** lần đầu và **0 ms** sau đó (cache trong tiến trình);
+  88 profile, trong đó 39 phone và 13 tablet.
+- Đọc system image từ **đĩa** thay vì `sdkmanager --list_installed`: tức thì, không có thanh
+  tiến trình phải bóc tách, và vẫn trả lời đúng trên máy có image nhưng **không có** cmdline-tools.
+- AVD tạo bởi PPM: boot lần đầu **25 s**, boot lại từ snapshot **3 s**, boot sau wipe **24 s**.
+- Một wipe giải phóng **3.2 GB** trên AVD đã boot hai lần.
+
+## 2. `ANDROID_AVD_HOME` trỏ vào thư mục **không tồn tại** thì avdmanager ghi vào `~/.android/avd`
+
+Đây là biến thể thứ hai của cùng một cái bẫy, và nó nguy hiểm hơn cái đầu.
+
+- Lần đầu (đã ghi ở Phase 4 khi đang code): **không** set `ANDROID_AVD_HOME` cho tiến trình con
+  thì `avdmanager` ghi AVD vào `~/.android/avd` — đúng thư mục AVD thật của người dùng. Sửa bằng
+  `avdHomeEnv()` trong `sdk-discovery.ts`, dùng chung với `emulator-launcher.ts`.
+- Lần hai: **có** set `ANDROID_AVD_HOME`, nhưng trỏ vào thư mục vừa bị xoá. `avdmanager` **không
+  báo lỗi** — nó lặng lẽ quay về `~/.android/avd` và ghi AVD ở đó. Phát hiện bằng
+  `find ~ -maxdepth 4 -name 'ppm_wipe_probe*'`.
+
+Cả hai lần đều không đụng `Pixel_9` / `Pixel_Tablet`; AVD lạc đã được xoá tay ngay.
+
+Sửa: một dòng `mkdirSync(opts.avdHome, { recursive: true })` trước khi chạy tool. Kiểm tra
+"config.ini có xuất hiện đúng chỗ không" ở cuối `createAvd` vẫn giữ nguyên — nó chính là thứ đã
+**bắt được** cả hai lần, nên nó không phải kiểm tra thừa.
+
+Bài học chung: một biến môi trường kiểu "thay thế đường dẫn" cần thư mục **có thật**; nếu không,
+tool sẽ dùng mặc định và trông như đang hoạt động bình thường.
+
+## 3. File lock của emulator kết thúc bằng NUL, nên `trim()` không cứu được
+
+`hardware-qemu.ini.lock` của một emulator đang chạy, đọc bằng `xxd`:
+
+```
+00000000: 3531 3937 3732 00                        519772.
+```
+
+7 byte: `519772` rồi **một byte NUL**. `String.prototype.trim()` chỉ bỏ khoảng trắng, mà NUL
+không phải khoảng trắng — nên `Number("519772\0")` là `NaN`, `Number.isInteger(NaN)` là `false`,
+và `isLocked()` trả `false` cho **mọi** emulator đang chạy.
+
+Hậu quả, tất cả đều im lặng:
+
+- Dòng cảnh báo "Locked by another process — it is probably open in Android Studio" trong danh
+  sách thiết bị **chưa từng hiện**.
+- `assertDestructible()` của Phase 4 có một lớp bảo vệ không hoạt động (lớp "đang chạy" vẫn
+  hoạt động, vì nó quét tiến trình chứ không đọc lock).
+
+Lý do nó sống sót qua Phase 1: unit test tự viết fixture `` `${process.pid} ` `` — pid kèm một
+**dấu cách**. `trim()` xử lý được dấu cách, nên bài test xanh với đúng giả định sai của người
+viết nó. Bài test mới ghi đúng thứ emulator ghi (`${pid}\0`) và đỏ trước khi sửa.
+
+Sửa: lấy cụm số ở đầu file (`/^\s*(\d+)/`) thay vì tin vào `trim()`.
+
+Kiểm tra lại trên máy thật, có một emulator đang chạy:
+
+```
+ppm_spike_test         locked=true      ← đang chạy
+ppm_spike_test2        locked=false
+Pixel_9                locked=false
+Pixel_Tablet           locked=false
+```
+
+## 4. `userdata.img` **không** được xoá khi wipe — tài liệu của chính emulator nói vậy
+
+Danh sách wipe ban đầu có `userdata.img`. `emulator -help-disk-images` xếp nó vào nhóm ảnh
+**khởi tạo**, cùng chỗ với `system.img`, và định nghĩa wipe là:
+
+> `-wipe-data`  Copy the content of the *initial* user data image (userdata.img) into the
+> writable one (userdata-qemu.img)
+
+Tức là xoá `userdata.img` chính là xoá bản gốc mà một lần wipe cần để khôi phục.
+
+Đo thêm cho đủ: AVD tạo bằng tooling hiện tại trên máy này **không có** `userdata.img` trong thư
+mục AVD (nó nằm trong thư mục system image), nên lỗi này không biểu hiện ở đây — boot sau wipe
+vẫn 24 s. Nó chỉ cắn một AVD do tooling cũ tạo ra, im lặng, ở lần boot kế tiếp. Đúng loại việc
+mà danh sách cho phép (allowlist) sinh ra để tránh.
+
+## 5. Ba lỗi của **bài test**, không phải của sản phẩm
+
+1. **`adb shell sh -c "echo X > file"`** — `adb` nối các tham số bằng dấu cách rồi đưa cả chuỗi
+   cho shell **của máy ảo**, nên dấu `>` bị shell đó nuốt: `sh -c echo` chạy với `echo` là lệnh và
+   ghi một dòng trống. File có thật, nội dung rỗng, và hai check "ghi được file" + "dữ liệu còn
+   sau khi stop" cùng đỏ. Sửa: truyền **một** tham số duy nhất.
+2. **`boot()` nuốt output của emulator** — một lần boot không xong chỉ báo đúng chữ `no`, tức là
+   thứ duy nhất đáng quan tâm thì không có. Giờ mỗi lần boot ghi ra một file log và phần tổng kết
+   in đường dẫn của những lần boot hỏng.
+3. **Một lần "boot sau wipe" hỏng không tái lập được** — chạy lại đúng kịch bản đó bằng một
+   probe riêng (tạo → boot → ghi → stop → wipe → boot) thì boot lần hai mất 24 s và thành công;
+   lần chạy e2e kế tiếp cũng qua. Ghi lại ở đây thay vì tuyên bố là đã hiểu: nó **chưa được giải
+   thích**, chỉ là không lặp lại.
+
+## 6. Quyết định thiết kế
+
+- **PPM không tải system image.** `/system-images` đọc cây `system-images/<api>/<tag>/<abi>/
+  source.properties` trên đĩa. Không có nút tải, không tự chấp nhận licence — đúng plan Phase 4.
+  Image sai CPU vẫn được **liệt kê** nhưng không chọn được, kèm lý do ngay trên dòng đó: ẩn đi thì
+  người dùng biết mình đã cài mà không thấy, và sẽ nghĩ là lỗi.
+- **Bắt buộc có device profile.** `avdmanager create avd` không `--device` cho ra AVD **320x640**
+  (đã đo ở Phase 4 khi code), trông như emulator hỏng chứ không như thiếu tham số.
+- **`hw.keyboard=yes` luôn được ghi** sau khi tạo. `avdmanager` ghi `no`; với `no` thì `sendKey`
+  trả OK và không một ký tự nào tới máy ảo (đo ở Phase 0).
+- **Không `--force`.** Trùng tên bị từ chối, vì ghi đè một AVD là hành vi phá huỷ đội lốt tạo mới.
+- **Tên được kiểm tra, không được escape.** Regex nằm ở `src/shared/android-avd.ts` và **dùng
+  chung** cho form lẫn host — hai bản sao của một regex kiểm tra là hai bản sẽ lệch nhau, và cách
+  chúng lệch là form nhận một cái tên rồi host từ chối sau khi hộp thoại đã đóng.
+- **Wipe là allowlist chứ không phải glob.** File nào code này chưa biết thì **giữ lại**.
+- **Wipe/Delete: gõ lại đúng tên máy.** Không phải checkbox — các dòng trong danh sách nhìn giống
+  hệt nhau, và checkbox chỉ xác nhận rằng có một hộp thoại đang mở, không xác nhận nó mở trên máy nào.
+- **Nút ba chấm nhìn thấy được**, không phải right-click hay long-press: wipe và delete không có
+  đường nào khác, mà một cử chỉ ẩn thì không phải là một đường đi. Nó là control riêng nên không
+  cướp mất cú chạm của cả dòng (bẫy đã ghi trong CLAUDE.md).
+
+## 7. UI đo trên trình duyệt thật, không chỉ đọc code
+
+Chạy PPM đã build (`bun run build:web` rồi serve `dist/web`) và lái bằng Playwright, ở **390x844**:
+
+| | |
+|---|---|
+| Hộp thoại tạo máy dưới `md` | là **bottom sheet** thật (đáy dính đáy màn hình) |
+| Tràn ngang | **không** (`scrollWidth === innerWidth`) |
+| Vùng chạm | 7/7 control **44 px** — nhưng chỉ sau khi sửa: trigger của `SearchSelect` mặc định là `h-10 md:h-7`, tức **40 px**, dưới ngưỡng. Đo mới thấy, đọc code thì không. |
+| Nút ba chấm mỗi dòng | 44x44 |
+| Mục menu | "Wipe data" 44 px, "Delete device" 44 px và `data-variant="destructive"` |
+| Sheet xác nhận | nút vẫn **disabled** khi gõ tên sai (`Pixel_9_wrong`) và khi thiếu **một ký tự** (`ppm_ui_prob`) |
+
+Và chạy trọn vòng **qua chính UI** với server thật: tạo `ppm_ui_probe` → nó hiện trong danh sách
+(API 37, 1080x2424, **không** có cảnh báo thiếu hardware keyboard, tức `hw.keyboard=yes` đã vào)
+→ xoá bằng cách gõ đúng tên → biến mất. `Pixel_9` (26 file) và `Pixel_Tablet` (22 file) nguyên vẹn.
+
+Một quan sát phụ, tình cờ: `vite build` xoá `dist/web` nên tab đang mở mất chunk — và màn hình
+khôi phục chunk (`root-error-boundary` + watchdog) đã bắt đúng, hiện nút Reload thay vì trắng trang.
+
+## 8. Cách viết test phá huỷ mà không phá gì
+
+Trong `android-ws-e2e.ts` (chạy với AVD **thật** của người dùng) có check "không wipe được máy
+đang chạy". Nó gửi kèm `confirmName` **sai**:
+
+```ts
+{ confirmName: "definitely-not-its-name" }
+```
+
+rồi mới khẳng định thông báo lỗi nói về *đang chạy*. Nghĩa là phải **hai** lớp bảo vệ cùng hỏng
+mới mất dữ liệu. Một bài test có thể phá dữ liệu người dùng khi code hỏng thì không đáng viết.
+
+Còn gate thật của Phase 4 (tạo/wipe/xoá thật) nằm ở `android-avd-crud-e2e.ts`, chạy trong AVD
+home riêng `~/.android-phase4-avd` và tự dọn — không đụng `Pixel_9` / `Pixel_Tablet` (plan §9).
+
+## 9. Chưa đo — không được coi là đã đạt
+
+- Chưa thử trên Windows / macOS: `avdmanager` là `.bat` trên Windows và cách nó nhận stdin `no\n`
+  chưa được kiểm tra ở đó.
+- Chưa thử với AVD do **Android Studio** đang mở (lock thật của Studio, chứ không phải của
+  emulator do PPM khởi động) — giờ mới có `isLocked` đúng để thử.
+- Chưa thử tạo AVD khi ổ đĩa đầy, và chưa thử `sdCardMb: 0` trên máy thật.
+- Chưa đo p50/p95 click-to-visible trên LAN và qua tunnel (vẫn là mục còn nợ từ §10 của plan).
+
+## 10. Tái lập
+
+```bash
+# Gate Phase 4 — mất vài phút, 4 lần boot, AVD home riêng
+ANDROID_EMULATOR_ENABLED=1 PPM_E2E_LOG_DIR=/tmp/p4logs PPM_HOME=$(mktemp -d) \
+  bun tests/e2e/android-avd-crud-e2e.ts
+
+# Route Phase 4 qua server thật
+ANDROID_EMULATOR_ENABLED=1 bun src/server/index.ts __serve__ 8099 127.0.0.1 dev
+PPM_BASE=http://127.0.0.1:8099 PPM_TOKEN=<token> PPM_HOME=$(mktemp -d) \
+  bun tests/e2e/android-ws-e2e.ts
+
+# Unit
+bun test tests/unit/android tests/unit/web/android-*.test.ts
+```