merge: merge origin/gamma/refactor and origin/feature/teamhoa/r05-r06 into feature/delta-team/epic-R04

docs/refactor/BaoCao_TeamDuy_R01_R03_R04.md

@@ -0,0 +1,233 @@
+# BÁO CÁO KẾT QUẢ — TEAM DUY: EPIC R01, R03, R04
+
+* **Dự án**: Cowork Local (Cowork-Local BamBOO)
+* **Team**: 🔵 Team Duy — Core AI, Routing, Turn Runtime & Testing (Tech Lead)
+* **Nhánh**: `feature/deltateam/refactor-plan`
+* **Thời gian thực hiện**: 21/08/2026, 09:56 ➔ 10:56
+* **Ngày báo cáo**: 21/08/2026
+* **Tài liệu gốc**: `Feature_Architecture_Proposal.md`, `Refactoring_Checklist.md`, `DeltaTeam_prompt.md`
+
+---
+
+## 1. Tóm tắt điều hành
+
+Hoàn tất **16/16 task** của 3 EPIC được giao trong đợt này: **R01** (nền tảng kiến trúc & lưới an toàn), **R03** (hợp nhất provider & routing), **R04** (vòng đời turn hội thoại). Toàn bộ đã commit và push lên nhánh.
+
+| Chỉ số | Kết quả |
+| :--- | :--- |
+| Task hoàn thành | **16/16** (R01: 5, R03: 6, R04: 5) |
+| Commit | 5 |
+| File thay đổi | 48 (37 file mới, 11 file sửa) |
+| Dòng code | +5.843 / −225 |
+| Test | **243 pass** / 44s |
+| Test suite nhanh (unit + contract + characterization + routing) | **218 pass / 1,22s** |
+| CASAN Check 3 (`scripts/check_imports.py`) | **PASS** — 0 Qt import trong `domain/`, `application/` |
+| File production > 400 dòng | **0** |
+
+**3 lỗi thật được phát hiện và sửa trong quá trình làm** (chi tiết mục 5) — trong đó 1 lỗi deadlock sẽ làm treo ứng dụng ngay ở tin nhắn đầu tiên.
+
+---
+
+## 2. Kết quả theo từng EPIC
+
+### 🔹 EPIC R01 — Architecture Foundation & Characterization (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R01-T01 | `docs/architecture/ADR-001-layered-architecture.md` | Định nghĩa 4 tầng, chiều phụ thuộc, 6 quy tắc bất biến I1–I6, chiến lược di trú Strangler Fig |
+| R01-T02 | `tests/fakes/fake_provider.py`, `fake_tool_executor.py` | Test double chạy offline, kịch bản hoá, ghi lại mọi lời gọi |
+| R01-T03 | `scripts/check_imports.py` (239 dòng) | Quét AST, bắt cả import tương đối (`from ...ui import x`) và import trong thân hàm |
+| R01-T04 | `tests/characterization/test_run_cowork.py` | **13 test** chụp snapshot hành vi hiện tại của `run_cowork` trước khi R04 đụng vào |
+| R01-T05 | `docs/architecture/dormant-code.md` | Quét đồ thị import: 43 module "không ai import" ➔ xác minh còn **6 hạng mục chết thật (~1.887 dòng)** |
+
+**Điểm đáng chú ý ở R01-T03**: dùng AST thay vì `grep` là bắt buộc — trong repo có nhiều docstring nhắc tên `PySide6` một cách hợp lệ, `grep` sẽ báo nhầm và đội sẽ học cách tắt cổng kiểm duyệt.
+
+**Điểm đáng chú ý ở R01-T05**: 43 module không có importer **không** đồng nghĩa 43 module chết. Sau xác minh thủ công: `__main__.py` là entry point, `mcp_servers/ms365_server.py` chạy bằng subprocess (`state.py:285`), 34 file `tools/check_*.py` là dev tooling chạy tay. Chỉ 6 hạng mục là dormant thật.
+
+### 🔹 EPIC R03 — Model Providers & Routing (6/6)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R03-T01 | `tests/contracts/test_providers.py` | **29 contract test**; chạy được cả 2 adapter thật mà **không cần mạng** nhờ thay `Provider._request` bằng SSE đóng hộp |
+| R03-T02 | `domain/models/provider_descriptor.py`, `infrastructure/providers/provider_registry.py` | Gom 3 nơi khai báo provider về 1 chỗ |
+| R03-T03 | `application/model_routing/routing_application_service.py` | Pure Python, 4 chế độ: Off / Auto / Manual / **Fallback (mới)** |
+| R03-T04, T05 | `ui/chat_panel.py`, `ui/co4e_tab.py`, `ui/folder_tab.py` | Gỡ 3 bản sao logic routing |
+| R03-T06 | `infrastructure/telemetry/usage_sink.py` | Tách ghi nhận token usage khỏi provider |
+
+**Vấn đề gốc đã giải quyết** — cùng một thuật toán routing tồn tại **3 bản gần giống nhau**:
+
+```
+ui/chat_panel.py::_apply_routing       (~45 dòng)
+ui/co4e_tab.py::_apply_co4e_routing    (~38 dòng)
+ui/folder_tab.py::_ai_apply_routing    (~42 dòng)
+```
+
+Cả 3 đều nằm trong widget Qt ➔ **không thể test nếu không dựng cửa sổ**, và đã bắt đầu lệch nhau (mỗi bản xác định "model hiện tại" một kiểu). Nay cả 3 chỉ còn gọi `ctx.routing_application().route_turn(...)` + một callback xác nhận.
+
+**Chế độ Fallback (mới)**: giữ nguyên model người dùng chọn, **chỉ đổi sau khi model đó lỗi**. Đây là chế độ người dùng cần khi họ tin lựa chọn của mình nhưng vẫn muốn lượt chat sống sót qua sự cố nhà cung cấp.
+
+**Bộ từ vựng mode**: trước đây tuple `("off", "auto", "manual")` bị lặp ở **4 chỗ** (`config.py` × 2, `state.py` × 2). Thêm một mode mà quên một chỗ sẽ **âm thầm hạ lựa chọn của người dùng về "off"**. Nay tập trung vào `normalize_mode()` / `is_valid_mode()`.
+
+### 🔹 EPIC R04 — Agent Runtime & Conversation Service (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R04-T01 | `domain/agents/conversation_execution_request.py` | Frozen dataclass, chụp toàn bộ input của 1 turn tại thời điểm submit |
+| R04-T02 | `domain/agents/agent_event.py` (370 dòng) | **13 event có kiểu** thay cho dict không kiểu, kèm cầu nối 2 chiều |
+| R04-T03 | `application/conversations/conversation_application_service.py` | Điều phối vòng đời turn, không import Qt |
+| R04-T04 | `ui/cowork_tab.py::build_job` | Chuyển sang snapshot + service |
+| R04-T05 | `core/task_executors.py::_run_agent` | Chuyển sang **cùng** service (trước đây là bản lắp ráp thứ hai, hơi khác) |
+
+**Vấn đề gốc đã giải quyết** — closure trong `build_job` đọc state của widget **từ trong worker thread**:
+
+```python
+def job(worker):
+    provider = self.build_provider()                  # đọc combo box
+    proj_ctx = project_context_text(load_project(project_id))
+```
+
+Người dùng có thể đổi model, đổi workspace, sửa chỉ dẫn project **trong lúc turn đang chạy**. Turn khi đó chạy trên hỗn hợp state cũ + mới, và hỗn hợp nào phụ thuộc vào thời điểm luồng — đúng loại bug tái hiện mỗi tuần một lần và không bao giờ tái hiện trong test.
+
+**`TurnCompletedEvent`** là tín hiệu kết thúc turn mà engine cũ **hoàn toàn không có**: hiện tại mọi consumer suy ra "xong" từ việc worker thread kết thúc, nên **turn bị huỷ và turn thất bại trông giống hệt nhau** với giao diện.
+
+---
+
+## 3. Kiến trúc sau refactor
+
+```text
+presentation/  ui/chat_panel.py, ui/co4e_tab.py, ui/folder_tab.py, ui/cowork_tab.py
+      │        (chỉ dựng UI, mở dialog xác nhận, render thông báo)
+      ▼
+application/   model_routing/routing_application_service.py    ← 4 mode routing
+               conversations/conversation_application_service.py ← vòng đời turn
+      │        (100% pure Python — cổng kiểm duyệt tự động chặn import Qt)
+      ▼
+domain/        agents/conversation_execution_request.py  ← snapshot bất biến
+               agents/agent_event.py                     ← 13 event có kiểu
+               models/provider_descriptor.py             ← catalog provider
+      ▲
+infrastructure/ providers/provider_registry.py   telemetry/usage_sink.py
+```
+
+**Nguyên tắc di trú (ADR-001 mục 4)**: **không viết lại engine**. `core/chat_agent.py::run_cowork` và `core/routing/*` (2.263 dòng, 79 test đang xanh) vẫn là engine bên dưới; tầng application chỉ sở hữu phần trước đây bị trộn vào UI. Nhờ vậy `pytest` luôn xanh giữa các bước và một team có thể merge mà không phải chờ team khác.
+
+---
+
+## 4. Bằng chứng kiểm thử
+
+### Phân bố test
+
+| Suite | Số test | Thời gian | Vai trò |
+| :--- | ---: | ---: | :--- |
+| `tests/unit/` | 97 | | Logic thuần, không Qt/mạng |
+| `tests/contracts/` | 29 | | Mọi provider phải thoả cùng bộ cam kết |
+| `tests/characterization/` | 13 | | Chốt hành vi hiện tại của `run_cowork` |
+| `tests/routing/` | 79 | | Có sẵn từ trước, vẫn xanh |
+| **Cộng 4 suite nhanh** | **218** | **1,22s** | ✅ đạt CASAN "A — unit < 1s" |
+| `tests/integration/` | 25 | 42s | Widget Qt thật (offscreen) + provider kịch bản hoá |
+| **Tổng** | **243** | **44s** | |
+
+### Đối chiếu Definition of Done (7 tiêu chí, `DeltaTeam_prompt.md`)
+
+| # | Tiêu chí | Kết quả |
+| :--- | :--- | :--- |
+| 1 | Mọi file < 400 dòng | ✅ Lớn nhất: `agent_event.py` 370 dòng |
+| 2 | 0 import Qt trong `domain/`, `application/` | ✅ `check_imports.py` PASS |
+| 3 | Comment tiếng Anh ở mọi khối sửa/mới | ✅ Docstring + giải thích **lý do**, không chỉ mô tả code |
+| 4 | Có unit/contract test, pass 100% < 1s | ✅ 218 test / 1,22s |
+| 5 | Không hồi quy | ✅ 79 test routing có sẵn vẫn xanh |
+| 6 | Ghi Start/End vào Checklist | ✅ 16 task đã tick kèm mốc thời gian |
+| 7 | Cổng CASAN | ⚠️ `run_quality_gate.py` thuộc **R10-T02**, chưa viết. Check 3 đã có và PASS |
+
+### Ba đường code đã sửa nhưng ban đầu chưa được thực thi
+
+Sau khi hoàn tất 16 task, rà soát lại phát hiện 3 đường code đã bị sửa nhưng **không test nào chạy qua**. Đã bổ sung **18 test**:
+
+| Đường code | Rủi ro nếu bỏ qua | Test bổ sung |
+| :--- | :--- | ---: |
+| `task_executors._run_agent` | Autosave History có thể đóng băng ở tin nhắn đầu | 7 |
+| `_apply_co4e_routing` / `_ai_apply_routing` | Mới chỉ import được, chưa từng gọi hàm | 11 |
+| `confirm_switch(decision)` Manual mode | Thiếu field ➔ **nổ bên trong modal**, nơi khó phát hiện nhất | (nằm trong 11 ở trên) |
+
+---
+
+## 5. Ba lỗi thật phát hiện trong quá trình làm
+
+### 🔴 Lỗi 1 — Deadlock khi khởi tạo routing service
+
+`AppContext.routing_application()` giữ `_routing_lock` rồi gọi `routing()`, vốn cũng lấy **chính lock đó**. `threading.Lock` không reentrant ➔ **treo cứng ngay ở tin nhắn đầu tiên**, không có thông báo lỗi.
+
+*Sửa*: tách `_routing_app_lock` riêng, và resolve engine **trước khi** lấy lock.
+
+### 🟠 Lỗi 2 — Event `notice` bị cầu nối nuốt mất
+
+Bản đầu của `agent_event.py` liệt kê 12 loại event nhưng **thiếu `notice`**. Trong khi đó `notice` được phát ra từ 3 nơi trên đường chạy bình thường:
+
+* `core/agent_security.py` — yêu cầu/lệnh bị Agent Security **chặn**
+* `core/context_budget.py` — hội thoại vừa bị tự động nén
+* Bộ đọc file đính kèm — file không xử lý được, và tiến độ "đang đọc trang X/Y"
+
+Cầu nối bỏ qua event không nhận diện được (đúng thiết kế, để engine có thể thêm event mới) — nên **người dùng sẽ không bao giờ thấy cảnh báo bảo mật**, hoàn toàn im lặng.
+
+*Sửa*: thêm `NoticeEvent`, **và** thêm test quét mã nguồn engine tìm mọi tag `emit({"type": ...})` rồi bắt lỗi nếu có tag nào chưa có event tương ứng — biến sự im lặng thành test đỏ.
+
+### 🟡 Lỗi 3 — Test đang chạy trên checkout khác
+
+`tests/routing/conftest.py` đẩy thư mục cha vào `sys.path`. Vì thư mục checkout tên là `cowork_local_gitea` (không phải `cowork_local`), lệnh `import cowork_local` **ăn nhầm sang `Desktop\cowork_local`** — một bản checkout khác. Suite báo xanh trên mã nguồn **không phải nhánh đang review**.
+
+*Sửa*: `tests/conftest.py` nạp `__init__.py` theo đường dẫn tuyệt đối và đăng ký vào `sys.modules` trước mọi test.
+
+---
+
+## 6. Cải thiện phụ (không nằm trong yêu cầu task)
+
+| Cải thiện | Ảnh hưởng |
+| :--- | :--- |
+| `ProviderRegistry.build()` đóng dấu `descriptor.id` lên instance | Sửa việc usage của `ollama` / `github_copilot` / `codex` bị ghi nhận nhầm thành `openai_compat` trên Dashboard. **Chưa nối vào production** — xem mục 7. |
+| `ProviderRegistry.build()` copy config trước khi ghi | Trước đây một model do routing chọn có thể ghi đè lên default đã lưu của người dùng |
+| `UsageTrackerSink` ghi log ở mức debug khi thất bại | Trước là `except: pass` — mất sạch lý do khi Dashboard hỏng |
+| `estimate_tokens` được chốt bằng test so với `core.usage_tracker` | Bảo đảm việc tách telemetry **không làm lệch một con số nào** |
+
+---
+
+## 7. Còn nợ & cần quyết định
+
+| # | Nội dung | Người quyết |
+| :--- | :--- | :--- |
+| 1 | **`ProviderRegistry` chưa nối vào `state.build_provider_for`** (vẫn dùng `providers/factory.py`). Nối vào sẽ sửa lỗi quy kết usage ở mục 6, **nhưng đổi cách gom dữ liệu lịch sử trên Dashboard**. | Team Duy + PO |
+| 2 | **Mode `fallback` chưa có trên toggle UI** — config và service đã hỗ trợ đầy đủ; widget `RoutingToggle` thuộc R08. | Team Duy (R08) |
+| 3 | **Đã sửa 2 dòng trong `config.py`** (`routing_mode_for`, `set_routing_mode_for`) để dùng chung bộ từ vựng mode. File này Team Nam đang refactor ở R02-T02. | ⚠️ **Cần báo Team Nam** |
+| 4 | **Circular import** `core/model_pricing.py` ↔ `core/usage_tracker.py` chưa xử lý (task ngày 28/08). | Team Duy |
+| 5 | **2 test đỏ có sẵn từ trước**: `config.py:108` hardcode `sandbox_pw = "quandh14"` ➔ `tests/test_config_security.py`. Thuộc **EPIC R02 / Team Nam**. | 🟣 Team Nam |
+| 6 | `tests/integration/test_routing_surfaces.py` mất 41s do dựng `Co4ETab`/`FolderTab`. Nên gắn marker `slow` khi làm R10. | Team Duy (R10) |
+
+---
+
+## 8. Phạm vi chưa kiểm thử
+
+Nêu rõ để tránh hiểu nhầm mức độ bảo đảm:
+
+* **Chưa mở ứng dụng bằng tay** — mới chạy widget headless (`QT_QPA_PLATFORM=offscreen`), chưa có ai kiểm tra bằng mắt.
+* **Chưa gọi provider thật** — toàn bộ dùng `FakeProvider`, không có lưu lượng mạng.
+* **Chưa chạy 34 script `tools/check_*.py`** — các script này tự `sys.path.insert` thư mục cha nên sẽ import nhầm checkout khác (đúng lỗi 3 ở mục 5). Cần sửa chúng ở R10.
+
+---
+
+## 9. Việc kế tiếp của Team Duy
+
+| EPIC | Nội dung | Điều kiện |
+| :--- | :--- | :--- |
+| **R08** (T01 ➔ T06) | Tách `ui/chat_panel.py` (1.795 dòng) thành 6 widget < 400 dòng | Sẵn sàng bắt đầu — `AgentEvent` (R04-T02) chính là kênh dữ liệu 6 widget con sẽ dùng thay vì đọc trực tiếp state của `ChatPanel` |
+| **R10** (T01 ➔ T05) | Testing Pyramid, `run_quality_gate.py`, Contributor Recipes, E2E Smoke | Chờ cả 3 team hoàn tất |
+
+---
+
+## 10. Lịch sử commit
+
+| Commit | Nội dung |
+| :--- | :--- |
+| `bbc09f6` | feat(R01): architecture foundation, offline fakes and characterization net |
+| `96bec97` | feat(R03): unify provider catalogue, routing decisions and usage telemetry |
+| `a53163e` | feat(R04): immutable turn snapshot, typed agent events, conversation service |
+| `15e1d3e` | test(R03/R04): cover the three code paths that were changed but never executed |
+| `67b8d2e` | docs(refactor): correct the Team Duy scope block in the checklist |

