@kienntpixon/dieu-phoi 0.7.0 → 0.7.2

package/profile/unity-lanes.md

@@ -0,0 +1,316 @@
+# Unity lanes: nhiều editor Unity song song (phòng ai-lab)
+
+Tài liệu miền của profile ai-lab, cho kế hoạch Fast Forward / rebuild game Unity. Agent tìm tới file này qua dòng `unity-lanes`
+trong `profile/lessons.md`; điều phối viên qua dòng `[orch]`. Ký hiệu: `<project>` = checkout chính của game, `<wt_root>` =
+gốc worktree (mặc định `<project>-wt`, cạnh project), `<wt>` = `<wt_root>/<lane>`, `<main>` = nhánh chính của game (vd.
+`mobile-portrait`), `<skill>` = thư mục skill dieu-phoi. Phần toolchain: `docs/machine-setup.md` trong repo ai-lab/pixon-fast-forward.
+
+## 1. Khi nào dùng lanes
+- Backlog Unity dài và đồ thị phụ thuộc thật cho phép >= 2 nhánh chạy cùng lúc. Một bước lẻ hoặc chuỗi tuần tự: không dùng.
+- Số đo pilot 2026-10-11: cặp 2 lane 1.59x trước tích hợp, 1.16x khi tính cả bước tích hợp; mô phỏng phần còn lại 3 lane 2.0-2.3x,
+  2 lane 1.4-1.7x. Chi phí chính là **test sau merge** (~0.85 h editor trunk mỗi bước lane), không phải merge (1 phút, 0 xung đột).
+
+## 2. Mô hình
+- **trunk** = checkout chính trên `<main>`, là đường găng: tích hợp, cổng thiết bị, build Android.
+- **Lane vệ tinh** = git worktree `<wt>` trên nhánh `lane/<lane>`, một editor mỗi lane, nhận trọn một miền tự chứa (vd. repair,
+  monetization). Một miền không bao giờ ở hai lane cùng lúc.
+- Planner ghi `unity_lane` (trunk / b / c) cho mỗi bước Unity, và `unity_lane_2` (phương án 2 lane) để lùi về khi thiếu máy.
+- Tạo/mở/liệt kê/xoá lane bằng `lanes.py` (toolset hoặc bản trong game: `create [--sparse] [--keep-art ...]`, `launch`, `list`,
+  `env`, `remove`, `device-lock`, `--selftest`). `--sparse` bỏ thư mục art thô (~1-2 GB thay vì ~8 GB checkout).
+
+### 2.1 Slot cố định + editor mở sẵn + hàng đợi việc (mặc định từ 2026-10-26)
+- **Tối đa 3 editor Unity mỗi máy** (người dùng đo; con số theo máy ghi trong `~/.pff/machine.env` nếu khác). Đây là trần cứng,
+  không phải mục tiêu.
+- **Slot = worktree cố định có Library ấm**, đặt tên và giữ suốt dự án (vd. `<wt_root>/cut|tai|b8`). Không tạo worktree mới cho mỗi
+  bước; bước sau `git checkout -B lane/<việc> origin/<main>` trong slot rảnh. Worktree hết dùng thì xoá (`git worktree remove`) sau khi
+  kiểm sạch + không còn commit chưa lên `<main>` — Library mỗi cái ~5-10 GB (sự cố 2026-10-26: 19 worktree bỏ quên chiếm ~95 GB).
+- **Agent không tự chạy Unity.exe / `-executeMethod`.** Mỗi slot có một editor có cửa sổ mở sẵn chạy cầu nối (Editor script
+  [InitializeOnLoad] đọc hàng đợi job file-based, sống qua domain reload, timeout + watchdog mỗi job); agent gửi job qua CLI
+  (`unity_slot.py start|submit --wait|status|stop <slot>`): `refresh_compile`, `editmode`, `playmode`, `smoke <mode> [res]`,
+  `screenshot`. Khoá slot để mỗi lúc một agent. Xong việc để editor mở cho lượt sau.
+- **Editor slot chạy ẩn cửa sổ** (từ 2026-10-28, PO không muốn thấy): `start <slot>` ẩn cửa sổ mặc định (`--show` để hiện),
+  `hide|show <slot>` chỉ tác động PID editor của slot, `status` in `window hidden|visible`. Cửa sổ ẩn (SW_HIDE) vẫn render Game view
+  kèm UI, play mode chạy frame, job cầu nối / unity CLI / `capture` y như cũ. Chỉ `show` khi có người yêu cầu xem, xong `hide` lại.
+- Lý do (đo DTU 2026-10-26): mỗi lần agent tự mở/đóng editor tốn 2-5 phút khởi động, hay để lại editor treo khoá dự án; qua cầu nối
+  smoke nhanh hơn ~28-55 s/job, kết quả trùng cách cũ. Agent tiếp nối (handoff) dùng lại đúng slot + nhánh, không mở slot mới.
+- Điều phối viên giữ bảng slot -> lane đang chạy; việc Unity mới xếp hàng theo slot rảnh, không vượt trần. Game chưa có cầu nối: bước
+  đầu tiên là dựng nó (bản tham chiếu: pff-tailor `Assets/Tailor/Editor/AgentBridge/` + `tools/unity_slot.py` + `Docs/qa/agent_bridge.md`).
+
+### 2.2 Unity CLI trên editor của slot (mặc định từ 2026-10-28, task rs5wj1g4)
+- **Mọi việc editor trực tiếp** (eval C#, sửa scene/asset, play mode, chụp ảnh, đọc console, test nhanh) dùng skill `unity:unity-cli`
+  nhắm vào editor ĐANG CHẠY của slot, luôn kèm `--project-path <worktree slot>` (3 editor cùng chạy; thiếu cờ thì CLI theo cwd và có
+  thể điều khiển nhầm worktree khác). `python tools/unity_slot.py cli <slot>` in đường dẫn + công thức. Job cầu nối vẫn dùng cho cổng
+  compile, chạy test đầy đủ, smoke/VisRun.
+- Giữ kỷ luật khoá slot (`lock`/`unlock --owner <task>`) và trần 3 editor. **Không bao giờ chạy Unity.exe trực tiếp** (kể cả
+  `unity open`, `-batchmode`); editor sập thì báo điều phối. Editor mở ngoài `unity_slot.py start` còn mất env lane (sandbox save/prefs).
+- Cần `com.unity.pipeline` 0.9.1-exp.1 (đã lên main pff-tailor e5bb7ca4; worktree cũ còn 0.8.0 dùng tên phẳng `eval`, `editor_play`).
+- Công thức chụp: `editor set_auto_tick -- --enable true` (một lần, nếu không eval timeout 5000 ms) → mở scene đã lưu →
+  `editor.playmode start` → `unity status --until-ready` → `job wait -- --condition '{"member":"UnityEngine.Time.frameCount","op":"changed"}' --timeout 10`
+  phải `met: true` → `python tools/unity_slot.py capture <slot> --out Logs/cli-render/x.png [--source camera]` (base64 → file, có kiểm
+  frame) → `editor.playmode stop`.
+- Bẫy: `capture game_view --save_path` luôn ghi vào `Assets/` (+ .meta) → không dùng, decode base64 ra file, KHÔNG in base64 vào ngữ
+  cảnh, chỉ xem bản thu nhỏ. `source=screen` (Game view + UI overlay) cần editor có cửa sổ (minimize hoặc ẩn vẫn được); batchmode chỉ có
+  `source=camera` (mất UI overlay). Editor đứng hình vẫn trả ảnh trông hợp lý → luôn kiểm frameCount trước.
+
+## 3. Lập lịch (điều phối viên + planner)
+- Một agent Unity mỗi lane tại một thời điểm. Bắt đầu 2 lane (trunk + b), lên 3 khi RAM/đĩa (mục 7) đạt.
+- Bước lane xong -> **bước integrator** trên trunk (sonnet/high; opus/medium nếu xung đột chạm code). Lane chờ integrator > 1 h hai
+  lần -> gộp mỗi 2 bước, hoặc lùi về 2 lane (`unity_lane_2`).
+- Chỉ trên trunk: cổng thiết bị, build Android, đổi schema save, sửa package dùng chung (puzzlecore/casualcore).
+- Integrator đường tắt: trunk HEAD == base merge-forward của lane (lane đã test đúng cây đó) -> compile + EditMode + smoke chính +
+  mode của lane (~10-15 phút). Khác -> EditMode + smoke en/vi + các mode ở mục 11 (~25 phút); vòng đầy đủ thứ hai chỉ sau khi sửa.
+
+## 4. Một editor mỗi đường dẫn dự án
+- Mọi Bash call của lane: `set -a; . <wt>/.lane.env; set +a` (đặt `UPROJ`, `UNITY_PROJECT_PATH`, `PFF_LANE`, `PFF_SAVE_SANDBOX`,
+  `ADB_SERIAL`, `UNITY_LOG`, `TMP`/`TEMP`). Trunk cũng export `UNITY_PROJECT_PATH` (có 2 editor thì tự dò bị mơ hồ).
+- Dự án không có editor mở -> "No Pipeline instance found", không fallback sang editor khác: đúng hành vi, không lách.
+- Trước khi mở editor: kiểm `Temp/UnityLockfile` và process có `-projectPath <đúng đường dẫn>` theo sau là dấu cách (khớp chính xác).
+
+## 5. Đóng editor
+- Chỉ đóng PID mình mở, bằng `EditorApplication.Exit(0)`. Cấm `CloseMainWindow()` lên mọi Unity.
+- Script đếm/chờ process phải khớp `-projectPath` chính xác (sự cố 2026-10-11: khớp lỏng `pff-dressmaker` dính cả
+  `pff-dressmaker-wt`, script khác đứng chờ và suýt đóng nhầm editor lane).
+- TaskStop không giết vòng bash nền: `ps` + `kill` PID còn sót trước khi chạy lại.
+
+## 6. Mở lần đầu
+- Import/compile batchmode trước: `Unity -batchmode -quit -projectPath <wt> -buildTarget <t> -logFile <log>`, rồi mới mở GUI
+  (import nguội lane sparse ~5.5 phút; mở lại GUI ~20 s).
+- Seed `Library` bằng robocopy từ trunk chỉ khi editor trunk đóng; đang mở thì import nguội.
+
+## 7. Ngưỡng đĩa / RAM
+- Ổ hệ thống (C:) >= 10 GB trước khi mở editor hoặc build; < 8 GB -> đóng lane cuối (c). Lane gần như không tốn C: (đo -0.04 GB)
+  khi TMP/TEMP, `-logFile`, Library, worktree nằm trên ổ dữ liệu.
+- **TMP/TEMP của agent và editor phải trỏ sang ổ dữ liệu** (`PFF_TMP`, mục "Nhiều máy"); shell mặc định vẫn dùng Temp trên C:.
+- Ổ dữ liệu còn >= 20 GB sau khi tạo lane (~5 GB/lane sparse: checkout ~1 + art giữ lại ~2 + Library ~2).
+- RAM: đỉnh x1.5 < RAM trống (đo: 2 editor GUI 6 GB WS / 8.4 GB private; 3 editor ~9-10 GB WS; một MuMu +4-6 GB).
+- Agent **không tự dọn C:**; báo người dùng kèm danh sách thủ phạm thường gặp: Docker WSL vhdx (lớn nhất, ~77 GB lúc đo),
+  `~/.gradle`, `%TEMP%`, `~/.cache`, npm-cache, cache trình duyệt. Sự cố 2026-10-13: C: 12 -> 3.4 GB không do lane.
+
+## 8. Cô lập trong một máy
+- Save: lane editor mặc định dùng sandbox `agent_sandbox/lane_<lane>` (env `PFF_SAVE_SANDBOX`), bỏ qua nút "REAL save" trong
+  EditorPrefs; chỉ `PFF_REAL_SAVE=1` trong env của chính lane đó mới trỏ vào save thật.
+- PlayerPrefs: facade `Prefs` thêm tiền tố `lane_<lane>.` khi có `PFF_LANE`; trunk giữ key gốc.
+- EditorPrefs là chung cả máy: đặt Interaction Mode = No Throttling một lần.
+- Play không focus bị đứng hình: hook `AgentPlayMode` bật `Application.runInBackground = true` cho phiên play của agent. Phiên RDP
+  ngắt: dùng `EditorApplication.Step` (`ustep`).
+- Kiểm hash save thật trước/sau mỗi chiến dịch test (phải không đổi).
+
+## 9. Khoá (trong một máy)
+- `DEVICE_LOCK`: MuMu + build Android, một cái một lúc (`lanes.py device-lock <lane>`, exit 3 = bận, thử lại sau).
+- `MERGE_LOCK`: không commit trunk khi đang merge.
+- `LFS_HOLD`: kiểm trước MỌI commit ở mọi lane (các worktree dùng chung một kho `.git/lfs`).
+- Vị trí: `PFF_LOCK_DIR` (mặc định `<wt_root>/locks`), **không đặt trong run dir** (run dir là nháp của một phiên, một máy).
+
+## 10. Commit / merge / push
+- Commit đúng đường dẫn của mình: `git commit -- <paths>`. Lane không commit lên `<main>`, không bao giờ push `lane/*`.
+- Merge-forward `<main>` vào lane ở đầu và cuối mỗi bước.
+- Integrator: trên nhánh cục bộ `integration/<id>`, `git merge --no-ff lane/<x>` (giữ MERGE_LOCK + LFS_HOLD chỉ quanh merge),
+  tái sinh asset sinh (LocTable, GameConfig, ...), compile, test. Đỏ -> bỏ nhánh, sửa ở lane bằng editor lane. Xanh -> MERGE_LOCK,
+  `git merge --ff-only` vào `<main>`, push thường (theo push policy của game). Kẹt / khoá / LFS: mục 14.
+- File nóng: smoke mode mới = file partial mới; dòng CSV thêm ở cuối; asset sinh không merge tay, luôn tái sinh.
+
+## 11. DoD bước lane
+- EditMode tất cả (số test >= trước) + smoke chính (en + vi) + mode của bước + **mọi smoke mode lái màn hình mà bước đổi** (brief
+  liệt kê). Chạy trong lane sau merge-forward `<main>` mới nhất.
+- Smoke chờ theo điều kiện (`Until(cond, max)`, ngân sách thời gian thực), không đếm tap/frame cố định (gây 3 lần flake ở pilot).
+
+## 12. Rollback
+- Merge phải sửa code ở cả hai miền hai lần -> gộp cặp đó vào một lane.
+- Editor lane crash / lỗi license -> đóng lane, giữ nhánh, cherry-pick sang trunk.
+
+## 13. Máy mới (phần dieu-phoi)
+1. `npm i -g @kienntpixon/dieu-phoi`.
+2. Cài `ai-lab/dieu-phoi` từ Skill Hub vào `~/.claude/skills/dieu-phoi` (skill `skill-hub`: install / tải zip).
+3. `dieu-phoi setup --dept ai-lab --sink-url <url> --sink-token <...>`: URL + sink token lấy từ trưởng phòng (password manager /
+   nhắn trực tiếp), không ghi vào file nào trong repo hay tài liệu. Khởi động lại Claude Code; `dieu-phoi doctor --net`.
+4. Tạo `~/.pff/machine.env` (mục "Nhiều máy") từ mẫu `tools/templates/machine.env.example` của toolset.
+5. Auto-memory của Claude không theo máy: điều cần biết đã nằm trong file này + `docs/machine-setup.md` của toolset.
+6. Toolchain Fast Forward (Unity, MuMu, git-lfs, Python, gws...): `docs/machine-setup.md` trong repo ai-lab/pixon-fast-forward.
+
+## 14. Xử lý kẹt (stuck)
+
+Rút từ sự cố thật 2026-10-11..13 (3-4 lane + integrator trên một máy). "Treo" hiếm khi do mạng hay LFS: thường là một hộp thoại
+modal không ai thấy, một khoá bị giữ quá lâu, hoặc một agent chờ thứ không tồn tại. Điều phối viên không tự soi bằng shell (luật
+không tự làm): nhắn agent đang kẹt bằng `SendMessage`, hoặc giao một agent `debug` chạy lệnh soi ở 14.3.
+
+### 14.1 Watchdog của điều phối viên (không bao giờ ngồi chờ)
+- Mỗi agent Unity/git đang chạy: hẹn giờ kiểm (Monitor / ScheduleWakeup) mỗi `min(15 phút, ½ budget_s)`. Tín hiệu kẹt: không có
+  thông báo tiến độ mới > 15 phút; cùng một trạng thái lặp >= 2 lần ("Waiting.", "merging...", "waiting for MERGE_LOCK"); agent nói
+  đang chờ khoá / Unity / thiết bị / push.
+- Bước 1, hỏi trạng thái (`SendMessage`, một câu): "Trả lời <= 3 dòng: đang chờ gì, từ lúc nào, PID / khoá / lệnh nào đang chặn."
+- Bước 2: 10 phút sau vẫn không tiến, hoặc câu trả lời khớp một triệu chứng ở 14.2 -> gửi đúng các dòng brief của triệu chứng đó.
+  Cần soi máy (process, khoá, C:) mà agent kẹt không tự làm được -> giao agent `debug` (sonnet/medium, <= 15 phút) chạy 14.3, chỉ
+  báo cáo, không kill thứ không phải của mình.
+- Bước 3: vẫn kẹt hoặc quá `budget_s` -> `TaskStop` + `verdict <id> timeout --reason looping|over-budget` (watchdog trong
+  `references/verify.md`). Khoá / PID của agent đã dừng: giao agent mới gỡ, kèm danh sách PID / khoá cụ thể.
+- Trong lúc một lane chờ: giao bước không phụ thuộc (không Unity, QIS, docs) hoặc báo người dùng một dòng đang chờ gì, tới khi nào.
+  Thông báo "Waiting." lặp của agent nền: không trả lời từng cái, chỉ theo đồng hồ ở trên.
+- Verifier / agent chờ Unity mà dự án không có editor nào chạy (sự cố: ~80 phút im) = kẹt. Brief verifier: "5 phút không thấy editor
+  của dự án -> tự mở theo mục 6 (batchmode trước), hoặc báo `BLOCKED` ngay; không chờ."
+
+### 14.2 Theo triệu chứng: phát hiện -> dòng brief -> gỡ an toàn
+1. **`git merge` / `git merge-tree` treo 25-40 phút, trông như LFS.** Nguyên nhân thật: merge driver UnityYAMLMerge chạy
+   `merge -p` không có `--force` nên không nhận file tạm `.merge_file_*` của git, đi tìm tool GUI dự phòng và mở MessageBox
+   "UnityYAMLMerge Error" mà không ai thấy. Không có process git-lfs nào; LFS và credential vẫn khoẻ. `merge-tree` (preview) cũng chạy driver.
+   - Phát hiện: process `git` có cây con `sh -> UnityYAMLMerge.exe merge ...`, có cửa sổ tiêu đề "UnityYAMLMerge Error", CPU ~0.
+   - Brief: "git chỉ qua `lanes.py git --timeout <s> -- ...`, `lanes.py merge-forward`, `lanes.py push` (bản lanes.py có các lệnh
+     này; chưa có thì merge-forward `<main>` trước). git treo -> in cây process con + tiêu đề cửa sổ, không đoán từ dòng log cuối."
+   - Gỡ: kill đúng PID git của mình kèm cây con (`taskkill /T /F /PID <pid>`), `git merge --abort`; xoá `.git/index.lock` (hoặc
+     lock của worktree) chỉ khi không còn git nào chạy trên worktree đó. Chạy `lanes.py merge-driver` (ghi vào `.git/config` chung,
+     phủ mọi worktree: `timeout -k 5 120 UnityYAMLMerge merge -h -p --force`, lỗi thì khôi phục bản ours rồi `git merge-file` ghi
+     marker) rồi `lanes.py merge-forward`. Khẩn cấp khi chưa có driver mới: `git -c merge.unityyamlmerge.driver=false merge ...` -> mọi
+     file dùng driver thành conflict giữ bản ours, không marker; asset sinh thì tái sinh, còn lại chọn bản rồi `git add`. Không dùng
+     `--fallback none` (ghi theirs vào %A, rc 2).
+2. **git-lfs smudge / fetch / push chậm, hoặc push báo "unable to migrate objects to permanent storage".** Nguyên nhân: `git lfs
+   checkout` cả cây (~10 phút mỗi lane), `git lfs fetch <ref>` không `--include` (kéo cả ref ~9 GB vào kho trống), nhiều lane tải
+   cùng lúc. Lỗi "migrate objects" là lỗi tạm phía GitLab; commit thường đã lên.
+   - Brief: "merge với `GIT_LFS_SKIP_SMUDGE=1` (`lanes.py merge-forward` làm sẵn, timeout cứng 900 s), sau đó chỉ kéo file đổi:
+     `lanes.py lfs-pull --changed-since <rev>` hoặc `--include <path>`. Cấm `git lfs checkout` / `git lfs fetch` cả cây. Push bằng
+     `lanes.py push` (tự thử lại lỗi migrate / 5xx / timeout, coi là xong nếu origin đã có HEAD)."
+   - Gỡ: trước khi push lại, `git fetch` rồi `git branch -r --contains HEAD`: đã có thì thôi. Thao tác mạng chạy tuần tự qua
+     `GIT_NET_LOCK` trong `PFF_LOCK_DIR` (giữ trong một thao tác; PID chết hoặc > 45 phút = cũ, được lấy lại).
+3. **MERGE_LOCK / LFS_HOLD bị giữ hàng giờ, nhiều agent xếp hàng** (sự cố: integrator giữ ~1.5 h trong lúc test, 4 agent chờ, một
+   agent chờ ~95 phút).
+   - Phát hiện: `lanes.py locks` (holder + tuổi khoá). Khoá > 30 phút là bất thường.
+   - Brief integrator: "MERGE_LOCK / LFS_HOLD chỉ giữ quanh merge, commit, fast-forward, push (tính bằng phút). Test chạy trên
+     `integration/<id>` không giữ khoá."
+   - Brief người chờ: "khoá bận -> làm phần không commit trước, kiểm lại mỗi 5 phút, quá 30 phút báo
+     `STATUS: partial — waiting-lock <holder>`. Không xoá khoá của người khác."
+   - Gỡ: holder còn sống -> nhắn holder nhả khoá giữa các lượt test. Holder đã chết (agent đã dừng, PID không còn) -> giao agent
+     `lanes.py unlock` kèm tên holder (hỏi người dùng nếu holder là phiên khác).
+4. **Merge cục bộ của integrator bị push lên origin theo push của agent khác; agent commit nhầm lên nhánh integration.**
+   - Integrator merge trên nhánh cục bộ `integration/<id>`; xanh mới lấy MERGE_LOCK, `git merge --ff-only` vào `<main>`, push. Đỏ ->
+     bỏ nhánh (`<main>` chưa bao giờ chứa merge chưa test).
+   - Trunk đang checkout `integration/<id>` -> agent khác không commit trong checkout trunk (commit rơi vào nhánh integration): commit
+     ArtIncoming / docs từ worktree tạm (`git worktree add <wt_root>/tmp/<task_id> <main>`), hoặc chờ trunk về `<main>`.
+   - Mọi commit / push trên trunk tôn trọng MERGE_LOCK. Trước commit: `git branch --show-current` phải đúng nhánh brief ghi.
+   - Gỡ: commit lỡ trên nhánh sai -> cherry-pick sang đúng nhánh; đã push thì sửa bằng commit mới (revert), không force.
+5. **Script nháp đè nhau, đóng editor của lane khác.** Các agent song song dùng chung scratchpad của phiên; runner cùng tên
+   (`smokes.sh`) ghi đè nhau và đóng editor lane khác.
+   - Brief: "script / file tạm / log của bạn chỉ nằm trong `<wt_root>/tmp/<lane>/<task_id>/`; không đặt runner trong scratchpad của
+     phiên; script chỉ đụng editor có `-projectPath` đúng của bạn (mục 4-5)."
+6. **C: tụt dưới ngưỡng giữa chừng** (12 -> 3.4 GB không do lane; một integrator tự xoá npx cache, log Claude, temp của VS: vi phạm).
+   - Phát hiện: `lanes.py paths` (C: free) hoặc `Get-PSDrive C`.
+   - Brief: "Không bao giờ xoá gì ngoài repo / worktree / tmp lane của bạn. C: < 10 GB -> dừng ở điểm an toàn, báo
+     `STATUS: partial — disk-low <GB>`; không tự dọn."
+   - Gỡ: điều phối viên báo người dùng kèm danh sách thủ phạm ở mục 7; < 8 GB đóng lane cuối.
+7. **Unity Safe Mode / hộp thoại modal chặn editor hoặc batchmode** ("Enter Safe Mode?" khi mở dự án đang lỗi compile; hộp thoại
+   import / nâng cấp / khoá dự án).
+   - Phát hiện: process Unity đúng `-projectPath`, log đứng, có cửa sổ tiêu đề hộp thoại (14.3).
+   - Brief: "compile batchmode (`-batchmode -quit -logFile <log>`, có timeout cứng) trước khi mở GUI; có `error CS` thì sửa trước;
+     gặp hộp thoại Safe Mode: không vào Safe Mode, đóng editor của bạn và sửa lỗi compile."
+   - Gỡ: editor của mình kẹt hộp thoại, không nhận `EditorApplication.Exit(0)` -> `Stop-Process -Id <PID mình mở>` (chỉ PID đó;
+     mục 5 vẫn cấm `CloseMainWindow()` lên mọi Unity), xoá `Temp/UnityLockfile` của đúng dự án đó, compile batchmode lại.
+8. **adb / MuMu chết, touch kẹt** (adb server :5037 chết liên tục, adb.exe của Unity SDK crash 0xc0000409, thiết bị offline).
+   - Brief: "một adb duy nhất (`ADB_SERIAL`, luôn cùng một adb.exe), giữ DEVICE_LOCK. adb offline -> `adb kill-server`, rồi
+     `MuMuManager control -v <index> restart` (giữ dữ liệu), đọc lại cổng bằng `MuMuManager info -i <index>` (cổng có thể đổi).
+     Touch kẹt -> gửi lại sự kiện nhả / back, không được thì khởi động lại app. Trước QA thiết bị: sao lưu save của app
+     (`adb shell run-as <pkg>` / backup), khôi phục sau (MuMu đang chơi save thật của người dùng)."
+9. **Smoke flake ở tap đầu khi nhiều editor chạy.** Brief: "trước tap đầu chờ theo điều kiện <= 30 s (`Until`), không đếm frame;
+   flake 1 lần -> chạy lại đúng một lần, lặp lại -> báo, không vòng thử."
+10. **GitLab bảo trì (không push được).** Phát hiện: push 5xx / 503 / trang maintenance. Brief: "commit cục bộ, ghi
+    `PUSH PENDING (GitLab maintenance)` trong báo cáo; tối đa 3 lần với back-off, không thử dồn dập." Điều phối viên đánh dấu bước
+    "chờ push", không chặn bước khác; GitLab về thì giao agent `lanes.py push`.
+
+### 14.3 Lệnh soi (agent `debug` chạy, điều phối viên không chạy)
+```powershell
+# Unity của đúng một dự án (khớp -projectPath chính xác, mục 4)
+Get-CimInstance Win32_Process -Filter "Name='Unity.exe'" | ? { $_.CommandLine -like '*-projectPath <path> *' -or $_.CommandLine -like '*-projectPath "<path>"*' } | select ProcessId,CreationDate
+# cây con của một git treo (lặp với từng PID con) + cửa sổ có tiêu đề
+Get-CimInstance Win32_Process -Filter "ParentProcessId=<pid>" | select ProcessId,Name,CommandLine
+Get-Process | ? MainWindowTitle | select Id,ProcessName,MainWindowTitle
+```
+Kèm `lanes.py locks` (holder, tuổi khoá) và `lanes.py paths` (C: free). `lanes.py git --timeout` tự in cây process và tiêu đề cửa
+sổ khi hết giờ, rồi kill cây đó và xoá index.lock nó để lại.
+
+### 14.4 Phòng ngừa: dòng bắt buộc trong mọi brief bước Unity / git
+- `set -a; . <wt>/.lane.env; set +a`; `lanes.py env` đã xuất `GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never GIT_MERGE_AUTOEDIT=no
+  GIT_EDITOR=true`. Không có `.lane.env` thì tự export 4 biến đó.
+- Không lệnh git / lfs / Unity / adb nào chạy không có trần thời gian (`lanes.py git --timeout`, `timeout`, `-batchmode -quit`).
+- Script và file tạm trong `<wt_root>/tmp/<lane>/<task_id>/`. Không xoá gì ngoài repo / worktree / tmp của mình; C: < 10 GB -> dừng, báo.
+- Integrator merge trên `integration/<id>`, ff `<main>` sau khi xanh; khoá chỉ quanh merge / commit / push.
+- Trước commit: `git branch --show-current` đúng nhánh; `git commit -- <paths>`.
+- Chỉ kill PID mình mở và git con của mình.
+- QA thiết bị: sao lưu save app trước, khôi phục sau.
+- Chờ bất cứ thứ gì (khoá, Unity, thiết bị, push): tối đa 30 phút rồi báo `STATUS: partial — waiting-<thứ>`, không chờ im.
+
+## Nhiều máy
+
+Fast Forward + dieu-phoi (cùng profile ai-lab) chạy trên nhiều máy cùng lúc. Nguyên tắc: thứ máy khác phải thấy đi qua **git
+(GitLab)** hoặc **Skill Hub**, không bao giờ qua thư mục cục bộ (run dir, memory, `~/.claude`). File chung: hoặc mỗi file một người
+ghi (file theo máy), hoặc merge bằng `git merge` thường. Không force push, không rebase commit đã push.
+
+### Cấu hình theo máy: `~/.pff/machine.env`
+Ngoài mọi repo; lanes.py, wrapper `tools/bin` và brief agent đều source file này. Mẫu chỉ có placeholder.
+
+| biến | mặc định khi trống | dùng cho |
+|---|---|---|
+| `PFF_MACHINE` | hostname (chữ thường) | inbox bài học, tên nhánh, tag job, tên APK |
+| `PFF_DATA_ROOT` | ổ dữ liệu nếu có (vd. `D:/`), không thì `~` | gốc của các biến dưới |
+| `PFF_WT_ROOT` | `<project>-wt` cạnh project | worktree lane |
+| `PFF_LOCK_DIR` | `<PFF_WT_ROOT>/locks` | DEVICE_LOCK, MERGE_LOCK, LFS_HOLD |
+| `PFF_TMP` | `<PFF_DATA_ROOT>/pff-tmp` | TMP/TEMP của agent và editor, file kết quả `ujob` |
+| `PFF_UNITY_HUB_EDITORS` | thư mục Editor của Unity Hub | Unity theo `ProjectSettings/ProjectVersion.txt` |
+| `UNITY_CLI` | `unity.exe` của Unity CLI trong LocalAppData | `tools/bin` |
+| `ADB_SERIAL`, `PFF_MUMU_INDEX` | từ `MuMuManager info -i <index>` | device QA, adbshot, lanes |
+| `DIEU_PHOI_RUNS_DIR` | `~/.dieu-phoi/runs` | dieu-phoi CLI |
+| `QIS_MAX_INFLIGHT`, `ATLAS_MAX_INFLIGHT` | 2 | job đồng thời của máy này |
+
+Run dir là nháp của một máy: contract/báo cáo mà máy khác cần phải chép vào repo game (`Docs/` hoặc `Reports/`) trước khi bước kết thúc.
+
+### Máy maintainer
+- **Một** máy publish lên Skill Hub. Mặc định: máy chính của người dùng (ví dụ, máy này lúc viết: `desktop-l730gt6`); đổi máy thì
+  sửa dòng này và báo cả phòng.
+- Publish chỉ từ HEAD của `main` trên GitLab, luôn tăng version; Hub từ chối version trùng, nên hai máy publish chồng nhau sẽ lộ ra.
+- Máy khác không publish: chỉ push file inbox bài học.
+
+### Bài học trên nhiều máy
+- `profile/lessons.md` publish = danh sách đã tuyển (nguồn duy nhất, trong repo nguồn ai-lab/dieu-phoi).
+- Dòng ghi `>>` trên một máy chỉ ở máy đó. `tools/lessons_sync.cjs harvest` chép dòng chỉ-có-ở-máy vào `lessons-inbox/<PFF_MACHINE>.md`
+  (gốc repo, ngoài `skill/`), commit + `git pull --no-rebase` + push thường. Mỗi máy một file inbox -> không xung đột.
+- Máy vừa cài từ Hub chưa có `profile/.lessons.published.md`: lần chạy đầu của `lessons_sync` (`status` / `harvest` / `update`) tự
+  tạo nó từ `lessons.md` đã cài (mọi dòng coi là đã publish). Chạy `lessons_sync status` ngay sau khi cài, trước khi `>>` bài học mới.
+- `lessons_sync update`: harvest -> tải bản Hub mới -> thay skill -> nối lại cuối file các dòng cục bộ chưa vào bản tuyển ->
+  `dieu-phoi setup` -> `dieu-phoi doctor`. Không cài đè skill bằng tay (mất dòng cục bộ).
+- Retro trên máy maintainer: đọc `lessons-inbox/*.md`, gộp vào `skill/profile/lessons.md`, chuyển dòng đã gộp sang
+  `lessons-inbox/merged/<date>.md`, commit, publish version mới.
+
+### Sink chung
+Mọi máy dùng cùng sink của phòng (setup ở mục 13). Sink chỉ nhận event (metrics + nhãn), không nhận bài học hay profile.
+`choose` / `stats` đọc event cục bộ, nên máy mới bắt đầu từ prior cho tới khi có dữ liệu riêng: chấp nhận.
+
+### Chia việc giữa các máy
+- Như lanes, một tầng trên: kế hoạch đã duyệt gán cho mỗi bước Unity một `machine` (và `unity_lane` trong máy đó). Một miền không ở
+  hai máy cùng lúc. Kế hoạch nằm trong repo game (`Docs/plan/assignments.json`), không trong run dir.
+- Khoá (mục 9) chỉ có hiệu lực trong một máy (mỗi máy có clone, kho `.git/lfs`, emulator riêng). Phối hợp giữa máy = git.
+
+### Claim trước khi làm
+- `Docs/plan/claims.md` trong repo game, mỗi bước một dòng: `<step> <machine> <utc> <branch>`.
+- Commit claim rồi push. Push bị từ chối non-fast-forward = máy khác push trước -> fetch + merge + kiểm lại claim; **claim push trước
+  thắng**. git push là khoá nguyên tử, không cần server thêm.
+- `.gitattributes` của repo game có `Docs/plan/claims.md merge=union`: hai máy claim bước khác nhau thì merge giữ cả hai dòng,
+  không xung đột. Trùng **cùng một bước**: dòng đã có trong origin (push sớm nhất) thắng; máy thua xoá dòng của mình, push, rồi
+  lập lại kế hoạch sang bước khác. Không xoá dòng của máy khác.
+
+### Nhánh và push
+- `<main>` = việc đã tích hợp. Mỗi máy tích hợp trên trunk của mình và tự push `<main>` sau khi xanh (không có máy integrator duy nhất).
+- `lane/*` chỉ ở máy, không bao giờ push. Được push `m/<machine>/<topic>` để sao lưu/bàn giao; xoá sau khi merge.
+- Giao thức push (mọi máy): `git fetch` -> `git merge --no-ff origin/<main>` vào trunk (mặc định `git pull --no-rebase`; chỉ rebase
+  commit cục bộ chưa push) -> tái sinh asset sinh -> kiểm ngắn (compile + EditMode + smoke chính + mode bước chạm) -> `git push`
+  thường. Non-fast-forward -> lặp lại, tối đa 3 lần rồi hỏi người dùng. Cấm `--force` / `--force-with-lease` trên nhánh chung.
+  Chỉ push việc đã kiểm (push policy của game).
+- Binary/YAML không merge được (`*.png`, `*.psd`, `*.unity`, `*.prefab` ở thư mục chung): ưu tiên chia miền; chỉ khi hai máy buộc
+  phải sửa cùng file mới `git lfs lock <path>` và nhả trong cùng bước. **Không** đặt thuộc tính `lockable` (làm mọi file LFS chỉ-đọc,
+  hỏng tool của agent).
+
+### QIS / Atlas dùng chung
+- Danh sách job + trạng thái nằm trong repo game (mỗi job một dòng, `status` = todo / claimed:<machine> / done); claim như trên.
+- Mặc định **2 job đồng thời mỗi máy** (`QIS_MAX_INFLIGHT`, `ATLAS_MAX_INFLIGHT`) cho tới khi chủ hub cho số thật.
+- Tag job / tên file ra có tiền tố `<machine>`. Gặp 429 / hết quota: back-off luỹ thừa (30 s -> 10 phút), rồi
+  `STATUS: partial — quota-pause`; không vòng thử lại dồn dập.
+- Credential mỗi máy trong `<toolset>/.env` (gitignore), nhận ngoài luồng; script đọc trong process, không bao giờ in ra.
+
+### Emulator / thiết bị
+- **Mỗi máy một emulator** (MuMu riêng: `PFF_MUMU_INDEX` + `ADB_SERIAL` trong `machine.env`), DEVICE_LOCK cục bộ.
+- Cổng thiết bị của milestone chạy trên máy đã tích hợp build milestone đó. Tên APK `<game>-<commit>-<machine>.apk` (upload Drive
+  theo policy của game). Điện thoại thật dùng chung cần người cầm: không tự động.