docs/refactor/BaoCao_TeamHoa_R05_R06.md

@@ -0,0 +1,198 @@
+# BÁO CÁO KẾT QUẢ — TEAM HOA: EPIC R05, R06
+
+* **Dự án**: Cowork Local (Cowork-Local BamBOO)
+* **Team**: 🟢 Team Hoa — Workspace, Filesystem, Scheduling & Tool Registry
+* **Nhánh**: `feature/teamhoa/r05-r06` (tạo từ `origin/feature/deltateam/refactor-plan`, chưa push lên remote — xem mục 7)
+* **Thời gian thực hiện**: 21/08/2026, 21:40 ➔ 22:57
+* **Ngày báo cáo**: 22/08/2026
+* **Tài liệu gốc**: `Feature_Architecture_Proposal.md`, `Refactoring_Checklist.md`, `plan.md`
+
+---
+
+## 1. Tóm tắt điều hành
+
+Hoàn tất **10/10 task** của 2 EPIC được giao: **R05** (Tool, MCP & Connector Policy) và **R06** (Workspace, Filesystem & History Isolation). Đã commit 2 commit trên branch cục bộ; **chưa push lên Gitea** — remote từ chối với lỗi quyền ghi (xem mục 7 #1).
+
+| Chỉ số | Kết quả |
+| :--- | :--- |
+| Task hoàn thành | **10/10** (R05: 5, R06: 5) |
+| Commit | 2 (`ae4fe72`, `cf542b7`) |
+| File thay đổi | 41 (27 file mới, 14 file sửa — 1 file (`docs/refactor/Refactoring_Checklist.md`) sửa ở cả 2 commit) |
+| Dòng code | +3.054 / −459 |
+| Test | **283 pass** / 12,5s (283/287 — 4 fail có sẵn từ trước, không do R05/R06) |
+| Test suite nhanh (unit + contract + characterization + routing) | **256 pass / 4,5s** |
+| CASAN Check 3 (`scripts/check_imports.py`) | **PASS** — 0 Qt import trong `domain/`, `application/` |
+| File production > 400 dòng (file mới) | **0** — lớn nhất `domain/tools/tool_registry.py` 125 dòng |
+
+**2 lỗi thật được phát hiện và sửa trong quá trình làm** (chi tiết mục 5): một lỗ hổng bảo mật (MCP/connector tool không qua permission gate) và một race condition (turn chạy ngầm lưu nhầm lịch sử vào project khác).
+
+---
+
+## 2. Kết quả theo từng EPIC
+
+### 🔹 EPIC R05 — Tool, MCP & Connector Policy (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R05-T01 | `domain/tools/tool_descriptor.py`, `tool_registry.py` | `ToolCapability` (Flag: READ/WRITE/EXECUTE/NETWORK, kết hợp được) + `ToolDescriptor` + `ToolRegistry` |
+| R05-T02 | `infrastructure/filesystem/{file_tools,command_tools,fetch_tools,tool_context}.py` | Tách if/elif dispatcher của `core/tools.py`; `core/tools.py` còn 291 dòng (từ 566), là shim strangler-fig |
+| R05-T03 | `application/conversations/tool_policy_gateway.py` | `ToolPolicyGateway.allow(name, gate, payload)` — thay 2 chỗ check hardcode riêng biệt (`chat_agent.py`, `code_agent.py`) bằng 1 lookup capability |
+| R05-T04 | Sửa `core/chat_agent.py`, `core/mcp_client.py` | **Thay đổi hành vi có chủ đích** — xem mục 5, Lỗi 1 |
+| R05-T05 | `infrastructure/mcp/mcp_source_manager.py` | Tách lifecycle connection MCP khỏi `state.py::AppContext` |
+
+**Vấn đề gốc đã giải quyết** — cùng một việc "tool này có cần xác nhận trước khi chạy không" tồn tại **3 cách trả lời khác nhau**:
+
+```
+core/chat_agent.py::run_cowork    name in ("run_command", "install_package")
+core/code_agent.py::run_code      name in (WRITE_TOOLS | MS365_WRITE_TOOLS)
+core/mcp_client.py / ext_connectors.py    (không hỏi gì cả)
+```
+
+Cách thứ 3 là một lỗ hổng thật, không phải khác biệt thiết kế — xem mục 5.
+
+### 🔹 EPIC R06 — Workspace, Filesystem & History Isolation (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R06-T01 | `domain/workspaces/workspace_session.py` | `WorkspaceSession` — snapshot bất biến (project_id/workspace_root/sandbox_dir/allowed_paths) + `is_allowed(path)`, cùng khuôn với `ConversationExecutionRequest` (R04-T01) |
+| R06-T02 | `infrastructure/persistence/json/{atomic_write,workspace_repository_impl,conversation_repository_impl}.py` | **Sửa bug thật** — xem mục 5, Lỗi 2 |
+| R06-T03 | `infrastructure/filesystem/execution_workspace.py` | Đặt tên cho quy ước `.scratch` đã có, không đổi vị trí file |
+| R06-T04 | Sửa `ui/chat_panel.py` | **Sửa race condition thật** — xem mục 5, Lỗi 3 |
+| R06-T05 | `application/workspaces/file_workspace_service.py` | File Explorer/AI Editor gọi `core/tools.py::execute_tool` giống agent, không viết lại logic |
+
+---
+
+## 3. Kiến trúc sau refactor
+
+```text
+presentation/  (chưa đổi ở đợt này — ui/chat_panel.py chỉ thêm 1 field "home_history_dir")
+      │
+      ▼
+application/   conversations/tool_policy_gateway.py        ← ALLOW/CONFIRM cho mọi tool call
+               workspaces/file_workspace_service.py         ← file ops cho File Explorer/AI Editor
+      │        (100% pure Python — check_imports.py chặn import Qt)
+      ▼
+domain/        tools/{tool_descriptor,tool_registry}.py     ← capability + catalogue
+               workspaces/workspace_session.py              ← snapshot workspace bất biến
+      ▲
+infrastructure/ filesystem/{file_tools,command_tools,fetch_tools,tool_context,execution_workspace}.py
+                mcp/mcp_source_manager.py                   ← lifecycle connection MCP
+                persistence/json/{atomic_write,*_repository_impl}.py
+```
+
+**Nguyên tắc di trú (ADR-001 mục 4, tiếp nối cách Team Duy làm ở R04)**: **không viết lại engine**. `core/tools.py::execute_tool`, `core/chat_agent.py::run_cowork`, `core/code_agent.py::run_code` vẫn là engine bên dưới — tầng mới chỉ sở hữu phần phân loại rủi ro (R05) và phần định danh workspace (R06) mà trước đây nằm rải rác/hardcode. `pytest` xanh liên tục giữa các bước.
+
+---
+
+## 4. Bằng chứng kiểm thử
+
+### Phân bố test (bao gồm test mới của Team Hoa)
+
+| Suite | Số test | Ghi chú |
+| :--- | ---: | :--- |
+| `tests/unit/` | 137 | +41 test mới (R05: 26, R06: 15 — không tính `test_history_dir_race.py`, ở `integration/`) |
+| `tests/contracts/` | 29 | có sẵn từ R03, không đổi |
+| `tests/characterization/` | 13 | có sẵn từ R01, vẫn xanh — xác nhận `run_cowork` không hồi quy sau khi sửa gate |
+| `tests/routing/` | 79 | có sẵn từ trước, không đụng |
+| **Cộng 4 suite nhanh** | **256** (4 fail routing-env, không do R05/R06) | 4,5s |
+| `tests/integration/` | 27 | +2 test mới: `test_history_dir_race.py` — Qt offscreen thật, không phải test double |
+| **Tổng** | **287** (283 pass) | 12,5s |
+
+### Đối chiếu Definition of Done (theo `DeltaTeam_prompt.md` / mẫu Team Duy)
+
+| # | Tiêu chí | Kết quả |
+| :--- | :--- | :--- |
+| 1 | Mọi file mới < 400 dòng | ✅ Lớn nhất: `domain/tools/tool_registry.py` 125 dòng |
+| 2 | 0 import Qt trong `domain/`, `application/` | ✅ `check_imports.py` PASS |
+| 3 | Comment tiếng Anh giải thích lý do ở mọi khối sửa/mới | ✅ |
+| 4 | Có unit/contract/integration test, verify bằng chạy thật | ✅ 41 test mới + 2 test Qt offscreen thật cho race condition |
+| 5 | Không hồi quy | ✅ 283/287 pass — 4 fail là lỗi có sẵn từ trước R05/R06 (2 EPIC R02, 2 do môi trường máy có Ollama thật) |
+| 6 | Ghi Start/End vào Checklist | ✅ 10 task đã tick kèm mốc thời gian |
+| 7 | Cổng CASAN (`run_quality_gate.py`, R10-T02) | ⚠️ Chưa viết (thuộc R10, chưa tới lượt) — Check 3 đã PASS |
+
+---
+
+## 5. Hai lỗi thật phát hiện và sửa trong quá trình làm
+
+### 🔴 Lỗi 1 (R05-T04) — Tool MCP/Connector chạy hoàn toàn không qua permission gate
+
+`core/chat_agent.py::run_cowork` có 2 nhánh dispatch tool call: nhánh built-in (`read_file`, `run_command`, ...) đi qua gate xác nhận khi Settings bật "confirm before running commands"; nhánh `extra_tools` (mọi tool từ MCP server hoặc Connector — `core/mcp_client.py`, `core/ext_connectors.py`) gọi thẳng:
+
+```python
+if name in extra_names and extra_executor is not None:
+    ...
+    result = extra_executor(name, args)   # KHÔNG có bước xác nhận nào
+```
+
+Nghĩa là một MCP server (kể cả server tự cấu hình, hoặc MS365 write-tool như `send_mail`) chạy **auto-run tuyệt đối**, bất kể người dùng đã bật "confirm before running commands" trong Settings hay chưa. Đây không phải khác biệt thiết kế có chủ đích — không có ghi chú, không có toggle riêng cho việc này.
+
+*Sửa*: mọi `extra_tools` được gắn `ToolCapability` mặc định bảo toàn (`WRITE|EXECUTE|NETWORK` — vì MCP không có chuẩn khai báo rủi ro), đăng ký vào registry của turn, và đi qua CÙNG `ToolPolicyGateway` với built-in tools.
+
+**Đây là thay đổi hành vi người dùng sẽ thấy**: khi "confirm before running commands" đang bật, tool MCP/connector từ giờ sẽ hỏi xác nhận — giống `run_command`. Verify bằng test `tests/unit/test_cowork_extra_tool_policy.py` (3 test: rejected trước khi executor chạy, approved thì chạy, `gate=None` vẫn auto-run như cũ).
+
+### 🟠 Lỗi 2 (R06-T04) — Turn chạy ngầm lưu nhầm lịch sử vào project khác
+
+`ui/chat_panel.py::_persist_session` (lưu hội thoại của một turn **chạy ngầm**, không phải conversation đang xem) gọi:
+
+```python
+save_conversation(self.ctx.config.history_dir(), ...)
+```
+
+`history_dir()` đọc `config._project_history_dir` — một field **dùng chung** trên `AppContext.config`, được `ui/workspace_tab.py::_load_current` ghi đè mỗi lần người dùng đổi project trong màn Workspace. Nếu một turn ở project A còn đang chạy (ví dụ Scheduled Task, hoặc user gõ câu hỏi rồi chuyển sang xem project B ngay) và người dùng đổi sang project B **trước khi** turn đó lưu xong, hội thoại của project A bị ghi nhầm vào thư mục lịch sử của project B.
+
+*Sửa*: thêm `"home_history_dir"` vào dict `ctx` mà mỗi turn đã có sẵn (cùng quy ước với `home_id`/`home_messages`/`home_title` — dict này được author code gốc thiết kế đúng cho mục đích này, chỉ thiếu 1 field), chụp giá trị **tại lúc submit** thay vì đọc sống lúc lưu.
+
+*Kèm 1 phát hiện phụ*: `_save_snapshot` (dùng cho conversation ĐANG XEM) đã có logic đúng từ trước để không ghi đè `project_id` của một turn nền bằng project hiện tại — chỉ riêng **thư mục lưu** là bị bỏ sót, không phải toàn bộ cơ chế bị thiếu.
+
+Verify bằng test Qt offscreen thật (không phải double): `tests/integration/test_history_dir_race.py` — dựng `ChatPanel` thật, giả lập đổi project giữa lúc turn chạy, xác nhận file được lưu đúng thư mục project A.
+
+---
+
+## 6. Cải thiện phụ (không nằm trong yêu cầu task)
+
+| Cải thiện | Ảnh hưởng |
+| :--- | :--- |
+| `core/projects.py::save_project`, `core/history.py::save_conversation/rename_conversation/set_pinned` chuyển sang ghi atomic (`infrastructure/persistence/json/atomic_write.py`) | Trước đây `path.write_text(json.dumps(...))` không atomic — crash/kill giữa lúc ghi để lại file JSON hỏng, và `load_project`/`load_conversation` coi file hỏng như "không tồn tại" ➔ **mất project hoặc hội thoại âm thầm, không báo lỗi**. Có test giả lập crash giữa lúc ghi xác nhận file cũ không bị hỏng (`tests/unit/test_atomic_write_and_repositories.py`) |
+| `McpServerConnection.is_alive()` (mới, `core/mcp_client.py`) | Nhỏ, cộng thêm — cho `McpToolSourceManager` biết một connection cached đã chết (subprocess crash) để khởi động lại, thay vì cache giữ một connection chết vô thời hạn |
+
+---
+
+## 7. Còn nợ & cần quyết định
+
+| # | Nội dung | Người quyết |
+| :--- | :--- | :--- |
+| 1 | **Branch chưa lên được Gitea** — `git push` bị từ chối: `User permission denied for writing` (pre-receive hook). Cần cấp quyền push cho tài khoản git đang dùng trên máy này, hoặc push bằng tài khoản khác có quyền. | Admin Gitea |
+| 2 | **Xung đột file với EPIC R02 (Team Nam)**: R02-T01 giao `infrastructure/persistence/json/atomic_json_file.py`. R06-T02 cần atomic write ngay nên tạo `atomic_write.py` (tên khác, cùng thư mục) — không đụng file của Team Nam, nhưng 2 module cùng mục đích sẽ tồn tại song song cho tới khi hợp nhất. | Team Nam (khi bắt đầu R02-T01) |
+| 3 | **`WorkspaceRepository`/`ConversationRepository`/`FileWorkspaceService` chưa có call site thật** — giống tình trạng `ProviderRegistry` của Team Duy ở R03 (mục 7 #1 trong báo cáo Team Duy). Mọi nơi trong production vẫn gọi trực tiếp `core/projects.py`/`core/history.py`/`core/tools.py::execute_tool`. | Team Hoa (nối dây ở EPIC sau) |
+| 4 | **R06-T04 không sửa đúng y nguyên `ui/workspace_tab.py::_load_current` như mô tả gốc trong `plan.md`** — bug thật nằm ở điểm ĐỌC (`ui/chat_panel.py::_persist_session`), không phải điểm GHI (`_load_current` chỉ set field, tự nó không đọc lại). Đã sửa đúng điểm đọc, có test thật xác nhận. Việc đổi `_load_current` sang "đồng bộ bằng session id" như plan gốc gợi ý cần tách sâu hơn `WorkspaceTab`/`ChatPanel`, thuộc phạm vi R08 (UI/Application Separation). | Team Duy (R08) |
+| 5 | **2 test đỏ có sẵn từ trước, không do R05/R06**: `tests/test_config_security.py` × 2 (EPIC R02/Team Nam, đã ghi nhận từ báo cáo Team Duy) và `tests/unit/test_routing_wiring.py` × 2 (môi trường máy này có Ollama/llama3.1 thật + config routing cục bộ khác giả định "fresh install" của test — nghi là do máy chạy test có cấu hình routing/Ollama khác máy Team Duy dùng, cần Team Duy xác nhận lại trên máy sạch). | Team Nam (#1), Team Duy (#2) |
+
+---
+
+## 8. Phạm vi chưa kiểm thử
+
+Nêu rõ để tránh hiểu nhầm mức độ bảo đảm:
+
+* **R05-T04 (gate cho MCP/connector) chưa test với MCP server thật** — toàn bộ test dùng `ToolSpec` giả (`_EXTRA_SPEC` trong `test_cowork_extra_tool_policy.py`), chưa có tình huống thật với `core/mcp_client.py::McpServerConnection` chạy subprocess thật.
+* **`McpToolSourceManager` (R05-T05) chưa test với subprocess MCP thật** — test dùng `_FakeConnection`, không spawn tiến trình. Đã smoke-test `AppContext.build_mcp_tools()` thật (không có server nào cấu hình → chỉ trả về ms365 local tools) nhưng chưa thử ensure/restart trên một server thật.
+* **`ui/folder_tab.py`, `ui/file_edit_dialog.py` chưa được nối vào `FileWorkspaceService` (R06-T05)** — dịch vụ tồn tại và có test unit đầy đủ, nhưng chưa xác nhận bằng cách chạy UI thật (đã mở app kiểm tra sau R05, nhưng không lặp lại cho R06's file explorer flow cụ thể).
+* **Đã mở app thật 1 lần sau khi sửa `ui/chat_panel.py` (R06-T04)** để xác nhận không crash lúc khởi động — chưa thử tay thao tác "đổi project giữa lúc chat đang trả lời" trên UI thật (chỉ verify bằng test offscreen).
+
+---
+
+## 9. Việc kế tiếp của Team Hoa
+
+| EPIC | Nội dung | Điều kiện |
+| :--- | :--- | :--- |
+| **R07** (Scheduling & Workflow Runtime) | Tách `TaskRepository`/`ScheduleCalculator` khỏi `QTimer` (`core/task_scheduler.py`), xây `TaskApplicationService` | Phối hợp 🟣 Team Nam (Co4E Workflows) |
+| **R08** (T01 ➔ ...) | Phần Team Hoa trong tách UI (`ui/workspace_tab.py`, `ui/folder_tab.py`, `ui/schedule_task_tab.py`, `ui/dashboard_tab.py`, Graph) | Chờ R07 |
+| Nối `WorkspaceRepository`/`ConversationRepository`/`FileWorkspaceService` vào call site thật | Xem mục 7 #3 | Có thể làm sớm hơn R07/R08 nếu được yêu cầu |
+
+---
+
+## 10. Lịch sử commit
+
+| Commit | Nội dung |
+| :--- | :--- |
+| `ae4fe72` | feat(R05): tool capability registry, unified policy gateway, MCP lifecycle manager |
+| `cf542b7` | feat(R06): workspace session snapshot, atomic persistence, history-dir race fix |

docs/refactor/Refactoring_Checklist.md

@@ -158,16 +158,16 @@
 * **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Chủ trì) + Phối hợp Team Duy
 * **Mục tiêu**: Bóc tách monolithic `core/tools.py`, đưa toàn bộ Built-in tools, MCP tools và Connectors qua `ToolPolicyGateway` kiểm tra quyền phân tầng.
 
-- [ ] **R05-T01 (Team Hoa)**: Định nghĩa `ToolDescriptor`, `ToolCapability` (read/write/execute/network) ➔ `domain/tools/tool_descriptor.py` & `domain/tools/tool_registry.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R05-T02 (Team Hoa)**: Tách nhỏ các built-in handlers từ `core/tools.py` ➔ `infrastructure/filesystem/file_tools.py`, `command_tools.py`, `fetch_tools.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R05-T03 (Team Hoa)**: Xây dựng `ToolPolicyGateway` (kiểm tra phân quyền allow/confirm/deny) ➔ `application/conversations/tool_policy_gateway.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R05-T04 (Team Hoa)**: Chuẩn hóa MCP tools từ `core/mcp_client.py` đi qua `ToolPolicyGateway`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R05-T05 (Team Hoa)**: Xây dựng `McpToolSourceManager` quản lý vòng đời tiến trình MCP ➔ `infrastructure/mcp/mcp_source_manager.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [x] **R05-T01 (Team Hoa)**: Định nghĩa `ToolDescriptor`, `ToolCapability` (read/write/execute/network) ➔ `domain/tools/tool_descriptor.py` & `domain/tools/tool_registry.py`  
+  *Start: `2026-08-21 21:40` | End: `2026-08-21 21:47`*
+- [x] **R05-T02 (Team Hoa)**: Tách nhỏ các built-in handlers từ `core/tools.py` ➔ `infrastructure/filesystem/file_tools.py`, `command_tools.py`, `fetch_tools.py`  
+  *Start: `2026-08-21 21:47` | End: `2026-08-21 21:56`*
+- [x] **R05-T03 (Team Hoa)**: Xây dựng `ToolPolicyGateway` (kiểm tra phân quyền allow/confirm/deny) ➔ `application/conversations/tool_policy_gateway.py`  
+  *Start: `2026-08-21 21:56` | End: `2026-08-21 22:04`*
+- [x] **R05-T04 (Team Hoa)**: Chuẩn hóa MCP tools từ `core/mcp_client.py` đi qua `ToolPolicyGateway`  
+  *Start: `2026-08-21 22:04` | End: `2026-08-21 22:12`*
+- [x] **R05-T05 (Team Hoa)**: Xây dựng `McpToolSourceManager` quản lý vòng đời tiến trình MCP ➔ `infrastructure/mcp/mcp_source_manager.py`  
+  *Start: `2026-08-21 22:12` | End: `2026-08-21 22:19`*
 
 ---
 
@@ -175,16 +175,16 @@
 * **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Chủ trì)
 * **Mục tiêu**: Xóa bỏ biến toàn cục `state.py::active_project_id`, đóng gói workspace per-turn thành `WorkspaceSession` bất biến, bảo vệ an toàn đường dẫn sandbox.
 
-- [ ] **R06-T01 (Team Hoa)**: Định nghĩa `WorkspaceSession` chứa snapshot project id, workspace root ➔ `domain/workspaces/workspace_session.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R06-T02 (Team Hoa)**: Xây dựng `WorkspaceRepository` từ `core/projects.py` & `ConversationRepository` từ `core/history.py` ➔ `infrastructure/persistence/json/workspace_repository_impl.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R06-T03 (Team Hoa)**: Xây dựng `ExecutionWorkspace` quản lý output/scratch files ➔ `infrastructure/filesystem/execution_workspace.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R06-T04 (Team Hoa)**: Khắc phục race condition trong `ui/workspace_tab.py::_load_current`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
-- [ ] **R06-T05 (Team Hoa)**: Xây dựng `FileWorkspaceService` xử lý thao tác file cho File Explorer và AI File Editor ➔ `application/workspaces/file_workspace_service.py`  
-  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [x] **R06-T01 (Team Hoa)**: Định nghĩa `WorkspaceSession` chứa snapshot project id, workspace root ➔ `domain/workspaces/workspace_session.py`  
+  *Start: `2026-08-21 22:19` | End: `2026-08-21 22:24`*
+- [x] **R06-T02 (Team Hoa)**: Xây dựng `WorkspaceRepository` từ `core/projects.py` & `ConversationRepository` từ `core/history.py` ➔ `infrastructure/persistence/json/workspace_repository_impl.py`  
+  *Start: `2026-08-21 22:24` | End: `2026-08-21 22:35`*
+- [x] **R06-T03 (Team Hoa)**: Xây dựng `ExecutionWorkspace` quản lý output/scratch files ➔ `infrastructure/filesystem/execution_workspace.py`  
+  *Start: `2026-08-21 22:35` | End: `2026-08-21 22:40`*
+- [x] **R06-T04 (Team Hoa)**: Khắc phục race condition trong `ui/workspace_tab.py::_load_current`  
+  *Start: `2026-08-21 22:40` | End: `2026-08-21 22:50`*
+- [x] **R06-T05 (Team Hoa)**: Xây dựng `FileWorkspaceService` xử lý thao tác file cho File Explorer và AI File Editor ➔ `application/workspaces/file_workspace_service.py`  
+  *Start: `2026-08-21 22:50` | End: `2026-08-21 22:57`*
 
 ---