merge: lấy phần N3 của Lâm (6 widget UI Co4E) về nhánh chung

Không xung đột — Lâm động vào ui/co4e_tab.py và presentation/co4e/,
tôi động vào ui/settings_dialog.py và presentation/settings/. Đúng như
quy tắc phân chia sở hữu đặt ra từ đầu.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1,29 @@
+# Normalise line endings so a Windows checkout and a Linux CI runner see the
+# same bytes. Without this, committing from Windows records CRLF and every file
+# shows as fully rewritten to anyone (or any CI job) on Linux.
+* text=auto eol=lf
+
+# Windows-only scripts must keep CRLF or cmd.exe mis-parses them.
+*.bat   text eol=crlf
+*.cmd   text eol=crlf
+*.ps1   text eol=crlf
+
+# Binary: never touch, never try to diff as text.
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.pdf   binary
+*.pptx  binary
+*.xlsx  binary
+*.docx  binary
+*.7z    binary
+*.zip   binary
+*.ttf   binary
+*.woff  binary
+*.woff2 binary
+
+# The audit page is a single 8 MB file with base64 images inlined — a textual
+# diff of it is noise, and merging it by hand is never the right move.
+docs/ui-audit.html  -diff -merge

.gitea/workflows/ci.yaml

@@ -39,3 +39,32 @@ jobs:
 
       - name: Run tests
         run: python -m pytest tests -q
+
+      # --- CASAN Verification Gate -------------------------------------
+      # Ba check này là điều kiện của cổng ngày 30/08. Chạy trên MỌI PR để
+      # biết vi phạm ngay hôm phát sinh, thay vì dồn tới ngày cổng.
+      #
+      # Check 1 do Team Gamma sở hữu và đã có. Check 2 (Team Hoa) và Check 3
+      # (Team Duy) chưa viết — bước dưới bỏ qua nếu script chưa tồn tại, để
+      # thêm cổng không làm đỏ CI của hai team kia.
+
+      - name: "CASAN Check 1 — không có credential lộ (Team Gamma)"
+        run: |
+          python scripts/audit_security.py --self-test
+          python scripts/audit_security.py
+
+      - name: "CASAN Check 2 — file production ≤ 400 dòng (Team Hoa)"
+        run: |
+          if [ -f scripts/check_loc.py ]; then
+            python scripts/check_loc.py
+          else
+            echo "scripts/check_loc.py chưa có — Team Hoa viết, hạn 30/08. Bỏ qua."
+          fi
+
+      - name: "CASAN Check 3 — domain/ và application/ không import PySide6 (Team Duy)"
+        run: |
+          if [ -f scripts/check_imports.py ]; then
+            python scripts/check_imports.py
+          else
+            echo "scripts/check_imports.py chưa có — Team Duy viết, hạn 30/08. Bỏ qua."
+          fi

.gitignore

@@ -1,39 +1,128 @@
-# Python bytecode and test/tool caches
+# =============================================================================
+# Dependencies
+# =============================================================================
+node_modules/
+.pnpm-store/
 __pycache__/
-*.py[cod]
-*$py.class
-.pytest_cache/
-.ruff_cache/
-.mypy_cache/
-.coverage
-htmlcov/
-
-# Local environments and packaging output
+*.pyc
+*.pyo
+*.pyd
 .venv/
 venv/
 env/
-build/
-dist/
+.env.venv/
+pip-wheel-metadata/
 *.egg-info/
+*.egg
+.eggs/
+bower_components/
 
-# Local configuration, credentials, and runtime data
+# =============================================================================
+# Environment & Secrets
+# =============================================================================
 .env
-.env.*
-!.env.example
-.cowork_local/
-ms365_token_cache.bin
-*.log
-*.sqlite
-*.sqlite3
-*.db
+.env.local
+.env.*.local
+.env.production
+.env.development
+.env.preview
 *.pem
 *.key
-*.p12
-*.pfx
+# Neo vào gốc repo: mẫu không neo nuốt MỌI thư mục tên secrets ở mọi độ
+# sâu — nó đã âm thầm chặn infrastructure/secrets/ (mã nguồn, không phải
+# bí mật) khỏi repo suốt 21-22/08.
+/secrets/
+credentials.json
+.npmrc
+.yarnrc
 
-# Editors and operating systems
-.DS_Store
+# =============================================================================
+# Build & Distribution
+# =============================================================================
+# Neo vao goc — mau khong neo se nuot moi thu muc trung ten o moi do sau,
+# ke ca ma nguon. Da mac dung loi do voi secrets/ (xem khoi Credentials).
+/dist/
+/build/
+/out/
+.next/
+.nuxt/
+.output/
+
+# =============================================================================
+# IDE & Editor
+# =============================================================================
 .idea/
 .vscode/
 *.swp
+*.swo
 *~
+.project
+.classpath
+.settings/
+*.sublime-project
+*.sublime-workspace
+
+# =============================================================================
+# OS Files
+# =============================================================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# =============================================================================
+# Logs & Debug
+# =============================================================================
+*.log
+# Neo vao goc: infrastructure/logs/ la ma nguon, khong phai log chay may.
+/logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# =============================================================================
+# Testing & Coverage
+# =============================================================================
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.tox/
+.nox/
+coverage/
+*.cover
+*.py,cover
+.hypothesis/
+.nyc_output/
+test-results/
+playwright-report/
+
+# =============================================================================
+# AI & Agent Workspace
+# =============================================================================
+vibeflow.json
+.claude/
+.cursor/
+.aider/
+.continue/
+.copilot/
+
+# =============================================================================
+# Temporary & Cache
+# =============================================================================
+*.tmp
+*.temp
+.cache/
+.parcel-cache/
+.turbo/
+*.tsbuildinfo
+
+# Runtime data the app writes next to itself when it is run from the repo.
+# A chat transcript got committed and pushed this way.
+.cowork_history/
+.cowork_local/

.vibeflow-preview/entrypoint.sh

@@ -0,0 +1,99 @@
+#!/bin/sh
+# Boot the Cowork-Local PySide6 desktop app on Qt's built-in VNC server, then
+# expose the live GUI to the browser through noVNC + websockify on :6080.
+#
+# This entrypoint is intended to be run from a `python:3.11-slim-bookworm`
+# container via podman-compose.  All setup (Qt runtime libs, noVNC, PySide6
+# wheels) happens here so we don't need a custom image / Dockerfile.
+# Idempotent: reruns are fast (apt reuses debs, pip uses the named cache vol).
+
+set -e
+
+log() { printf '[entrypoint] %s\n' "$*"; }
+
+# ---------------------------------------------------------------------------
+# 1. System runtime libraries: Qt6 needs EGL/GL/XCB; noVNC needs websockify.
+# ---------------------------------------------------------------------------
+if [ ! -f /var/cache/cowork_setup.stamp ]; then
+    log "installing apt packages (first run only)…"
+    apt-get update -qq
+    apt-get install -y --no-install-recommends \
+        libegl1 libgl1 libglib2.0-0 libdbus-1-3 libfontconfig1 \
+        libxkbcommon0 libxkbcommon-x11-0 libxcb-cursor0 \
+        libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
+        libxcb-render-util0 libxcb-shape0 libxcb-sync1 \
+        libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxcb-util1 \
+        libxcomposite1 libxdamage1 libxrandr2 libxss1 libxtst6 \
+        libxi6 libxrender1 libfreetype6 \
+        fonts-dejavu fonts-noto-cjk \
+        netcat-openbsd ca-certificates >/dev/null
+    rm -rf /var/lib/apt/lists/*
+    touch /var/cache/cowork_setup.stamp
+    log "apt setup done."
+else
+    log "apt setup already done (skipping)."
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Python dependencies (cached in the named `pip-cache` volume).
+#    `websockify` is shipped as a pip wheel and bundles the noVNC web
+#    assets under its package `web/` directory, so we don't need the
+#    (unavailable on slim-bookworm) apt `novnc` / `websockify` packages.
+# ---------------------------------------------------------------------------
+log "ensuring python deps…"
+pip install --no-cache-dir --quiet \
+    "PySide6>=6.6" "pydantic>=2" requests psutil websockify numpy
+log "python deps OK."
+
+# ---------------------------------------------------------------------------
+# 3. Make the workspace importable as `cowork_local` (the package name that
+#    `python -m cowork_local` and the test suite expect).  Compose mounts the
+#    live repo at /workspace; we add a thin symlink at /opt/cowork_local.
+# ---------------------------------------------------------------------------
+ln -sfn /workspace /opt/cowork_local
+export PYTHONPATH=/opt
+
+# ---------------------------------------------------------------------------
+# 4. Launch the app on Qt's built-in VNC platform (no Xvfb needed).
+#    Qt VNC listens on QT_QPA_VNC_HOST:QT_QPA_VNC_PORT (127.0.0.1:5900).
+# ---------------------------------------------------------------------------
+: > /var/log/app.log
+log "launching app on Qt VNC platform…"
+python -m cowork_local >/var/log/app.log 2>&1 &
+APP_PID=$!
+
+# Wait until the VNC socket accepts a connection (or give up after 60s).
+for i in $(seq 1 120); do
+    if nc -z 127.0.0.1 "${QT_QPA_VNC_PORT:-5900}" 2>/dev/null; then
+        log "VNC server up on 127.0.0.1:${QT_QPA_VNC_PORT:-5900} (pid ${APP_PID})."
+        break
+    fi
+    if ! kill -0 "${APP_PID}" 2>/dev/null; then
+        log "app process died before VNC was up; log tail:"
+        tail -n 60 /var/log/app.log >&2 || true
+        exit 1
+    fi
+    sleep 0.5
+done
+
+if ! nc -z 127.0.0.1 "${QT_QPA_VNC_PORT:-5900}" 2>/dev/null; then
+    log "VNC never came up; log tail:"
+    tail -n 60 /var/log/app.log >&2 || true
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Bridge browser -> VNC.  websockify serves the noVNC web client on :6080
+#    and proxies WebSocket connections to the raw VNC server.  The noVNC web
+#    assets are bundled inside the websockify pip wheel.
+# ---------------------------------------------------------------------------
+NOVNC_WEB="$(python - <<'PY'
+import os, websockify
+print(os.path.join(os.path.dirname(websockify.__file__), "web"))
+PY
+)"
+[ -f "${NOVNC_WEB}/vnc.html" ] || { log "noVNC web assets not found at ${NOVNC_WEB}, aborting."; exit 1; }
+
+log "noVNC web assets: ${NOVNC_WEB}"
+log "starting noVNC bridge on 0.0.0.0:6080 -> 127.0.0.1:${QT_QPA_VNC_PORT:-5900}"
+exec websockify --web="${NOVNC_WEB}" 0.0.0.0:6080 "127.0.0.1:${QT_QPA_VNC_PORT:-5900}"

__main__.py

@@ -1,13 +1,29 @@
-"""Entry point: ``python -m cowork_local``."""
+"""Entry point: ``python -m cowork_local``.
+
+Also works when run directly as ``python __main__.py`` — see main().
+"""
 from __future__ import annotations
 
+import os
 import sys
 
 
 def main() -> int:
     # Imported lazily so that ``-h`` style tooling and tests can import the
     # package without spinning up a full Qt application.
-    from .app import run
+    #
+    # `from .app import run` requires this file to be loaded as part of the
+    # `cowork_local` package (i.e. via `python -m cowork_local`). When run as
+    # a plain script (`python __main__.py`), `__package__` is empty so the
+    # relative import fails — in that case put the package root (the parent
+    # of this file's directory) on sys.path and use an absolute import.
+    if __package__:
+        from .app import run
+    else:
+        parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        if parent not in sys.path:
+            sys.path.insert(0, parent)
+        from cowork_local.app import run
 
     return run(sys.argv)
 

adapters/__init__.py

@@ -0,0 +1,12 @@
+"""adapters/ — Adapter riêng cho Qt (clock, thread, timer).
+
+Kế hoạch gốc đặt tên thư mục này là ``platform/``. Không dùng được: chạy
+bất kỳ script nào từ thư mục gốc repo (``python tools/...``,
+``python scripts/...``) thì ``platform/`` **che khuất module ``platform``
+của thư viện chuẩn**, và ``import keyring`` chết ngay với
+``AttributeError: module 'platform' has no attribute 'system'``.
+Repo có 26 script chạy đúng kiểu đó.
+
+Đổi tên là cách duy nhất chắc chắn — không thể bắt mọi người nhớ "đừng bao
+giờ chạy python từ thư mục gốc".
+"""

app.py

@@ -7,18 +7,21 @@ from pathlib import Path
 from typing import List
 
 from PySide6.QtCore import Qt, QTimer
-from PySide6.QtGui import QGuiApplication, QIcon
+from PySide6.QtGui import QColor, QGuiApplication, QIcon
 from PySide6.QtWidgets import (
+    QStyledItemDelegate,
     QApplication, QComboBox, QHBoxLayout, QLabel, QMainWindow, QMenu,
-    QPushButton, QSizePolicy, QSplitter, QStackedWidget, QSystemTrayIcon,
-    QToolButton, QTreeWidget, QTreeWidgetItem, QVBoxLayout, QWidget,
+    QPushButton, QScrollArea, QSizePolicy, QSplitter, QStackedWidget,
+    QSystemTrayIcon, QToolButton, QTreeWidget, QTreeWidgetItem, QVBoxLayout,
+    QWidget,
 )
 
 from . import APP_NAME, DISPLAY_NAME, __version__
 from .config import PROVIDER_LABELS, AppConfig
 from .i18n import LANGUAGE_SHORT, LANGUAGES, get_language, on_language_changed, set_language, tr
 from .state import AppContext
-from .theme import ACCENT, stylesheet
+from .ui.widgets import tidy_popup
+from .theme import current_palette, set_active_theme, stylesheet
 from .core.task_scheduler import TaskScheduler
 from .ui.cowork_tab import CoworkTab
 from .ui.dashboard_tab import DashboardTab
@@ -35,6 +38,23 @@ ASSETS = Path(__file__).resolve().parent / "assets"
 # shows icon-only (still fully clickable, just narrower).
 _NAV_EXPANDED_WIDTH = 150
 _NAV_COLLAPSED_WIDTH = 54
+# The splitter between rail and content draws a drag handle. It only means
+# something if the rail can actually take a width from it, so the expanded rail
+# is a range rather than one number; long project and thread names in RECENTS
+# are the reason someone would widen it.
+#
+# The ceiling is a SHARE of the window, not a pixel count: 360px is a quarter
+# of a 1440 screen and more than a quarter of a 1280 one, where it left the
+# seven Kanban lanes 920px of the 1067 they need. A share behaves the same on
+# every monitor.
+# Where a rail row starts, and how much air sits between its icon and its
+# label. The tree rows get these from the style; anything laid out by hand
+# beside them has to use the same two numbers or it will not line up.
+_NAV_ROW_INSET = 4
+_NAV_ROW_GAP = 6
+_NAV_MIN_WIDTH = 132
+_NAV_MAX_SHARE = 0.22
+_NAV_MAX_CEILING = 360
 
 
 def app_icon() -> QIcon:
@@ -64,10 +84,12 @@ class _Toast(QLabel):
         self._timer.timeout.connect(self.hide)
 
     def show_message(self, text: str, ok: bool = True, ms: int = 4500) -> None:
-        bg = "#1f9d63" if ok else "#e5484d"
+        p = current_palette()
+        bg = p.success_soft if ok else p.danger_soft
+        fg = p.success if ok else p.danger
         self.setStyleSheet(
-            f"#toast {{ background:{bg}; color:white; border-radius:12px;"
-            f" padding:10px 16px; font-weight:600; }}")
+            f"#toast {{ background:{bg}; color:{fg}; border:1px solid {fg};"
+            f" border-radius:{p.radius}px; padding:10px 16px; font-weight:600; }}")
         self.setText(text)
         self.adjustSize()
         self.move(14, 14)          # top-left of the window
@@ -76,6 +98,23 @@ class _Toast(QLabel):
         self._timer.start(ms)
 
 
+class _NavItemDelegate(QStyledItemDelegate):
+    """Keep a rail row's icon on the left edge, whatever the column is doing.
+
+    QStyledItemDelegate hands the style decorationAlignment = AlignHCenter, so
+    a row with no label — every row once the rail collapses to 54px — has its
+    icon centred inside whatever box the column happens to give it. That box
+    tracks the column width, which is not stable: stretched to the viewport the
+    icons land in the middle of the rail, while a column left wider than the
+    view leaves them at the left. Same code, two different pictures, which is
+    why a test render disagreed with the running app.
+    """
+
+    def initStyleOption(self, option, index):
+        super().initStyleOption(option, index)
+        option.decorationAlignment = Qt.AlignLeft | Qt.AlignVCenter
+
+
 class MainWindow(QMainWindow):
     # Nav rows (Dashboard/Schedule/Monitoring are lazy; Workspace is the eager home page).
     _ROW_DASHBOARD, _ROW_SCHEDULE, _ROW_WORKSPACE, _ROW_MONITORING = 0, 1, 2, 3
@@ -155,8 +194,6 @@ class MainWindow(QMainWindow):
             ("app.tab.workspace", "workspaces", None, self.workspace),
             ("app.tab.monitoring", "monitoring", self._build_monitoring, None),
         ]
-        # Container pages whose sub-tabs become expandable nav children.
-        self._nav_parents = {self._ROW_WORKSPACE, self._ROW_MONITORING}
         self._page_widgets = []   # page index → widget (placeholder until lazily built)
         self._built = []
         for _key, _icon_name, _builder, widget in self._nav_defs:
@@ -165,48 +202,37 @@ class MainWindow(QMainWindow):
             self._page_widgets.append(page)
             self._built.append(widget is not None)
 
-        # Left nav rail as a parent→child accordion (Claude-style): the container
-        # pages (Workspaces, Monitoring) expand to list their sub-views as
-        # children, and their in-content tab strips are hidden — so the content
-        # area is as large as possible.
-        from .ui.icons import icon as _icon
-        self.nav = QTreeWidget()
-        self.nav.setObjectName("navrail")
-        self.nav.setHeaderHidden(True)
-        self.nav.setIndentation(14)
-        self.nav.setRootIsDecorated(True)
-        self.nav.setExpandsOnDoubleClick(False)
-        self._nav_items = []      # page index → top-level QTreeWidgetItem
-        for page, (key, icon_name, _b, _w) in enumerate(self._nav_defs):
-            it = QTreeWidgetItem([tr(key)])
-            it.setIcon(0, _icon(icon_name))
-            it.setData(0, Qt.UserRole, {"page": page, "sub": None,
-                                        "parent": page in self._nav_parents, "key": key})
-            # A container (Monitoring/Workspace) always shows the dropdown arrow —
-            # even before its page/children are lazily built — so it's obvious it
-            # holds multiple sub-views. It stays collapsed until first expanded.
-            if page in self._nav_parents:
-                it.setChildIndicatorPolicy(QTreeWidgetItem.ShowIndicator)
-            self.nav.addTopLevelItem(it)
-            self._nav_items.append(it)
+        # Left nav rail — ONE FLAT LIST, no accordion. Every screen the user
+        # works in is one click away: the Workspace sub-views are listed
+        # directly instead of hiding behind an expandable parent. The two
+        # occasional admin destinations sit in a second, bottom-pinned list.
+        #
+        # Monitoring is the exception that keeps its sub-views OUT of the rail:
+        # it has eight, which would double the rail's length for screens opened
+        # once a week. Its own tab strip is left visible instead (it was hidden
+        # while the rail carried its children), so all eight stay reachable.
+        self.nav = self._new_nav_tree("navrail")
+        self.nav_bottom = self._new_nav_tree("navrailBottom")
+        self._nav_building = False       # guards the rebuild → select → rebuild loop
         self.workspace.hide_tab_bar()
-        self._reload_nav_children(self._ROW_WORKSPACE)     # Workspace is eager
-        self.workspace.subtabs_changed.connect(
-            lambda: self._reload_nav_children(self._ROW_WORKSPACE))
-        self.nav.currentItemChanged.connect(lambda cur, _prev: self._navigate(cur))
-        self.nav.itemClicked.connect(self._on_nav_click)
-        self.nav.itemExpanded.connect(self._on_nav_expanded)   # build children lazily
+        self._rebuild_nav()
+        self.workspace.subtabs_changed.connect(self._rebuild_nav)
+        for tree in (self.nav, self.nav_bottom):
+            tree.currentItemChanged.connect(
+                lambda cur, _prev, t=tree: self._on_nav_current(t, cur))
         rlay.addWidget(self.pages, 1)
 
         # Nav rail wrapper: a small toggle button ABOVE the page list so the
         # whole rail can collapse to icon-only (still fully clickable). Same
         # collapse/expand chevron iconography as every other collapsible panel.
         from .ui.icons import collapse_left_icon, collapse_right_icon
+        from .ui.icons import icon as _icon
         self._collapse_left_icon = collapse_left_icon
         self._collapse_right_icon = collapse_right_icon
         self._nav_wrap = QWidget()
         self._nav_wrap.setObjectName("navWrap")
-        self._nav_wrap.setFixedWidth(_NAV_EXPANDED_WIDTH)
+        self._nav_width = _NAV_EXPANDED_WIDTH   # remembered across collapses
+        self._set_nav_width_range(_NAV_MIN_WIDTH, self._nav_max_width())
         nvl = QVBoxLayout(self._nav_wrap)
         nvl.setContentsMargins(0, 0, 0, 0)
         nvl.setSpacing(0)
@@ -228,7 +254,107 @@ class MainWindow(QMainWindow):
         toggle_row.addWidget(self._nav_toggle_btn, 0, Qt.AlignLeft)
         toggle_row.addStretch(1)
         nvl.addLayout(toggle_row)
-        nvl.addWidget(self.nav, 1)
+        # Primary action at the top of the rail, with the project it will land
+        # in named right above it. Before, starting a chat in another project
+        # meant leaving Cowork → Project tab → click a row → come back.
+        self.nav_project = QComboBox()
+        self.nav_project.setObjectName("navProjectPick")
+        self.nav_project.setToolTip(tr("app.nav.project_pick"))
+        self.nav_project.currentIndexChanged.connect(self._on_rail_project_pick)
+        tidy_popup(self.nav_project)
+        self.nav_new_chat = QPushButton(tr("cowork.new_chat"))
+        self.nav_new_chat.setObjectName("navNewChatBtn")
+        self.nav_new_chat.setIcon(_icon("plus"))
+        self.nav_new_chat.setCursor(Qt.PointingHandCursor)
+        self.nav_new_chat.clicked.connect(self._on_rail_new_chat)
+        # At 54px the picker cannot show a name, but dropping it altogether left
+        # the collapsed rail with no way to change project at all. This stands in
+        # for it: same list, same handler, just the folder icon and a tooltip.
+        self.nav_project_btn = QToolButton()
+        self.nav_project_btn.setObjectName("navProjectPickMini")
+        self.nav_project_btn.setIcon(_icon("folder"))
+        self.nav_project_btn.setCursor(Qt.PointingHandCursor)
+        self.nav_project_btn.setPopupMode(QToolButton.InstantPopup)
+        self.nav_project_btn.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Fixed)
+        self.nav_project_btn.setMenu(QMenu(self.nav_project_btn))
+        self.nav_project_btn.menu().aboutToShow.connect(self._fill_rail_project_menu)
+        self.nav_project_btn.setVisible(False)
+        head = QVBoxLayout()
+        head.setContentsMargins(6, 0, 6, 6)
+        head.setSpacing(6)
+        head.addWidget(self.nav_project)
+        head.addWidget(self.nav_project_btn)
+        head.addWidget(self.nav_new_chat)
+        nvl.addLayout(head)
+        self.workspace.project_selected.connect(self._sync_rail_project)
+        self.workspace.projects_changed.connect(self._sync_rail_project)
+        self._syncing_rail_project = False
+        self._sync_rail_project()
+        # The destinations and RECENTS scroll together; the bottom group, the
+        # Settings button and the account row stay pinned below them.
+        #
+        # Without this the rail simply ran out of room on a short window (a
+        # 1280×720 laptop leaves ~570px here): nav and the bottom group have
+        # fixed heights, so the squeeze fell entirely on RECENTS, and once that
+        # hit zero the layout drew the "GẦN ĐÂY" heading straight over the last
+        # nav row.
+        self._nav_scroll = QScrollArea()
+        self._nav_scroll.setObjectName("navScroll")
+        self._nav_scroll.setWidgetResizable(True)
+        self._nav_scroll.setFrameShape(QScrollArea.NoFrame)
+        self._nav_scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
+        scroll_body = QWidget()
+        sv = QVBoxLayout(scroll_body)
+        sv.setContentsMargins(0, 0, 0, 0)
+        sv.setSpacing(0)
+        sv.addWidget(self.nav, 0)
+        # RECENTS — the threads of the project named in the picker above, right
+        # where Claude puts them. A shortcut only: the full History panel (search,
+        # filters, pin, bulk delete, context menu) stays exactly where it is, and
+        # "all projects…" at the end of this list opens it.
+        self.nav_recents_hdr = QLabel(tr("app.nav.recents"))
+        self.nav_recents_hdr.setObjectName("navSectionHdr")
+        sv.addWidget(self.nav_recents_hdr)
+        self.nav_recents = self._new_nav_tree("navRecents")
+        self.nav_recents.itemClicked.connect(self._on_rail_recent)
+        sv.addWidget(self.nav_recents, 1)
+        # Collapsing hides RECENTS, and with it the only item carrying a stretch
+        # factor. A box layout with nothing left to expand centres what remains,
+        # so the destinations dropped ~300px down the rail — "thu gọn menu lại
+        # ra giữa". This spacer takes the slack instead, and takes none of it
+        # while RECENTS is visible (stretch 0 against its 1).
+        sv.addStretch(0)
+        self._nav_scroll.setWidget(scroll_body)
+        nvl.addWidget(self._nav_scroll, 1)
+        # Bottom-pinned group: the places you visit occasionally, kept out of the
+        # way of the ones you live in. A hairline (styled via #navrailBottom in
+        # theme.py) separates the two lists.
+        nvl.addWidget(self.nav_bottom, 0)
+        # Settings reads as one more row under Dashboard / Giám sát, so its icon
+        # and label must start exactly where theirs do. Letting QPushButton place
+        # them does not achieve that: the gap it leaves between icon and text is
+        # the platform style's, and on macOS it is visibly tighter than the tree
+        # rows above — a Windows-tuned nudge only moved the mismatch. So the row
+        # is laid out here, in the same two numbers the tree uses: 4px in, 6px
+        # between.
+        self._nav_settings_btn = QPushButton()
+        self._nav_settings_btn.setObjectName("navSettingsBtn")
+        self._nav_settings_btn.setFlat(True)
+        self._nav_settings_btn.setCursor(Qt.PointingHandCursor)
+        self._nav_settings_btn.clicked.connect(self._open_settings)
+        srow = QHBoxLayout(self._nav_settings_btn)
+        srow.setContentsMargins(_NAV_ROW_INSET, 6, 8, 6)
+        srow.setSpacing(_NAV_ROW_GAP)
+        self._nav_settings_icon = QLabel()
+        self._nav_settings_icon.setPixmap(_icon("settings").pixmap(16, 16))
+        self._nav_settings_icon.setFixedSize(16, 16)
+        self._nav_settings_text = QLabel(tr("app.settings"))
+        srow.addWidget(self._nav_settings_icon)
+        srow.addWidget(self._nav_settings_text)
+        srow.addStretch(1)
+        nvl.addWidget(self._nav_settings_btn)
+        self._account_row = self._build_account_row()
+        nvl.addWidget(self._account_row)
 
         self.split = QSplitter(Qt.Horizontal)
         self.split.addWidget(self._nav_wrap)
@@ -236,10 +362,12 @@ class MainWindow(QMainWindow):
         self.split.setStretchFactor(0, 0)
         self.split.setStretchFactor(1, 1)
         self.split.setSizes([_NAV_EXPANDED_WIDTH, 1000])
+        self.split.splitterMoved.connect(self._on_split_moved)
         self.setCentralWidget(self.split)
-        # Workspace = landing/home (expand it and select its first sub-view).
-        self._nav_items[self._ROW_WORKSPACE].setExpanded(True)
-        self.nav.setCurrentItem(self._nav_items[self._ROW_WORKSPACE])
+        # Landing stays Workspace ▸ Project, exactly as before. Go through _goto
+        # so the page is actually shown — selecting the row alone only moves the
+        # highlight (its signals are blocked to avoid rebuild loops).
+        self._goto(self._ROW_WORKSPACE, self.workspace.current_subtab())
         self.toast = _Toast(self)   # top-left "task done" popup
         # Floating in-app Help assistant — a robot icon pinned bottom-right on
         # every screen; expands into a small help-only chat (see
@@ -253,8 +381,8 @@ class MainWindow(QMainWindow):
         # widget sits at the right end and is never cleared by showMessage (which
         # writes on the left).
         self._credit = QLabel(tr("app.credit"))
-        self._credit.setObjectName("hint")
-        self._credit.setStyleSheet("color: rgba(140,146,152,0.85); padding: 0 10px;")
+        self._credit.setObjectName("faint")
+        self._credit.setStyleSheet("padding: 0 10px;")
         self.statusBar().addPermanentWidget(self._credit)
         self._restore_sessions()
         self._setup_tray()
@@ -273,6 +401,11 @@ class MainWindow(QMainWindow):
 
     def resizeEvent(self, event):  # noqa: N802 - Qt override
         super().resizeEvent(event)
+        # The rail's ceiling is a share of the window, so it moves with the
+        # window. Computed once at construction it was read off a not-yet-sized
+        # window and stuck at 162px on every monitor.
+        if getattr(self, "_nav_wrap", None) is not None and not self._nav_collapsed:
+            self._set_nav_width_range(_NAV_MIN_WIDTH, self._nav_max_width())
         # Keep the floating Help assistant pinned to the bottom-right corner.
         if getattr(self, "help_agent", None) is not None:
             self.help_agent.reposition()
@@ -280,8 +413,24 @@ class MainWindow(QMainWindow):
     def showEvent(self, event):  # noqa: N802 - Qt override
         super().showEvent(event)
         if getattr(self, "help_agent", None) is not None:
+            self._update_dock_guard()
             self.help_agent.reposition()
             self.help_agent.raise_()
+        # Build GraphRAG's browser view and first graph once the window is up
+        # and idle, so clicking GraphRAG does not sit on an empty view while
+        # both happen. 3s is after the first paint and any startup refresh.
+        if not getattr(self, "_graph_prewarmed", False):
+            self._graph_prewarmed = True
+            QTimer.singleShot(3000, self._prewarm_graph)
+
+    def _prewarm_graph(self) -> None:
+        view = getattr(self, "structure", None)
+        if view is None or not hasattr(view, "prewarm"):
+            return
+        try:
+            view.prewarm()
+        except Exception:  # noqa: BLE001 — a warm-up must never break the app
+            pass
 
     # ---- i18n ----------------------------------------------------------
     def _retranslate(self) -> None:
@@ -368,12 +517,9 @@ class MainWindow(QMainWindow):
         placeholder.deleteLater()
         self._page_widgets[row] = real
         self._built[row] = True
-        # Container pages: hide their in-content tab strip + list their sub-views
-        # as children in the nav rail now that the real widget exists.
-        if hasattr(real, "hide_tab_bar"):
-            real.hide_tab_bar()
-        if row in self._nav_parents:
-            self._reload_nav_children(row)
+        # Monitoring KEEPS its own tab strip: its eight sub-views live in the
+        # page, not in the rail. Workspace is the one that hides its strip,
+        # because the rail lists its sub-views directly.
 
     def _page_index(self, widget) -> int:
         if widget is self.workspace:
@@ -386,28 +532,311 @@ class MainWindow(QMainWindow):
             return self._ROW_MONITORING
         return self.pages.indexOf(widget)
 
-    # ---- nav rail collapse (icon-only) --------------------------------
+    # ---- flat nav rail -------------------------------------------------
+    def _new_nav_tree(self, name: str) -> QTreeWidget:
+        """One flat, single-column list. No indentation and no expand arrows —
+        every row is a destination, nothing is a container."""
+        tree = QTreeWidget()
+        tree.setObjectName(name)
+        tree.setHeaderHidden(True)
+        tree.setIndentation(0)
+        tree.setRootIsDecorated(False)
+        tree.setUniformRowHeights(True)
+        # The column follows the viewport instead of the widest label. Left
+        # to size itself it stayed ~100px wide inside the 54px collapsed
+        # rail, so a horizontal scrollbar appeared and slid the icons out of
+        # the position they hold while the rail is open.
+        from PySide6.QtWidgets import QHeaderView
+        tree.header().setSectionResizeMode(0, QHeaderView.Stretch)
+        tree.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
+        tree.setItemDelegate(_NavItemDelegate(tree))
+        return tree
+
+    def _nav_rows(self):
+        """(tree, page, sub, label, icon, enabled) for every row, rail order.
+
+        Workspace contributes all five of its sub-views — including the two the
+        project gate currently disables — so the rail never changes shape while
+        the user is looking at it.
+        """
+        rows = [(self.nav, self._ROW_WORKSPACE, sub, label, ic, on)
+                for label, sub, ic, on in self.workspace.nav_entries()]
+        rows.append((self.nav, self._ROW_SCHEDULE, None,
+                     tr("app.tab.schedule"), "schedule", True))
+        rows.append((self.nav_bottom, self._ROW_DASHBOARD, None,
+                     tr("app.tab.dashboard"), "dashboard", True))
+        rows.append((self.nav_bottom, self._ROW_MONITORING, None,
+                     tr("app.tab.monitoring"), "monitoring", True))
+        return rows
+
+    def _rebuild_nav(self, force: bool = False) -> None:
+        """Re-fill both lists from _nav_rows(), keeping the current selection.
+
+        Rebuilding changes the current item, which would fire navigation and can
+        loop back here via subtabs_changed — hence the guard and the blocked
+        signals.
+        """
+        if self._nav_building:
+            return
+        spec = self._nav_rows()
+        # Rebuilding deletes the QTreeWidgetItems, including the one a signal is
+        # currently being delivered for. subtabs_changed fires on every visit to
+        # Workspace, so skip the rebuild unless the rows really differ.
+        sig = [(label, page, sub, enabled)
+               for _t, page, sub, label, _ic, enabled in spec]
+        if not force and sig == getattr(self, "_nav_sig", None):
+            return
+        self._nav_sig = sig
+        self._nav_building = True
+        try:
+            from .ui.icons import icon as _icon
+            keep = self._current_nav_key()
+            for tree in (self.nav, self.nav_bottom):
+                blocked = tree.blockSignals(True)
+                tree.clear()
+                tree.blockSignals(blocked)
+            for tree, page, sub, label, icon_name, enabled in spec:
+                it = QTreeWidgetItem([""] if self._nav_collapsed else [label])
+                it.setIcon(0, _icon(icon_name))
+                it.setData(0, Qt.UserRole, {"page": page, "sub": sub})
+                if not enabled:
+                    # Same gate as before, shown instead of hidden: the row stays
+                    # in place, greyed, and says why it cannot be opened.
+                    it.setDisabled(True)
+                    it.setToolTip(0, tr("app.nav.needs_project"))
+                elif self._nav_collapsed:
+                    it.setToolTip(0, label)
+                blocked = tree.blockSignals(True)
+                tree.addTopLevelItem(it)
+                tree.blockSignals(blocked)
+            # Both destination lists are exactly as tall as their rows; the
+            # stretch in between belongs to RECENTS.
+            for tree in (self.nav, self.nav_bottom):
+                n = tree.topLevelItemCount()
+                row_h = tree.sizeHintForRow(0) if n else 0
+                tree.setFixedHeight(n * row_h + 8)
+            if keep:
+                self._select_nav_row(*keep)
+        finally:
+            self._nav_building = False
+
+    def _current_nav_key(self):
+        """(page, sub) of the highlighted row, or None."""
+        for tree in (self.nav, self.nav_bottom):
+            it = tree.currentItem()
+            if it is not None and it.isSelected():
+                data = it.data(0, Qt.UserRole) or {}
+                if "page" in data:
+                    return data["page"], data.get("sub")
+        return None
+
+    def _select_nav_row(self, page: int, sub) -> None:
+        """Highlight the row for (page, sub) without triggering navigation.
+
+        Called both when the user clicks (to keep the two lists mutually
+        exclusive) and from _goto, so programmatic navigation moves the
+        highlight too — it used to stay behind on whatever was clicked last.
+        """
+        for tree in (self.nav, self.nav_bottom):
+            blocked = tree.blockSignals(True)
+            match = None
+            for i in range(tree.topLevelItemCount()):
+                it = tree.topLevelItem(i)
+                data = it.data(0, Qt.UserRole) or {}
+                if data.get("page") == page and (
+                        data.get("sub") == sub or data.get("sub") is None):
+                    match = it
+                    break
+            if match is not None:
+                tree.setCurrentItem(match)
+            else:
+                tree.setCurrentItem(None)
+                tree.clearSelection()
+            tree.blockSignals(blocked)
+
+    def _on_nav_current(self, tree: QTreeWidget, item) -> None:
+        """A row was picked: clear the other list so only one row looks active."""
+        if item is None or self._nav_building:
+            return
+        data = item.data(0, Qt.UserRole) or {}
+        other = self.nav_bottom if tree is self.nav else self.nav
+        blocked = other.blockSignals(True)
+        other.setCurrentItem(None)
+        other.clearSelection()
+        other.blockSignals(blocked)
+        self._goto(data.get("page", 0), data.get("sub"))
+
+    # ---- rail header: project picker + new chat ------------------------
+    def _sync_rail_project(self, *_a) -> None:
+        """Mirror the workspace's project list/selection into the rail picker.
+
+        One-way on purpose: the project list stays the source of truth, this is
+        only a second place to see and change it.
+        """
+        if self._syncing_rail_project:
+            return
+        self._syncing_rail_project = True
+        try:
+            choices = self.workspace.project_choices()
+            current = self.workspace.selected_project_id()
+            self.nav_project.clear()
+            for name, pid in choices:
+                self.nav_project.addItem(f"📁 {name}", pid)
+            if not choices:
+                # No project yet: say so, and say what to do about it, instead of
+                # leaving an empty box and a button that silently does nothing.
+                self.nav_project.addItem(tr("app.nav.no_project"), "")
+            idx = self.nav_project.findData(current)
+            if idx >= 0:
+                self.nav_project.setCurrentIndex(idx)
+            has = bool(choices)
+            tidy_popup(self.nav_project)
+            self.nav_project.setEnabled(has)
+            self.nav_project_btn.setEnabled(has)
+            self.nav_project_btn.setToolTip(
+                self.nav_project.currentText().replace("📁 ", "")
+                if has else tr("app.nav.create_project_first"))
+            self.nav_new_chat.setEnabled(has)
+            self.nav_new_chat.setToolTip(
+                "" if has else tr("app.nav.create_project_first"))
+        finally:
+            self._syncing_rail_project = False
+
+    def _fill_rail_project_menu(self) -> None:
+        """Mirror the picker's items. Choosing one moves the picker, which runs
+        _on_rail_project_pick — the collapsed rail adds no second code path."""
+        menu = self.nav_project_btn.menu()
+        menu.clear()
+        for i in range(self.nav_project.count()):
+            act = menu.addAction(self.nav_project.itemText(i))
+            act.setCheckable(True)
+            act.setChecked(i == self.nav_project.currentIndex())
+            act.triggered.connect(
+                lambda _checked=False, row=i: self.nav_project.setCurrentIndex(row))
+
+    def _on_rail_project_pick(self, _idx: int) -> None:
+        if self._syncing_rail_project:
+            return
+        pid = self.nav_project.currentData()
+        if pid:
+            self.workspace.choose_project(pid)
+
+    # ---- rail RECENTS --------------------------------------------------
+    _RAIL_RECENTS = 5
+
+    def _refresh_rail_recents(self) -> None:
+        """Re-fill the rail's recents from the active project's history."""
+        from .ui.icons import DOT_BLUE, dot_icon
+        from .ui.icons import icon as _icon
+
+        tree = self.nav_recents
+        blocked = tree.blockSignals(True)
+        tree.clear()
+        running = self._running_session_ids()
+        threads = self.workspace.recent_threads(self._RAIL_RECENTS)
+        for t in threads:
+            it = QTreeWidgetItem([t["title"]])
+            it.setToolTip(0, t["title"])
+            if t["session_id"] in running:
+                it.setIcon(0, dot_icon(DOT_BLUE))       # same marker as History
+            elif t["pinned"]:
+                it.setIcon(0, _icon("pin"))
+            it.setData(0, Qt.UserRole, {"path": t["path"], "kind": t["kind"]})
+            tree.addTopLevelItem(it)
+        if not threads:
+            it = QTreeWidgetItem([tr("sidebar.empty")])
+            it.setDisabled(True)
+            tree.addTopLevelItem(it)
+        # The way back to everything the rail cannot show — styled as a link
+        # (italic, accent-colored) so it reads as "go elsewhere", not another row.
+        more = QTreeWidgetItem([tr("app.nav.all_projects")])
+        more.setData(0, Qt.UserRole, {"all": True})
+        more_font = more.font(0)
+        more_font.setItalic(True)
+        more.setFont(0, more_font)
+        more.setForeground(0, QColor(current_palette().accent))
+        tree.addTopLevelItem(more)
+        tree.blockSignals(blocked)
+        self.nav_recents_hdr.setVisible(not self._nav_collapsed)
+        self.nav_recents.setVisible(not self._nav_collapsed)
+
+    def _on_rail_recent(self, item, _col: int = 0) -> None:
+        data = item.data(0, Qt.UserRole) or {}
+        if data.get("all"):
+            self._goto(self._ROW_WORKSPACE, self.workspace._cowork_tab_idx)
+            self.workspace.show_history_pane()
+            return
+        path = data.get("path")
+        if path:
+            self._goto(self._ROW_WORKSPACE, self.workspace._cowork_tab_idx)
+            self.workspace.open_thread(path, data.get("kind", "cowork"))
+
+    def _on_rail_new_chat(self) -> None:
+        """Start a new chat, from any screen.
+
+        Same call the Cowork toolbar button makes — that button stays exactly
+        where it was; this is a second entry point, not a replacement.
+        """
+        self._goto(self._ROW_WORKSPACE, None)
+        self.workspace.start_new_chat()
+        self._select_nav_row(self._ROW_WORKSPACE, self.workspace.current_subtab())
+
     def _apply_nav_labels(self) -> None:
-        """Set each top-level nav item's text for the current language AND
-        collapse state: collapsed shows icon-only (label → tooltip) and folds
-        the accordion so only the top-level icons show."""
-        for page, item in enumerate(self._nav_items):
-            key = self._nav_defs[page][0]
-            label = tr(key)
-            item.setText(0, "" if self._nav_collapsed else label)
-            item.setToolTip(0, label if self._nav_collapsed else "")
-            if self._nav_collapsed:
-                item.setExpanded(False)
-        # Refresh child labels (language-aware, from each container's tabText).
+        """Re-label every row for the current language and collapse state
+        (collapsed = icon only, label moves to the tooltip)."""
+        # force: collapsing leaves the row spec identical, only the text changes.
+        self._rebuild_nav(force=True)
+        self._nav_settings_text.setText(tr("app.settings"))
+        self._nav_settings_text.setVisible(not self._nav_collapsed)
+        self._nav_settings_btn.setToolTip(tr("app.settings"))
+        # Collapsed to 54px there is no room for either control's label; the
+        # picker would be a stub of a name, so it steps aside entirely and the
+        # button keeps just its ＋ icon.
+        self.nav_project.setVisible(not self._nav_collapsed)
+        self.nav_project_btn.setVisible(self._nav_collapsed)
+        self._refresh_rail_recents()
+        # Collapsed to 54px only the theme toggle still fits; the rest of the
+        # account row would be clipped, so it steps aside (Settings, which opens
+        # the same values in a dialog, stays reachable as an icon).
+        self.account_lbl.setVisible(not self._nav_collapsed)
+        self.language_combo.setVisible(not self._nav_collapsed)
+        self.provider_combo.setVisible(not self._nav_collapsed)
+        self.nav_new_chat.setText("" if self._nav_collapsed else tr("cowork.new_chat"))
+        if self._nav_new_chat_enabled():
+            self.nav_new_chat.setToolTip(
+                tr("cowork.new_chat") if self._nav_collapsed else "")
+        self._sync_rail_project()
+
+    def _nav_new_chat_enabled(self) -> bool:
+        return bool(self.workspace.project_choices())
+
+    def _nav_max_width(self) -> int:
+        """The rail's ceiling for THIS window, as a share of it."""
+        return max(_NAV_MIN_WIDTH,
+                   min(_NAV_MAX_CEILING, int(self.width() * _NAV_MAX_SHARE)))
+
+    def _set_nav_width_range(self, lo: int, hi: int) -> None:
+        """setFixedWidth would leave the splitter handle inert — visible, and
+        doing nothing when dragged."""
+        self._nav_wrap.setMinimumWidth(lo)
+        self._nav_wrap.setMaximumWidth(hi)
+
+    def _on_split_moved(self, _pos: int, _index: int) -> None:
         if not self._nav_collapsed:
-            for page in self._nav_parents:
-                if self._built[page]:
-                    self._reload_nav_children(page)
+            self._nav_width = max(_NAV_MIN_WIDTH,
+                                  min(self._nav_max_width(), self._nav_wrap.width()))
 
     def _toggle_nav(self) -> None:
+        if not self._nav_collapsed:
+            self._nav_width = max(_NAV_MIN_WIDTH,
+                                  min(self._nav_max_width(), self._nav_wrap.width()))
         self._nav_collapsed = not self._nav_collapsed
-        width = _NAV_COLLAPSED_WIDTH if self._nav_collapsed else _NAV_EXPANDED_WIDTH
-        self._nav_wrap.setFixedWidth(width)
+        if self._nav_collapsed:
+            width = _NAV_COLLAPSED_WIDTH
+            self._set_nav_width_range(width, width)
+        else:
+            width = self._nav_width
+            self._set_nav_width_range(_NAV_MIN_WIDTH, self._nav_max_width())
         self._apply_nav_labels()
         # Same chevron convention as every other collapsible panel: right-
         # pointing (fill-right) means "click to expand", left means "collapse".
@@ -444,6 +873,7 @@ class MainWindow(QMainWindow):
             current = self.cowork.session_id
             self.sidebar.set_view_state(current, self._running_session_ids())
             self.sidebar.refresh()
+            self._refresh_rail_recents()   # the rail shortcut follows the panel
 
         QTimer.singleShot(0, _do)
 
@@ -531,9 +961,8 @@ class MainWindow(QMainWindow):
     def _build_topbar(self) -> QWidget:
         bar = QWidget()
         bar.setObjectName("topbar")
-        # Transparent: the logo/provider/language text sits directly on the
-        # window background, no separate card box behind it.
-        bar.setStyleSheet("#topbar { background: transparent; border: none; }")
+        # Styled centrally (see theme._TEMPLATE): flat, with a single hairline
+        # separating it from the content below — no card box behind it.
         h = QHBoxLayout(bar)
         h.setContentsMargins(16, 10, 12, 10)
         h.setSpacing(10)
@@ -548,22 +977,32 @@ class MainWindow(QMainWindow):
             self.logo_img.setVisible(False)
         h.addWidget(self.logo_img)
         self.logo_lbl = QLabel(tr("app.logo"))
-        self.logo_lbl.setStyleSheet(f"font-weight:800; font-size:16px; color:{ACCENT};")
+        self.logo_lbl.setObjectName("brand")   # styled centrally — see theme._TEMPLATE
         h.addWidget(self.logo_lbl)
         h.addStretch(1)
+        # Provider / language / theme / Settings used to live here, five controls
+        # wide across the top of every screen. They are per-account settings, not
+        # per-screen ones, so they moved to the account row at the foot of the
+        # rail (_build_account_row) — same widgets, same handlers, new home.
+        return bar
 
-        self.provider_lbl = QLabel(tr("app.provider"))
-        self.provider_lbl.setObjectName("hint")
-        h.addWidget(self.provider_lbl)
-        self.provider_combo = QComboBox()
-        for key, label in PROVIDER_LABELS.items():
-            self.provider_combo.addItem(label, key)
-        idx = self.provider_combo.findData(self.ctx.config.active_provider)
-        if idx >= 0:
-            self.provider_combo.setCurrentIndex(idx)
-        self.provider_combo.currentIndexChanged.connect(self._on_provider_changed)
-        h.addWidget(self.provider_combo)
+    def _build_account_row(self) -> QWidget:
+        """The rail's foot: who you are, and the settings that follow you.
 
+        Nothing new is introduced here — these are the exact widgets the top bar
+        used to hold, moved as-is so every existing signal still lands.
+        """
+        box = QWidget()
+        box.setObjectName("navAccount")
+        v = QVBoxLayout(box)
+        v.setContentsMargins(6, 4, 6, 4)
+        v.setSpacing(4)
+
+        who = QHBoxLayout()
+        who.setSpacing(4)
+        self.account_lbl = QLabel(f"👤 {self._user_name}" if self._user_name else "👤")
+        self.account_lbl.setObjectName("hint")
+        who.addWidget(self.account_lbl, 1)
         self.language_combo = QComboBox()
         for key in LANGUAGES:
             self.language_combo.addItem(LANGUAGE_SHORT.get(key, key.upper()), key)
@@ -572,22 +1011,28 @@ class MainWindow(QMainWindow):
         idx = self.language_combo.findData(get_language())
         if idx >= 0:
             self.language_combo.setCurrentIndex(idx)
+        tidy_popup(self.language_combo)
         self.language_combo.currentIndexChanged.connect(self._on_language_changed)
-        h.addWidget(self.language_combo)
-
+        who.addWidget(self.language_combo)
         self.theme_btn = self._build_theme_button()
-        h.addWidget(self.theme_btn)
+        who.addWidget(self.theme_btn)
+        v.addLayout(who)
 
-        if self._user_name:
-            user_lbl = QLabel(f"👤 {self._user_name}")
-            user_lbl.setObjectName("hint")
-            h.addWidget(user_lbl)
-        self.settings_btn = QPushButton(tr("app.settings"))
-        from .ui.icons import icon as _icon
-        self.settings_btn.setIcon(_icon("settings"))
-        self.settings_btn.clicked.connect(self._open_settings)
-        h.addWidget(self.settings_btn)
-        return bar
+        self.provider_lbl = QLabel(tr("app.provider"))
+        self.provider_lbl.setObjectName("hint")
+        self.provider_lbl.setVisible(False)   # the combo names itself in the rail
+        self.provider_combo = QComboBox()
+        self.provider_combo.setToolTip(tr("app.provider"))
+        for key, label in PROVIDER_LABELS.items():
+            self.provider_combo.addItem(label, key)
+        tidy_popup(self.provider_combo)
+        idx = self.provider_combo.findData(self.ctx.config.active_provider)
+        if idx >= 0:
+            self.provider_combo.setCurrentIndex(idx)
+        self.provider_combo.currentIndexChanged.connect(self._on_provider_changed)
+        v.addWidget(self.provider_lbl)
+        v.addWidget(self.provider_combo)
+        return box
 
     _BRAND_LOGO_NAMES = ("fpt_logo.png", "fpt-logo.png", "logo_fpt.png", "fpt_logo.jpg")
     _BRAND_LOGO_HEIGHT = 22
@@ -661,6 +1106,11 @@ class MainWindow(QMainWindow):
         dlg = SettingsDialog(self.ctx, self)
         if dlg.exec():
             self._apply_theme()
+            # Settings can change the theme too — keep the rail's toggle icon
+            # showing the value that is actually in effect.
+            from .ui.icons import icon as _theme_icon
+            self.theme_btn.setIcon(
+                _theme_icon(self._THEME_ICONS.get(self.ctx.config.theme, "monitor")))
             set_language(self.ctx.config.language)   # apply if changed in Settings
             # reflect provider/theme/language changes
             i = self.provider_combo.findData(self.ctx.config.active_provider)
@@ -679,46 +1129,6 @@ class MainWindow(QMainWindow):
             self.sidebar.refresh()
             self.statusBar().showMessage(tr("app.status.settings_saved"))
 
-    def _reload_nav_children(self, page: int) -> None:
-        """(Re)build the nav children of a container page from its current
-        sub-views. Called when the page is built, when Workspace sub-tab
-        visibility changes, and on language change."""
-        if not (0 <= page < len(self._nav_items)):
-            return
-        item = self._nav_items[page]
-        expanded = item.isExpanded()
-        item.takeChildren()
-        widget = self._page_widgets[page]
-        if not hasattr(widget, "nav_subtabs"):
-            return
-        from .ui.icons import icon as _icon
-        for label, sub, icon_name in widget.nav_subtabs():
-            child = QTreeWidgetItem([label])
-            child.setIcon(0, _icon(icon_name))
-            child.setData(0, Qt.UserRole, {"page": page, "sub": sub, "parent": False})
-            item.addChild(child)
-        item.setExpanded(True)
-
-    def _on_nav_click(self, item, _col: int = 0) -> None:
-        # Clicking a parent toggles its expansion (its page is still shown).
-        data = item.data(0, Qt.UserRole) or {}
-        if data.get("parent"):
-            item.setExpanded(not item.isExpanded())
-
-    def _on_nav_expanded(self, item) -> None:
-        # Expanding a container whose children aren't built yet (e.g. Monitoring
-        # on first open, shown via its always-on dropdown arrow) builds its page
-        # so the sub-views appear.
-        data = item.data(0, Qt.UserRole) or {}
-        if data.get("parent") and item.childCount() == 0:
-            self._ensure_page(data.get("page", 0))
-
-    def _navigate(self, item) -> None:
-        if item is None:
-            return
-        data = item.data(0, Qt.UserRole) or {}
-        self._goto(data.get("page", 0), data.get("sub"))
-
     def _goto(self, page: int, sub) -> None:
         self._ensure_page(page)                # build lazy page on first visit
         self.pages.setCurrentIndex(page)
@@ -726,10 +1136,52 @@ class MainWindow(QMainWindow):
             self.workspace.refresh()           # re-list projects + threads on entry
         widget = self._page_widgets[page]
         if sub is not None and hasattr(widget, "select_subtab"):
-            widget.select_subtab(sub)
+            # Enforce the project gate here rather than at each entry point. A
+            # greyed rail row cannot be clicked, but _goto is also reached from
+            # RECENTS and from startup restore, and it used to open a sub-tab
+            # the gate was holding shut — page shown, tab strip still hiding it.
+            if hasattr(widget, "subtab_available") and not widget.subtab_available(sub):
+                self.statusBar().showMessage(tr("app.nav.needs_project"), 4000)
+            else:
+                widget.select_subtab(sub)
+        # Move the highlight with the content, however navigation was triggered —
+        # a programmatic _goto used to leave it on whatever was clicked last.
+        if not self._nav_building:
+            self._select_nav_row(page, sub)
+        self._update_dock_guard()
         # Switching pages updates which conversation is "current".
         self._refresh_history()
 
+    def _update_dock_guard(self) -> None:
+        """Keep the floating assistant clear of a screen's own bottom bar.
+
+        Only Cowork has one (the composer). Everywhere else the dock sits in
+        the corner as before.
+        """
+        dock = getattr(self, "help_agent", None)
+        if dock is None:
+            return
+        guard = 0
+        on_cowork = (self.pages.currentIndex() == self._ROW_WORKSPACE
+                     and self.workspace.current_subtab() == self.workspace._cowork_tab_idx)
+        if on_cowork:
+            comp = getattr(self.cowork, "composer", None)
+            if comp is not None and not comp.isHidden():
+                # Measured from the composer's TOP edge in window coordinates:
+                # its own height misses the extra row of controls laid out under
+                # it, which left the dot still overlapping by ~25px.
+                origin = comp.mapTo(self, comp.rect().topLeft())
+                # ...but only lift the dot if the composer is actually beneath
+                # it. The composer stops at the chat column's right edge, well
+                # short of the dot, so lifting it there raised the dot 156px for
+                # nothing — on Cowork alone it sat off the corner every other
+                # screen keeps it in.
+                dock_left = dock.x() - self.mapToGlobal(self.rect().topLeft()).x()
+                dock_right = dock_left + dock.width()
+                if dock_right > origin.x() and dock_left < origin.x() + comp.width():
+                    guard = max(0, self.height() - origin.y() + 8)
+        dock.set_bottom_guard(guard)
+
     def _on_projects_changed(self) -> None:
         self.sidebar.refresh()                 # History regroups by project
         self.cowork._apply_output_folder_label()  # project may have been renamed
@@ -738,6 +1190,7 @@ class MainWindow(QMainWindow):
     def _apply_theme(self) -> None:
         app = QApplication.instance()
         if app:
+            set_active_theme(self.ctx.config.theme)
             app.setStyleSheet(stylesheet(self.ctx.config.theme))
         # Re-apply theme styles to chat bubbles so they adapt to the new theme.
         self.cowork.apply_theme()
@@ -745,6 +1198,11 @@ class MainWindow(QMainWindow):
             self.help_agent.apply_theme()   # chat body follows theme (header stays fixed)
 
     # ---- sizing ------------------------------------------------------
+    # Share of the available screen the window takes when it has room to. Fixed
+    # pixels do not travel: 1180×760 fills a laptop and looks lost on a 4K
+    # panel. `want_*` stays the floor so a small screen behaves as before.
+    _SCREEN_SHARE_W, _SCREEN_SHARE_H = 0.80, 0.85
+
     def _fit_to_screen(self, want_w: int, want_h: int) -> None:
         screen = self.screen() or QGuiApplication.primaryScreen()
         avail = screen.availableGeometry() if screen else None
@@ -752,8 +1210,12 @@ class MainWindow(QMainWindow):
             self.resize(want_w, want_h)
             return
         margin = 60
-        w = min(want_w, avail.width() - margin)
-        h = min(want_h, avail.height() - margin)
+        # Take a share of the screen, never less than the asked-for size and
+        # never more than the screen can show.
+        w = min(max(want_w, int(avail.width() * self._SCREEN_SHARE_W)),
+                avail.width() - margin)
+        h = min(max(want_h, int(avail.height() * self._SCREEN_SHARE_H)),
+                avail.height() - margin)
         # minimum must never exceed what the screen can show
         self.setMinimumSize(min(820, avail.width() - margin), min(520, avail.height() - margin))
         self.resize(max(w, 1), max(h, 1))
@@ -761,6 +1223,25 @@ class MainWindow(QMainWindow):
         frame.moveCenter(avail.center())
         self.move(frame.topLeft())
 
+    def moveEvent(self, event):  # noqa: N802 - Qt override
+        super().moveEvent(event)
+        # Dragged to another monitor: its work area (and scaling) may differ, so
+        # the floating assistant re-pins and the panes re-decide if they fit.
+        self._on_screen_maybe_changed()
+
+    def _on_screen_maybe_changed(self) -> None:
+        screen = self.screen()
+        if screen is getattr(self, "_last_screen", None):
+            return
+        self._last_screen = screen
+        avail = screen.availableGeometry() if screen else None
+        if avail is not None:
+            self.setMinimumSize(min(820, avail.width() - 60),
+                                min(520, avail.height() - 60))
+        if getattr(self, "help_agent", None) is not None:
+            self._update_dock_guard()
+            self.help_agent.reposition()
+
     # ---- lifecycle ---------------------------------------------------
     def closeEvent(self, event) -> None:  # noqa: N802
         keep = (self.tray is not None
@@ -843,6 +1324,7 @@ def run(argv: List[str] | None = None) -> int:
             ctx.config.save()
     except Exception:  # noqa: BLE001 - seeding must never block startup
         pass
+    set_active_theme(ctx.config.theme)
     app.setStyleSheet(stylesheet(ctx.config.theme))
 
     # Follow the OS light/dark scheme live when theme is "Auto (System)".
@@ -858,6 +1340,7 @@ def run(argv: List[str] | None = None) -> int:
 
     def _reapply_system_theme(*_a):
         if ctx.config.theme == "system":
+            set_active_theme("system")
             app.setStyleSheet(stylesheet("system"))
             win.cowork.apply_theme()
     try:

application/__init__.py

@@ -0,0 +1 @@
+"""application/ — Điều phối use-case. KHÔNG import PySide6. Gọi domain + interface hạ tầng."""

application/conversations/__init__.py

@@ -0,0 +1 @@
+"""Application conversations package: turn lifecycle orchestration and agent execution."""

application/conversations/conversation_application_service.py

@@ -0,0 +1,322 @@
+"""The turn lifecycle, once, in pure Python (R04-T03).
+
+Extracted from ``core/chat_agent.py::run_cowork``, whose 260-line body mixed the
+lifecycle (compose the prompt, call the model, dispatch tools, respect the step
+ceiling, tidy the sandbox) with the concrete machinery that does each of those
+things. The lifecycle is the part with rules worth testing — and the part that
+was untestable, because reaching it meant standing up a Qt widget and a worker
+thread.
+
+Here it is a plain object driven through the seams in :mod:`turn_runtime`, so a
+test states a rule ("the guard runs before the model", "a rejected command never
+executes") in three lines. ``core/chat_agent.py`` keeps its signature and
+delegates, and the presentation layer keeps receiving the same events via the
+legacy codec, so nothing downstream had to change with it.
+
+Behavioural contract: this is a faithful port, not an improvement pass. Where
+the original had a quirk (the step-ceiling note only merges into the answer when
+the last message is the assistant's), the quirk is preserved and commented —
+changing what a user sees belongs in its own change, not smuggled into a move.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from ...domain.agents.agent_event import (
+    AssistantMessageCompletedEvent,
+    ErrorEvent,
+    OutputsAddedEvent,
+    OutputsRemovedEvent,
+    PlanStep,
+    PlanUpdatedEvent,
+    ReasoningChunkEvent,
+    TextChunkEvent,
+    ToolCallFinishedEvent,
+    ToolCallStartedEvent,
+    ToolOutputChunkEvent,
+)
+from ...domain.agents.agent_result import AgentResult
+from ...domain.agents.conversation_execution_request import ConversationExecutionRequest
+from .turn_runtime import (
+    BUDGET_NOTE_TEMPLATE,
+    GATED_TOOLS,
+    PLAN_TOOL,
+    REASONING_ONLY_NOTE,
+    REJECTED_OUTPUT,
+    AttachmentReader,
+    CancelFn,
+    CommandGuard,
+    ContextCompactor,
+    EventSink,
+    ModelCallPort,
+    PermissionRequest,
+    PromptGuard,
+    PromptPreparer,
+    ToolRuntimePort,
+)
+
+logger = logging.getLogger("cowork_local.application.conversations")
+
+
+class ConversationApplicationService:
+    """Runs one :class:`ConversationExecutionRequest` to completion."""
+
+    def __init__(
+        self,
+        model: ModelCallPort,
+        tools: ToolRuntimePort,
+        *,
+        prepare_prompt: Optional[PromptPreparer] = None,
+        prompt_guard: Optional[PromptGuard] = None,
+        command_guard: Optional[CommandGuard] = None,
+        compact: Optional[ContextCompactor] = None,
+        permission_request: Optional[PermissionRequest] = None,
+        attachment_reader: Optional[AttachmentReader] = None,
+    ) -> None:
+        self._model = model
+        self._tools = tools
+        # Every hook is optional so the service degrades to a plain chat turn.
+        # That is not only a test convenience: a headless caller legitimately has
+        # no guards (``security_config=None`` today) and no permission dialog.
+        self._prepare_prompt = prepare_prompt
+        self._prompt_guard = prompt_guard
+        self._command_guard = command_guard
+        self._compact = compact
+        self._permission_request = permission_request
+        self._attachment_reader = attachment_reader
+
+    # -- public API ------------------------------------------------------ #
+    def execute(self, request: ConversationExecutionRequest, sink: EventSink,
+                cancel: Optional[CancelFn] = None,
+                messages: Optional[List[Dict[str, Any]]] = None) -> AgentResult:
+        """Run the turn, streaming events to ``sink``, and report the outcome.
+
+        ``messages``, when given, is a working list the caller already built —
+        it MUST already end with this turn's user message, and the service
+        appends into that very object instead of composing its own. The Cowork
+        widget needs this: it hands out the same list to
+        ``_reattach_running_turn``, which replays the steps done so far while the
+        worker is still appending, and to ``_finalize_turn``, which slices it by
+        the pre-turn snapshot length. A private list would break both silently.
+        Passing ``None`` (every headless caller) lets the service compose the
+        list from the request, which is the mode the rest of this class assumes.
+
+        Raises whatever the runtime raises (a blocked prompt, a dead gateway):
+        the caller already has a failure path for that — ``AgentWorker.failed``
+        in the UI, the artifact writer in Schedule Task — and swallowing the
+        exception here would silently turn a failed turn into an empty answer.
+        An :class:`ErrorEvent` is emitted first so subscribers see the failure
+        on the same stream as everything else.
+        """
+        cancel = cancel or (lambda: False)
+
+        # -- pre-flight. Runs BEFORE the output snapshot, so a turn refused here
+        #    leaves the output folder completely untouched (tidying is not a
+        #    read-only operation — see ToolRuntimePort.finalize).
+        try:
+            # The caller's list is used by reference on purpose (see above); only
+            # the self-composed path may build a fresh one.
+            working = messages if messages is not None else self._compose_messages(request)
+            tools = list(self._tools.specs(request.allowed_tools))
+            if self._prepare_prompt is not None:
+                self._prepare_prompt(working, tuple(getattr(t, "name", "") for t in tools))
+            if request.enforce_rules and self._prompt_guard is not None:
+                self._prompt_guard(working)
+        except Exception as exc:  # noqa: BLE001 — reported, then re-raised as-is
+            sink(ErrorEvent(message=str(exc)))
+            raise
+
+        before = self._tools.snapshot()
+        steps_used = 0
+        plan_steps: Tuple[PlanStep, ...] = ()
+        completed_naturally = False
+        try:
+            for _ in range(request.effective_max_steps):
+                if cancel():
+                    break
+                # Auto-compress when nearing the model's context budget; a no-op
+                # when off or when the conversation is still short.
+                if self._compact is not None:
+                    self._compact(working, cancel)
+
+                assistant = self._model.call(
+                    working, tools,
+                    on_text=lambda piece: sink(TextChunkEvent(delta=piece)),
+                    on_reasoning=lambda piece: sink(ReasoningChunkEvent(delta=piece)),
+                    cancel=cancel,
+                )
+                working.append(assistant)
+                steps_used += 1
+                tool_calls = assistant.get("tool_calls") or []
+
+                if not tool_calls and not (assistant.get("content") or "").strip():
+                    # Written into the message, not just emitted, so the stored
+                    # conversation never ends on a blank assistant turn.
+                    assistant["content"] = REASONING_ONLY_NOTE
+                    sink(TextChunkEvent(delta=REASONING_ONLY_NOTE))
+                sink(AssistantMessageCompletedEvent(content=assistant.get("content", "")))
+
+                if not tool_calls:
+                    completed_naturally = True
+                    break
+
+                for call in tool_calls:
+                    if cancel():
+                        break
+                    tool_message, steps = self._dispatch(request, call, sink, cancel)
+                    working.append(tool_message)
+                    if steps is not None:
+                        plan_steps = steps
+
+            if not completed_naturally and not cancel():
+                self._announce_budget_exhausted(request, working, sink)
+        except Exception as exc:  # noqa: BLE001 — reported, then re-raised as-is
+            sink(ErrorEvent(message=str(exc)))
+            raise
+        finally:
+            # Always tidy: the sandbox and generator scripts must not survive a
+            # turn that stopped abruptly. Runs on success, cancel and failure.
+            self._finalize_outputs(before, sink, cancelled=cancel())
+
+        result = AgentResult(
+            messages=working, steps_used=steps_used, cancelled=cancel(),
+            budget_exhausted=not completed_naturally and not cancel(),
+            plan_steps=plan_steps,
+        )
+        sink(result.to_turn_completed_event())
+        return result
+
+    # -- internals ------------------------------------------------------- #
+    def _compose_messages(self, request: ConversationExecutionRequest) -> List[Dict[str, Any]]:
+        """History snapshot plus this turn's user message.
+
+        The attachment text is read HERE rather than when the request was built,
+        because extraction is slow enough to freeze the UI thread; the request
+        deliberately carries paths only.
+        """
+        body = request.prompt
+        if self._attachment_reader is not None:
+            body = self._attachment_reader(request.prompt, request.attachments)
+        messages = [dict(m) for m in request.messages]
+        messages.append({"role": "user", "content": request.user_content(body)})
+        return messages
+
+    def _dispatch(self, request: ConversationExecutionRequest, call: Dict[str, Any],
+                  sink: EventSink, cancel: CancelFn
+                  ) -> Tuple[Dict[str, Any], Optional[Tuple[PlanStep, ...]]]:
+        """Run one tool call.
+
+        Returns ``(tool_message, plan_steps)`` — the message to append to the
+        conversation, and the new checklist when this call was the plan tool
+        (``None`` otherwise, so the caller can tell "no change" from "empty
+        plan").
+        """
+        call_id = str(call.get("id", ""))
+        name = str(call.get("name", ""))
+        args = call.get("arguments") or {}
+
+        # The plan tool is invisible in the transcript: it updates the Plan panel
+        # and nothing else, so it skips preview, guard and gate entirely.
+        if name == PLAN_TOOL:
+            outcome = self._tools.execute(name, args, on_output=None, cancel=cancel)
+            steps = tuple(outcome.get("plan_steps") or ())
+            sink(PlanUpdatedEvent(steps=steps))
+            return self._tool_message(call_id, name, outcome.get("output", "")), steps
+
+        # Announce first: the user sees the code/command about to run before the
+        # guard or the approval dialog interrupts them, which is the whole point
+        # of showing the step CLI-style.
+        preview = self._tools.preview(name, args)
+        sink(ToolCallStartedEvent(call_id=call_id, name=name, arguments=dict(args),
+                                  preview=preview))
+
+        if request.enforce_rules and self._command_guard is not None:
+            self._command_guard(name, args)
+
+        if not self._approved(request, name, args, preview, sink, call_id):
+            return self._tool_message(call_id, name, REJECTED_OUTPUT), None
+
+        outcome = self._tools.execute(
+            name, args,
+            on_output=lambda piece: sink(ToolOutputChunkEvent(
+                call_id=call_id, name=name, delta=piece)),
+            cancel=cancel,
+        )
+        sink(ToolCallFinishedEvent(
+            call_id=call_id, name=name, ok=bool(outcome.get("ok", False)),
+            output=str(outcome.get("output", "")), path=str(outcome.get("path", "") or ""),
+            produced=outcome.get("produced") or (),
+        ))
+        return self._tool_message(call_id, name, outcome.get("output", "")), None
+
+    def _approved(self, request: ConversationExecutionRequest, name: str,
+                  args: Dict[str, Any], preview: Any, sink: EventSink,
+                  call_id: str) -> bool:
+        """Whether this call may run.
+
+        Only command-shaped tools are gated, and only when the workspace asked
+        to confirm them: file writes stay inside the turn's own sandbox, so
+        prompting for those would be noise. A rejection is reported as a failed
+        tool result — the model needs to read back that it was refused, or it
+        will simply try the same call again.
+        """
+        if not request.requires_permission_gate or name not in GATED_TOOLS:
+            return True
+        if self._permission_request is None:
+            # Confirm mode with nobody to ask: refusing is the safe direction,
+            # since auto-running is exactly what confirm mode exists to prevent.
+            logger.warning("turn: confirm mode without a permission callback — refusing %r", name)
+            approved = False
+        else:
+            approved = bool(self._permission_request({
+                "name": name, "args": args,
+                "preview": preview.to_dict() if preview is not None else {},
+            }))
+        if not approved:
+            sink(ToolCallFinishedEvent(call_id=call_id, name=name, ok=False,
+                                       output=REJECTED_OUTPUT))
+        return approved
+
+    @staticmethod
+    def _tool_message(call_id: str, name: str, output: Any) -> Dict[str, Any]:
+        """The canonical ``role: tool`` message the model reads back."""
+        return {"role": "tool", "tool_call_id": call_id, "name": name,
+                "content": str(output or "")}
+
+    @staticmethod
+    def _announce_budget_exhausted(request: ConversationExecutionRequest,
+                                   messages: List[Dict[str, Any]], sink: EventSink) -> None:
+        """Report being cut off by the step ceiling.
+
+        The note always reaches the transcript. It is merged into the stored
+        answer only when the last message is the assistant's — which, when the
+        ceiling is hit, it never is (the turn ends on a tool result). The branch
+        is kept because it is what the current runtime does, and because it is
+        the correct behaviour the day a caller ends the loop differently.
+        """
+        note = BUDGET_NOTE_TEMPLATE.format(steps=request.effective_max_steps)
+        sink(TextChunkEvent(delta=note))
+        if messages and messages[-1].get("role") == "assistant":
+            messages[-1]["content"] = (messages[-1].get("content") or "") + note
+
+    def _finalize_outputs(self, before: Any, sink: EventSink, cancelled: bool) -> None:
+        """Tidy the output folder and report what moved.
+
+        Failures are logged, never raised: this runs in a ``finally``, so an
+        exception here would replace the turn's real error (or its success) with
+        a housekeeping one.
+        """
+        try:
+            removed, added = self._tools.finalize(before, cancelled=cancelled)
+        except Exception:  # noqa: BLE001
+            logger.exception("turn: tidying the output folder failed")
+            return
+        if removed:
+            sink(OutputsRemovedEvent(paths=tuple(removed)))
+        if added:
+            sink(OutputsAddedEvent(paths=tuple(added)))
+
+
+__all__ = ["ConversationApplicationService"]

application/conversations/core_runtime_adapter.py

@@ -0,0 +1,325 @@
+"""Wires :class:`ConversationApplicationService` to the existing runtime (R04-T03).
+
+The service is written against the narrow seams in :mod:`turn_runtime` so it can
+be tested with plain fakes. This module supplies the real implementations — the
+provider call with its recovery pass, the tool/sandbox runtime, the security
+guards, context compaction — and is therefore the ONLY file in
+``application/conversations/`` that knows ``core/*`` exists. Same shape (and
+same reason) as ``application/model_routing/core_routing_adapter.py`` in R03.
+
+Every ``core`` import is deferred into a method body: importing the tool runtime
+pulls in ``requests``, ``psutil`` and the sandbox stack, and code that merely
+*builds* a service must not pay for that.
+
+Faithfulness notes — two places where this reproduces a quirk of the current
+runtime rather than the behaviour one would design fresh. Both are marked
+inline: the MS365 system-prompt paragraph keys off the CONFIGURED extra tools
+(not the advertised subset), and the ``tool_result`` path falls back to the
+call's own ``path`` argument resolved against the workdir.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+from ...domain.agents.agent_event import PlanStep, ToolPreview
+from .conversation_application_service import ConversationApplicationService
+from .turn_runtime import PLAN_TOOL, EventSink
+
+# Legacy emit: the dict-based callback every current caller already owns.
+LegacyEmit = Callable[[Dict[str, Any]], None]
+
+
+def legacy_event_sink(emit: LegacyEmit) -> EventSink:
+    """Adapt a typed :class:`EventSink` onto the legacy dict ``emit``.
+
+    This is what lets R04 land without touching the presentation layer: the
+    service thinks in typed events, ``ui/chat_panel.py::_on_event`` keeps
+    receiving exactly the dicts it already dispatches on. Deleted in R08 once
+    the widget consumes events directly.
+    """
+    return lambda event: emit(event.to_legacy_dict())
+
+
+class CoreModelCall:
+    """:class:`ModelCallPort` over ``code_agent._call_provider_with_recovery``.
+
+    Not ``provider.chat`` directly: the recovery wrapper adds the one bounded
+    retry that hides a dropped connection or a momentarily unreachable gateway,
+    and losing it would be a visible regression on flaky corporate networks.
+    """
+
+    def __init__(self, provider: Any) -> None:
+        self._provider = provider
+
+    def call(self, messages, tools, on_text=None, on_reasoning=None, cancel=None):
+        from ...core.code_agent import _call_provider_with_recovery
+
+        return _call_provider_with_recovery(self._provider, messages, tools, on_text,
+                                            cancel, on_reasoning)
+
+
+class CoreToolRuntime:
+    """:class:`ToolRuntimePort` over ``core/tools.py`` + Cowork's file tools."""
+
+    def __init__(self, output_dir: Path, *, title: str = "",
+                 extra_tools: Optional[Sequence[Any]] = None, extra_executor=None,
+                 security_config: Any = None, agent_role: str = "") -> None:
+        self._output_dir = Path(output_dir)
+        self._title = title
+        self._extra_tools = list(extra_tools or ())
+        self._extra_names = {getattr(t, "name", "") for t in self._extra_tools}
+        # The connector executor MCP/REST tools are routed to; None when the
+        # turn has no connectors enabled.
+        self._extra_executor = extra_executor
+        self._security_config = security_config
+        self._agent_role = agent_role
+        self._ctx: Any = None          # built on first use (see _tool_context)
+
+    # -- the configured extra tools, for the system-prompt hints ---------- #
+    @property
+    def extra_names(self) -> frozenset:
+        return frozenset(self._extra_names)
+
+    def _tool_context(self):
+        """The sandboxed ``ToolContext`` every built-in tool call runs inside.
+
+        Built once per turn and cached: it carries the resource limits and the
+        network policy, so re-deriving it mid-turn could let a Settings change
+        take effect halfway through work already in flight.
+        """
+        if self._ctx is None:
+            from ...core import agent_security
+            from ...core.tools import ToolContext
+
+            limits, block_network = agent_security.sandbox_settings(self._security_config)
+            self._ctx = ToolContext(
+                self._output_dir, flatten_writes=True,   # keep every file in the Output root
+                resource_limits=limits, block_network=block_network,
+                allow_url_fetch=agent_security.url_fetch_allowed(self._security_config),
+                jira=(self._security_config.data.get("jira") if self._security_config else None),
+            )
+        return self._ctx
+
+    # -- ToolRuntimePort -------------------------------------------------- #
+    def specs(self, allowed_tools: Optional[Sequence[str]] = None) -> List[Any]:
+        """Advertised tools: Cowork's own two, the enabled built-ins, then MCP.
+
+        ``allowed_tools`` restricts the list so a read-only step literally cannot
+        write. ``update_plan`` and the connector tools always survive the filter:
+        the plan tool has no side effects, and connectors are opted into
+        explicitly rather than governed by the built-in capability scope.
+        """
+        from ...core.chat_agent import SAVE_FILE_SPEC
+        from ...core.plan import UPDATE_PLAN_SPEC
+        from ...core.tools import enabled_tool_specs
+
+        specs = ([SAVE_FILE_SPEC, UPDATE_PLAN_SPEC]
+                 + list(enabled_tool_specs(self._security_config))
+                 + self._extra_tools)
+        if allowed_tools is None:
+            return specs
+        allow = set(allowed_tools) | {PLAN_TOOL} | self._extra_names
+        return [t for t in specs if getattr(t, "name", "") in allow]
+
+    def preview(self, name: str, args: Dict[str, Any]) -> Optional[ToolPreview]:
+        """What the user sees before the call runs."""
+        # A connector call has no local diff to show, so it renders as the plain
+        # argument dump the runtime already used.
+        if name in self._extra_names:
+            return ToolPreview(kind="info", title=name, text=str(args))
+        if name == "save_file":
+            return self._save_file_preview(args)
+        from ...core.tools import describe_action
+
+        raw = describe_action(self._tool_context(), name, args)
+        return ToolPreview.from_dict(raw)
+
+    def _save_file_preview(self, args: Dict[str, Any]) -> ToolPreview:
+        """A before/after diff for the file the agent is about to write.
+
+        A brand-new file renders all-green (before is empty); an overwrite shows
+        the real change, so saving a file reads like editing one.
+        """
+        import difflib
+
+        from ...core.chat_agent import _structure_summary, _titled_filename
+
+        fname = _titled_filename(self._title, args.get("filename", "output.txt"))
+        content = str(args.get("content", ""))
+        summary = _structure_summary(fname, content)
+        old = ""
+        existing = self._output_dir / fname
+        if existing.exists():
+            try:
+                old = existing.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                pass   # unreadable existing file: show it as a fresh write
+        diff = "".join(difflib.unified_diff(
+            old.splitlines(keepends=True), content.splitlines(keepends=True),
+            fromfile=f"a/{fname}", tofile=f"b/{fname}",
+        )) or content[:4000]
+        return ToolPreview(kind="diff", title=f"Save {fname}",
+                           text=f"{summary}\n\n{diff[:4000]}")
+
+    def execute(self, name: str, args: Dict[str, Any], on_output=None,
+                cancel=None) -> Dict[str, Any]:
+        """Run one tool call and return the runtime's result mapping."""
+        if name == PLAN_TOOL:
+            return self._execute_plan(args)
+        if name in self._extra_names and self._extra_executor is not None:
+            # Connector results carry no local file, so no path/produced keys —
+            # matching what the runtime reports for an MCP call today.
+            result = self._extra_executor(name, args) or {}
+            return {"ok": bool(result.get("ok", False)), "output": result.get("output", "")}
+        if name == "save_file":
+            from ...core.chat_agent import _do_save_file
+
+            return dict(_do_save_file(self._output_dir, self._title, args))
+
+        from ...core.tools import execute_tool
+
+        ctx = self._tool_context()
+        result = dict(execute_tool(ctx, name, args, cancel=cancel, on_output=on_output,
+                                   agent_role=self._agent_role))
+        # Quirk preserved: a tool that wrote the file named in its OWN arguments
+        # (write_file/edit_file) does not report a path, so the runtime derives
+        # one from the argument. Dropping this would empty the Output list.
+        if not result.get("path") and isinstance(args, dict) and args.get("path"):
+            result["path"] = str(ctx.workdir / str(args["path"]))
+        return result
+
+    def _execute_plan(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Apply an ``update_plan`` call: validate the steps and audit them.
+
+        Produces no file and no chat bubble; the service turns the returned
+        steps into a single plan event.
+        """
+        from ...core import agent_roles, audit_log
+        from ...core.plan import normalize_plan_steps
+
+        steps = normalize_plan_steps(args.get("steps"))
+        audit_log.record("tool_call", PLAN_TOOL, True, f"{len(steps)} step(s)",
+                         agent_role=agent_roles.PLANNER)
+        return {"ok": True, "output": "Plan updated.",
+                "plan_steps": [PlanStep(title=s["title"], status=s["status"]) for s in steps]}
+
+    def snapshot(self) -> Any:
+        from ...core.tools import _snapshot
+
+        return _snapshot(self._output_dir)
+
+    def finalize(self, before: Any, cancelled: bool = False
+                 ) -> Tuple[List[str], List[str]]:
+        """Drop the scratch sandbox and flatten deliverables into the root.
+
+        Returns ``(gone, arrived)``: a file that MOVED counts as both, because
+        the Output list keys entries by path and must drop the old one.
+        """
+        from ...core.chat_agent import _cleanup_cowork_intermediates
+
+        removed, moved = _cleanup_cowork_intermediates(self._output_dir, before,
+                                                       cancelled=cancelled)
+        gone = list(removed) + [old for old, _new in moved]
+        arrived = [new for _old, new in moved]
+        return gone, arrived
+
+
+def build_cowork_conversation_service(
+    provider: Any,
+    output_dir: Path,
+    emit: LegacyEmit,
+    *,
+    title: str = "",
+    project_context: str = "",
+    extra_tools: Optional[Sequence[Any]] = None,
+    extra_executor=None,
+    security_config: Any = None,
+    gate: Any = None,
+    agent_role: str = "",
+) -> ConversationApplicationService:
+    """A service wired to the real runtime, ready to execute a Cowork turn.
+
+    ``emit`` is the legacy dict callback: the guards and the compactor publish
+    their own notices through it directly (exactly as they do now), while the
+    service's typed events reach it via :func:`legacy_event_sink`.
+
+    ``gate`` present means the workspace asked to confirm commands; pass the
+    request with ``gate_mode="confirm"`` so the two agree. A gate of ``None``
+    keeps the pre-existing auto-run behaviour.
+    """
+    from ...core import agent_roles
+
+    tools = CoreToolRuntime(
+        output_dir, title=title, extra_tools=extra_tools, extra_executor=extra_executor,
+        security_config=security_config, agent_role=agent_role or agent_roles.COWORK,
+    )
+
+    def prepare_prompt(messages: List[Dict[str, Any]], advertised: Tuple[str, ...]) -> None:
+        """Insert the system prompt, then fold in skills, rules and project text.
+
+        ``advertised`` is unused on purpose: the runtime decides the MS365
+        paragraph from the CONFIGURED connector tools, not from the subset a
+        capability scope left advertised. Changing that changes the prompt the
+        model sees, so it stays as-is here and belongs to R05's tool-policy work.
+        """
+        from ...core.chat_agent import (
+            COWORK_TOOL_PROMPT,
+            OPENDATALOADER_PDF_PROMPT,
+            _apply_project_context,
+            _apply_security_rules,
+            _apply_skills,
+        )
+        from ...core.deps import _can_pip
+        from ...core.java_runtime import find_java
+        from ...core.security_rules import load_rules
+        from ...core.skills import active_skills_text
+
+        if not messages or messages[0].get("role") != "system":
+            system = COWORK_TOOL_PROMPT
+            if any(n.startswith("ms365_") for n in tools.extra_names):
+                system += ("\nThe user has signed in to Microsoft 365 and enabled some ms365__* "
+                           "tools (Outlook / Teams / OneDrive / SharePoint / meeting transcripts, "
+                           "via the built-in MS365 MCP server). Use them whenever the request "
+                           "involves that data — don't say you can't access it.")
+            if find_java() is not None and _can_pip():
+                # Only advertise the Java-backed PDF extractor when BOTH the JVM
+                # and pip are available, so the agent is never steered into a
+                # command that cannot work on this machine.
+                system += "\n\n" + OPENDATALOADER_PDF_PROMPT
+            messages.insert(0, {"role": "system", "content": system})
+        _apply_skills(messages, active_skills_text())
+        _apply_security_rules(messages, load_rules())
+        _apply_project_context(messages, project_context)
+
+    def prompt_guard(messages: List[Dict[str, Any]]) -> None:
+        from ...core import agent_security
+
+        agent_security.enforce_prompt(provider, messages, security_config, emit)
+
+    def command_guard(name: str, args: Dict[str, Any]) -> None:
+        from ...core import agent_security
+
+        agent_security.enforce_command(provider, name, args, security_config, emit)
+
+    def compact(messages: List[Dict[str, Any]], cancel) -> None:
+        from ...core import context_budget
+
+        context_budget.maybe_compact(provider, messages, security_config,
+                                     emit=emit, cancel=cancel)
+
+    return ConversationApplicationService(
+        CoreModelCall(provider), tools,
+        prepare_prompt=prepare_prompt,
+        prompt_guard=prompt_guard,
+        command_guard=command_guard,
+        compact=compact,
+        permission_request=(gate.request if gate is not None else None),
+    )
+
+
+__all__ = [
+    "LegacyEmit", "legacy_event_sink", "CoreModelCall", "CoreToolRuntime",
+    "build_cowork_conversation_service",
+]

application/conversations/cowork_turn_request.py

@@ -0,0 +1,77 @@
+"""Turn the Cowork widget's captured state into a request (R04-T04).
+
+``ui/cowork_tab.py::build_job`` reads a dozen values off the widget on the UI
+thread and has to translate three of them before a turn can run: which message
+is this turn's prompt, which messages are its history, and whether the workspace
+wants commands confirmed. Those rules lived inline in the widget, where no test
+could reach them — and each fails silently when wrong (a duplicated user message,
+or a command that quietly stops asking for approval).
+
+They live here instead, as the mapping step the migration map assigns to the
+application layer. The widget keeps only what is genuinely widget-specific:
+reading its own state and building the provider.
+
+Layer rules (``docs/architecture/ADR-001-layered-architecture.md``): pure Python.
+Everything arrives as a plain value, so this module never sees a widget.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence
+
+from ...domain.agents.conversation_execution_request import ConversationExecutionRequest
+
+
+def build_cowork_turn_request(
+    *,
+    turn_id: str,
+    session_id: str,
+    messages: Sequence[Dict[str, Any]],
+    surface: str = "cowork",
+    project_id: str = "",
+    title: str = "",
+    provider_id: str = "",
+    model: str = "",
+    instructions: str = "",
+    output_dir: Optional[Any] = None,
+    home_output_root: Optional[Any] = None,
+    confirm_commands: bool = False,
+    agent_role: str = "cowork",
+) -> ConversationExecutionRequest:
+    """Build one Cowork turn's immutable request.
+
+    ``messages`` is the widget's working list, which ALREADY ends with this
+    turn's user message (the chat panel composes it — prefix, attachments,
+    session notes — before the job starts). So the prompt is that last message
+    and the history is everything before it. The request records both; the
+    service is handed the same working list and appends into it.
+
+    Keyword-only on purpose: a dozen positional strings in a call site is exactly
+    how a title ends up in the project-id slot.
+    """
+    history = list(messages or ())
+    # ``pop`` rather than ``[-1]``/``[:-1]`` so the empty-list case needs no
+    # special branch: a turn with nothing in it yields an empty prompt instead of
+    # raising IndexError deep inside a worker thread.
+    last = history.pop() if history else {}
+    return ConversationExecutionRequest(
+        turn_id=turn_id,
+        session_id=session_id,
+        surface=surface,
+        project_id=project_id,
+        title=title,
+        prompt=str(last.get("content") or ""),
+        messages=history,
+        provider_id=provider_id,
+        model=model,
+        project_context=instructions,
+        output_dir=output_dir,
+        home_output_root=home_output_root,
+        # The workspace's Auto-run override (or the global setting) decides
+        # whether run_command/install_package must be approved first.
+        gate_mode="confirm" if confirm_commands else "auto",
+        agent_role=agent_role,
+    )
+
+
+__all__ = ["build_cowork_turn_request"]

application/conversations/turn_runtime.py

@@ -0,0 +1,177 @@
+"""The seams :mod:`conversation_application_service` runs a turn through (R04-T03).
+
+Two Protocols and six callables — chosen deliberately, not by reflex. The
+refactor plan forbids giving every class an interface, so a contract exists here
+only where there is both a real ``core/*`` implementation AND a test double:
+
+* :class:`ModelCallPort` — one provider round-trip *including* the app's
+  existing context-overflow recovery, which is why the raw ``Provider.chat``
+  signature is not enough.
+* :class:`ToolRuntimePort` — the tool + output-folder runtime, kept as one
+  cohesive object because every method operates on the same sandbox.
+
+Everything else is a single function, so it is expressed as a callable type
+rather than a class with one method (the same choice R03 made for
+``ConfirmationCallback``). All of them are optional: a service built with none
+of them still runs a plain chat turn, which is what keeps the unit tests short.
+
+Layer rules (``docs/architecture/ADR-001-layered-architecture.md``): application
+layer — pure Python. Nothing here imports PySide6, ``core.*``, ``providers.*``
+or ``ui.*``; the concrete wiring lives in :mod:`core_runtime_adapter`.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Protocol,
+    Sequence,
+    Tuple,
+    runtime_checkable,
+)
+
+from ...domain.agents.agent_event import AgentEvent, ToolPreview
+
+# The plan tool is special-cased by the loop: it drives the Plan panel and
+# produces no chat bubble and no file. Named here so the check is not a bare
+# string literal in the middle of the dispatch.
+PLAN_TOOL = "update_plan"
+
+# Tools that need approval before they run when the workspace is in confirm
+# mode. R05 replaces this tuple with a real ``ToolPolicyGateway`` keyed on
+# ToolCapability; until then it mirrors exactly what the runtime gates today.
+GATED_TOOLS = ("run_command", "install_package")
+
+# Shown when the user (or the workspace policy) rejects a proposed command. The
+# exact string also becomes the tool message the model reads back, so it must
+# stay stable.
+REJECTED_OUTPUT = "Rejected by user."
+
+# A reasoning model can answer with thinking only. The note is written into the
+# assistant message itself, not merely emitted, so an unattended run does not
+# read back an empty answer and report "(no output)".
+REASONING_ONLY_NOTE = "*(model returned only its reasoning — try rephrasing)*"
+
+# Emitted when the turn is stopped by its own safety ceiling rather than by the
+# model finishing. Never silent: being cut off looks exactly like being done.
+BUDGET_NOTE_TEMPLATE = (
+    "\n\n⚠️ Reached the {steps}-step safety limit before the task signalled "
+    "completion — stopping here. Re-run to continue if more work remains."
+)
+
+
+def combine_instructions(*blocks: Optional[str]) -> str:
+    """Join the standing-instruction blocks of a turn, skipping the absent ones.
+
+    A turn's instructions arrive as several independent blocks — the project's
+    shared context, an Admin agent's persona, a skill's rules, the
+    "this runs unattended" reminder — and each caller was joining them inline
+    with its own ``f"{a}\\n\\n{b}" if a else b`` expression. Two call sites now
+    need the same rule (the Cowork widget in R04-T04 and the task runner in
+    R04-T05), which is the point at which it stops being an expression.
+
+    Whitespace-only blocks count as absent: they would otherwise open the system
+    prompt with a stray blank line.
+    """
+    return "\n\n".join(b.strip() for b in blocks if b and b.strip())
+
+
+# --------------------------------------------------------------------------- #
+# Callables.
+# --------------------------------------------------------------------------- #
+# Receives every typed event the turn produces. The caller decides what that
+# means — render it, forward it as a legacy dict, autosave on it.
+EventSink = Callable[[AgentEvent], None]
+
+# True once the user has asked to stop. Polled between steps and between tool
+# calls, the same cadence the current runtime uses.
+CancelFn = Callable[[], bool]
+
+# ``(prompt, attachment_paths) -> body``. Runs on the worker thread because
+# extracting a .docx may pip-install a parser or call LibreOffice.
+AttachmentReader = Callable[[str, Tuple[str, ...]], str]
+
+# ``(messages, advertised_tool_names) -> None`` — inserts the system prompt and
+# folds in skills, security rules and project instructions, in place. It needs
+# the tool names because the system prompt gains an MS365 paragraph only when
+# ms365 tools are actually present.
+PromptPreparer = Callable[[List[Dict[str, Any]], Tuple[str, ...]], None]
+
+# Reviews the assembled request; raises to refuse the turn outright.
+PromptGuard = Callable[[List[Dict[str, Any]]], None]
+
+# Reviews one proposed tool call; raises to refuse it.
+CommandGuard = Callable[[str, Dict[str, Any]], None]
+
+# ``(messages, cancel) -> None``. Summarises old turns in place when the
+# conversation nears the model's context budget; a no-op when compaction is off
+# or the conversation is short. It takes the cancel signal because compacting
+# calls the model itself, so Stop has to reach it too.
+ContextCompactor = Callable[[List[Dict[str, Any]], "CancelFn"], None]
+
+# ``(action) -> approved``. Blocks the worker thread while a human decides.
+PermissionRequest = Callable[[Dict[str, Any]], bool]
+
+
+# --------------------------------------------------------------------------- #
+# Ports.
+# --------------------------------------------------------------------------- #
+@runtime_checkable
+class ModelCallPort(Protocol):
+    """One call to the model, with the app's retry/recovery behaviour applied."""
+
+    def call(self, messages: List[Dict[str, Any]], tools: Sequence[Any],
+             on_text: Optional[Callable[[str], None]] = None,
+             on_reasoning: Optional[Callable[[str], None]] = None,
+             cancel: Optional[CancelFn] = None) -> Dict[str, Any]:
+        """Return the canonical assistant message (content plus tool calls)."""
+
+
+@runtime_checkable
+class ToolRuntimePort(Protocol):
+    """The tools a turn may call, and the folder its files land in."""
+
+    def specs(self, allowed_tools: Optional[Sequence[str]] = None) -> Sequence[Any]:
+        """Tool specs to advertise to the model, already filtered.
+
+        Returns opaque objects (the provider layer's ``ToolSpec``); the service
+        only ever reads ``.name`` off them, which is what keeps this layer free
+        of a provider import.
+        """
+
+    def preview(self, name: str, args: Dict[str, Any]) -> Optional[ToolPreview]:
+        """Human-readable description of a call that is about to run."""
+
+    def execute(self, name: str, args: Dict[str, Any],
+                on_output: Optional[Callable[[str], None]] = None,
+                cancel: Optional[CancelFn] = None) -> Dict[str, Any]:
+        """Run one tool call.
+
+        Returns the runtime's own result mapping: ``ok``, ``output``, optionally
+        ``path``/``produced`` for files it created, and ``plan_steps`` for the
+        plan tool.
+        """
+
+    def snapshot(self) -> Any:
+        """Opaque record of the output folder before the turn started."""
+
+    def finalize(self, before: Any, cancelled: bool = False
+                 ) -> Tuple[Sequence[str], Sequence[str]]:
+        """Tidy the output folder; return ``(removed_paths, added_paths)``.
+
+        Not read-only — it deletes the scratch sandbox and flattens sub-folders —
+        so the service only calls it for a turn that actually started.
+        """
+
+
+__all__ = [
+    "PLAN_TOOL", "GATED_TOOLS", "REJECTED_OUTPUT", "REASONING_ONLY_NOTE",
+    "BUDGET_NOTE_TEMPLATE", "combine_instructions",
+    "EventSink", "CancelFn", "AttachmentReader", "PromptPreparer", "PromptGuard",
+    "CommandGuard", "ContextCompactor", "PermissionRequest",
+    "ModelCallPort", "ToolRuntimePort",
+]

application/model_routing/__init__.py

@@ -0,0 +1,54 @@
+"""Application model routing package: model route decisions and multi-provider balancing.
+
+Public surface (R03-T03 — the single routing entry point every chat surface uses):
+
+* :class:`RoutingApplicationService` — decides one turn's provider/model.
+* :class:`RoutingRequest` / :class:`RoutingOutcome` — the immutable DTOs in and out.
+* :class:`RoutingMode` — Off / Auto / Manual / Fallback.
+* :func:`build_routing_application_service` — wires the service to a live
+  ``AppContext`` (engine + per-workspace mode + confirm timeout).
+
+Typical call site (see ``ui/chat_panel.py::_apply_routing``)::
+
+    service = build_routing_application_service(self.ctx)
+    outcome = service.resolve(
+        RoutingRequest(surface="cowork", prompt=text,
+                       current_provider=provider, current_model=model),
+        confirm=lambda decision, timeout: confirm_switch(self, decision, timeout),
+    )
+
+Only ``core_routing_adapter`` touches ``core/routing``; the service and the DTOs
+stay pure Python so the whole rule set is testable without Qt or the engine.
+"""
+
+from .core_routing_adapter import (
+    AppContextModeResolver,
+    CoreRoutingEngine,
+    build_routing_application_service,
+)
+from .routing_application_service import (
+    ConfirmationCallback,
+    ModeResolver,
+    RoutingApplicationService,
+    RoutingDecisionPort,
+)
+from .routing_models import (
+    RouteEvaluation,
+    RoutingMode,
+    RoutingOutcome,
+    RoutingRequest,
+)
+
+__all__ = [
+    "AppContextModeResolver",
+    "ConfirmationCallback",
+    "CoreRoutingEngine",
+    "ModeResolver",
+    "RouteEvaluation",
+    "RoutingApplicationService",
+    "RoutingDecisionPort",
+    "RoutingMode",
+    "RoutingOutcome",
+    "RoutingRequest",
+    "build_routing_application_service",
+]

application/model_routing/core_routing_adapter.py

@@ -0,0 +1,169 @@
+"""Adapters that plug the existing routing engine into the application service.
+
+:mod:`routing_application_service` is written against two narrow ports so it can
+be unit-tested with plain fakes. This module supplies the real implementations —
+the assessment/scoring engine in ``core/routing`` and the per-workspace mode
+lookup on ``AppContext`` — and is therefore the ONLY file in
+``application/model_routing/`` that knows those concrete types exist.
+
+All engine imports are deferred into method bodies. Importing the routing stack
+pulls in Pydantic models and the on-disk assessment store, and the UI must be
+able to import this module during startup without paying that cost (the same
+lazy-wiring reason ``state.py::AppContext.routing`` gives).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from .routing_application_service import RoutingApplicationService
+from .routing_models import RouteEvaluation, RoutingMode, RoutingRequest
+
+logger = logging.getLogger("cowork_local.application.model_routing")
+
+
+class CoreRoutingEngine:
+    """:class:`RoutingDecisionPort` backed by ``core/routing/service.py``.
+
+    Translates in both directions: application DTOs in, and the engine's
+    ``RouteResult``/``SwitchDecision``/``TaskType`` flattened back out into a
+    :class:`RouteEvaluation`, so no ``core.routing`` type ever escapes into the
+    application service or the UI call sites.
+    """
+
+    def __init__(self, routing_service: Any) -> None:
+        self._routing_service = routing_service
+
+    def evaluate(self, request: RoutingRequest, mode: RoutingMode) -> RouteEvaluation:
+        """Rank candidates for this turn and report the engine's verdict."""
+        from ...core.routing.models import TaskType, candidate_key
+
+        result = self._routing_service.route(
+            request.surface,
+            request.prompt,
+            request.current_provider,
+            request.current_model,
+            # The engine only knows off/auto/manual; FALLBACK was already mapped
+            # to AUTO upstream so the value handed over here is always valid.
+            mode_override=mode.value,
+            required_capabilities=list(request.required_capabilities) or None,
+            task_type=self._parse_task_type(request.task_type, TaskType),
+        )
+
+        decision = result.decision
+        target = result.target()  # (provider, model_id) or None
+        current_key = (
+            candidate_key(request.current_provider, request.current_model)
+            if request.current_model
+            else ""
+        )
+        return RouteEvaluation(
+            task_type=self._task_type_value(result.task_type),
+            should_switch=bool(result.should_switch),
+            target_provider=target[0] if target else None,
+            target_model=target[1] if target else None,
+            score_gain=float(getattr(decision, "score_gain", 0.0) or 0.0),
+            reason=str(getattr(decision, "reason", "") or ""),
+            current_is_usable=self._current_is_usable(result, current_key),
+            decision=decision,
+        )
+
+    # -- translation helpers --------------------------------------------- #
+    @staticmethod
+    def _parse_task_type(raw: Optional[str], task_type_enum) -> Optional[Any]:
+        """Coerce a task-type string to the engine's enum.
+
+        ``None`` (the common case) means "let the engine classify the prompt".
+        An unrecognised string is also downgraded to ``None`` rather than
+        raising, so a stale value in a saved workspace cannot break a turn.
+        """
+        if raw is None:
+            return None
+        if isinstance(raw, task_type_enum):
+            return raw
+        try:
+            return task_type_enum(str(raw).strip().lower())
+        except ValueError:
+            logger.warning("routing: unknown task type %r — classifying from the prompt", raw)
+            return None
+
+    @staticmethod
+    def _task_type_value(task_type: Any) -> str:
+        """The plain string form of the engine's task type enum."""
+        return str(getattr(task_type, "value", task_type) or "")
+
+    @staticmethod
+    def _current_is_usable(result: Any, current_key: str) -> bool:
+        """Whether the currently selected model can still serve this task.
+
+        This is the signal FALLBACK mode acts on. A model is usable when the
+        ranking scored it above zero; ``rank_models`` already drops candidates
+        that are unavailable, lack a probe for this task type, or failed their
+        last probe, so "absent from the ranking" is precisely "cannot serve it".
+
+        With no ranking (routing off, or the engine's internal error path) or no
+        current model, we answer True: absence of evidence must not trigger a
+        surprise switch in a mode whose whole promise is not to surprise.
+        """
+        ranking = getattr(result, "ranking", None)
+        if ranking is None or not current_key:
+            return True
+        try:
+            return float(ranking.score_of(current_key)) > 0.0
+        except Exception:  # noqa: BLE001 — defensive: never fail a turn on telemetry-ish data
+            logger.debug("routing: could not score current model %r", current_key, exc_info=True)
+            return True
+
+
+class AppContextModeResolver:
+    """:class:`ModeResolver` backed by the active workspace's settings.
+
+    Reads through ``AppContext.project_routing_mode``, which already layers the
+    workspace override on top of the global default — so per-workspace routing
+    modes keep working unchanged now that the mode lookup moved out of the
+    widgets.
+    """
+
+    def __init__(self, ctx: Any) -> None:
+        self._ctx = ctx
+
+    def mode_for(self, surface: str) -> RoutingMode:
+        """Effective mode for ``surface`` in the active workspace."""
+        return RoutingMode.parse(self._ctx.project_routing_mode(surface))
+
+
+def build_routing_application_service(ctx: Any) -> RoutingApplicationService:
+    """The shared :class:`RoutingApplicationService` for this app context.
+
+    Cached on the context (like ``AppContext.routing()`` caches the engine) so
+    every surface talks to the same instance and a future stateful addition —
+    per-surface cool-down, switch history — is shared rather than duplicated per
+    widget. Falls back to a fresh instance if the context refuses attribute
+    assignment, which keeps tests using lightweight stand-ins working.
+    """
+    cached = getattr(ctx, "_routing_app_service", None)
+    if cached is not None:
+        return cached
+
+    service = RoutingApplicationService(
+        CoreRoutingEngine(ctx.routing()),
+        AppContextModeResolver(ctx),
+        # Read at call time: the user can change the confirm timeout in Settings
+        # between two turns and the next Manual dialog should honour it.
+        confirm_timeout_sec=lambda: float(
+            (ctx.config.routing or {}).get("confirm_timeout_sec", 60) or 60
+        ),
+    )
+    try:
+        ctx._routing_app_service = service
+    except Exception:  # noqa: BLE001 — read-only/slotted stand-ins stay supported
+        logger.debug("routing: could not cache the application service on the context", exc_info=True)
+    return service
+
+
+__all__ = [
+    "AppContextModeResolver",
+    "CoreRoutingEngine",
+    "build_routing_application_service",
+]

application/model_routing/routing_application_service.py

@@ -0,0 +1,236 @@
+"""The one place that decides how a turn is routed (R03-T03).
+
+Before this service, ``ui/chat_panel.py#L638``, ``ui/co4e_tab.py`` and
+``ui/folder_tab.py`` each carried their own copy of the same eight-step dance:
+clear last turn's override → read the surface's mode → bail on "off" → call the
+routing engine → check ``should_switch`` → resolve the target → show the Manual
+confirm dialog → publish the override and a status line. Three copies meant
+three chances to drift, and none of them could be tested without a Qt widget.
+
+The dance now lives here, once, in pure Python:
+
+* the routing engine is reached through :class:`RoutingDecisionPort`;
+* the surface's Off/Auto/Manual/Fallback mode through :class:`ModeResolver`;
+* the Manual-mode confirmation through a ``confirm`` callback supplied per call,
+  so the Qt dialog stays in the presentation layer where it belongs.
+
+Every failure path degrades to "keep the current model": a routing problem must
+never be the reason a user cannot send a message.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional, Protocol, runtime_checkable
+
+from .routing_models import (
+    RouteEvaluation,
+    RoutingMode,
+    RoutingOutcome,
+    RoutingRequest,
+)
+
+logger = logging.getLogger("cowork_local.application.model_routing")
+
+# Asks the user to approve a Manual-mode switch. Receives the underlying
+# decision object (for rendering) plus the timeout in seconds; returns True to
+# approve. Supplied by the caller so this module never imports a UI toolkit.
+ConfirmationCallback = Callable[[Any, float], bool]
+
+
+@runtime_checkable
+class RoutingDecisionPort(Protocol):
+    """The routing engine, as this service needs it.
+
+    Narrowed to a single method on purpose: the concrete engine
+    (``core/routing/service.py::RoutingService``) exposes assessment,
+    persistence and scheduling too, none of which a turn-time decision needs.
+    """
+
+    def evaluate(self, request: RoutingRequest, mode: RoutingMode) -> RouteEvaluation:
+        """Rank candidates for ``request`` and report whether to switch."""
+
+
+@runtime_checkable
+class ModeResolver(Protocol):
+    """Resolves the effective routing mode for a surface.
+
+    In the app this reads the active workspace's per-surface override with the
+    global default behind it (``AppContext.project_routing_mode``); in tests it
+    is a two-line stub.
+    """
+
+    def mode_for(self, surface: str) -> RoutingMode:
+        """Effective mode for ``surface``."""
+
+
+class RoutingApplicationService:
+    """Turn-time routing decisions for every chat surface."""
+
+    # Matches DEFAULT_CONFIG["routing"]["confirm_timeout_sec"]; used only when
+    # no timeout provider is wired, so a bare service is still usable in tests.
+    DEFAULT_CONFIRM_TIMEOUT_SEC = 60.0
+
+    def __init__(
+        self,
+        decision_port: RoutingDecisionPort,
+        mode_resolver: Optional[ModeResolver] = None,
+        *,
+        confirm_timeout_sec: Optional[Callable[[], float]] = None,
+    ) -> None:
+        self._decision_port = decision_port
+        self._mode_resolver = mode_resolver
+        # A callable rather than a number: the timeout lives in mutable config
+        # the user can change in Settings between two turns.
+        self._confirm_timeout_sec = confirm_timeout_sec
+
+    # -- public API ------------------------------------------------------ #
+    def resolve(
+        self,
+        request: RoutingRequest,
+        confirm: Optional[ConfirmationCallback] = None,
+    ) -> RoutingOutcome:
+        """Decide this turn's provider/model.
+
+        Returns a :class:`RoutingOutcome`; ``provider``/``model`` are ``None``
+        whenever the surface should keep its own selection. Never raises — an
+        unexpected failure is logged and reported as "keep current", because a
+        broken assessment store must not block chatting.
+        """
+        mode = request.mode or self._resolve_mode(request.surface)
+        try:
+            return self._resolve_unguarded(request, mode, confirm)
+        except Exception:  # noqa: BLE001 — routing must never break a turn
+            logger.exception("routing.resolve failed — keeping the current model")
+            return RoutingOutcome.keep_current(mode, reason="routing error — keeping current model")
+
+    def confirm_timeout(self) -> float:
+        """Seconds to wait for a Manual-mode confirmation.
+
+        Falls back to the built-in default when the provider is missing or
+        returns something unusable, so a corrupted config value cannot produce a
+        zero-second dialog that instantly declines every switch.
+        """
+        if self._confirm_timeout_sec is None:
+            return self.DEFAULT_CONFIRM_TIMEOUT_SEC
+        try:
+            value = float(self._confirm_timeout_sec())
+        except (TypeError, ValueError):
+            return self.DEFAULT_CONFIRM_TIMEOUT_SEC
+        return value if value > 0 else self.DEFAULT_CONFIRM_TIMEOUT_SEC
+
+    # -- internals ------------------------------------------------------- #
+    def _resolve_mode(self, surface: str) -> RoutingMode:
+        """The surface's configured mode, defaulting to OFF when unresolvable —
+        routing stays opt-in, so "we don't know" must mean "don't switch"."""
+        if self._mode_resolver is None:
+            return RoutingMode.OFF
+        try:
+            return RoutingMode.parse(self._mode_resolver.mode_for(surface))
+        except Exception:  # noqa: BLE001 — a config read must not break a turn
+            logger.exception("routing: could not resolve mode for surface %r", surface)
+            return RoutingMode.OFF
+
+    def _resolve_unguarded(
+        self,
+        request: RoutingRequest,
+        mode: RoutingMode,
+        confirm: Optional[ConfirmationCallback],
+    ) -> RoutingOutcome:
+        """The decision flow proper; :meth:`resolve` owns the safety net."""
+        # 1. Routing disabled, or nothing to classify -> keep the selection.
+        if mode is RoutingMode.OFF:
+            return RoutingOutcome.keep_current(mode, reason="routing off")
+        if not request.has_prompt:
+            return RoutingOutcome.keep_current(mode, reason="empty prompt — nothing to route")
+
+        # 2. Ask the engine. FALLBACK is evaluated with AUTO's ranking because
+        #    it needs the same candidate list; only the accept/reject rule below
+        #    differs, so the engine stays unaware of the extra mode.
+        engine_mode = RoutingMode.AUTO if mode is RoutingMode.FALLBACK else mode
+        evaluation = self._decision_port.evaluate(request, engine_mode)
+
+        # 3. Apply the mode's own accept rule to the engine's verdict.
+        if mode is RoutingMode.FALLBACK:
+            accepted, reason = self._fallback_verdict(evaluation)
+        else:
+            accepted, reason = evaluation.should_switch, evaluation.reason
+
+        if not accepted or not evaluation.has_target:
+            return RoutingOutcome.keep_current(
+                mode,
+                reason=reason or evaluation.reason,
+                task_type=evaluation.task_type,
+                decision=evaluation.decision,
+            )
+
+        # 4. Manual mode asks first; a decline or a timeout keeps the current
+        #    model (and is reported as such, so the surface can tell the two
+        #    cases apart from "nothing better was found").
+        if mode is RoutingMode.MANUAL and not self._approved(evaluation, confirm):
+            return RoutingOutcome.keep_current(
+                mode,
+                reason="switch declined by user or confirmation timed out",
+                task_type=evaluation.task_type,
+                declined=True,
+                decision=evaluation.decision,
+            )
+
+        # 5. Publish the override for THIS turn only. The provider falls back to
+        #    the request's current provider when the engine named a model but no
+        #    provider (same-provider switch).
+        return RoutingOutcome(
+            mode=mode,
+            switched=True,
+            provider=evaluation.target_provider or request.current_provider,
+            model=evaluation.target_model or "",
+            task_type=evaluation.task_type,
+            score_gain=evaluation.score_gain,
+            reason=reason or evaluation.reason,
+            decision=evaluation.decision,
+        )
+
+    @staticmethod
+    def _fallback_verdict(evaluation: RouteEvaluation) -> tuple:
+        """FALLBACK's accept rule: switch ONLY to rescue an unusable selection.
+
+        The user's pinned model wins as long as it can serve the turn, even when
+        a higher-scoring candidate exists — that is the whole point of the mode.
+        A switch happens only when the current model is not a usable candidate
+        (never assessed, marked unavailable, or its last probe failed) and the
+        engine has something to move to.
+        """
+        if evaluation.current_is_usable:
+            return False, "fallback mode — current model is healthy, keeping it"
+        if not evaluation.has_target:
+            return False, "fallback mode — current model unusable and no replacement available"
+        return True, "fallback mode — current model unavailable, switching to the best alternative"
+
+    def _approved(
+        self,
+        evaluation: RouteEvaluation,
+        confirm: Optional[ConfirmationCallback],
+    ) -> bool:
+        """Run the Manual-mode confirmation callback.
+
+        No callback means no way to ask, and silently switching in Manual mode
+        would violate the mode's contract — so a missing callback is treated as
+        "not approved". A callback that raises is treated the same way, since a
+        broken dialog must not auto-approve a model change.
+        """
+        if confirm is None:
+            logger.warning("routing: manual mode without a confirmation callback — keeping current model")
+            return False
+        try:
+            return bool(confirm(evaluation.decision, self.confirm_timeout()))
+        except Exception:  # noqa: BLE001
+            logger.exception("routing: confirmation callback failed — keeping current model")
+            return False
+
+
+__all__ = [
+    "ConfirmationCallback",
+    "ModeResolver",
+    "RoutingApplicationService",
+    "RoutingDecisionPort",
+]

application/model_routing/routing_models.py

@@ -0,0 +1,158 @@
+"""Pure-Python DTOs exchanged with :mod:`routing_application_service`.
+
+These types are the vocabulary the chat surfaces (Cowork chat, Co4E, AI-Edit)
+now speak instead of each re-deriving routing state from raw config lookups and
+``core/routing`` internals.
+
+Layer rules (``docs/architecture/ADR-001-layered-architecture.md``): application
+code is 100% pure Python. Nothing here imports PySide6, and nothing here imports
+``core.routing`` either — the concrete routing engine is reached only through
+the adapter in :mod:`core_routing_adapter`, which keeps this module trivially
+testable with plain fakes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Tuple
+
+
+class RoutingMode(str, Enum):
+    """The four routing behaviours a surface can be in (R03-T03).
+
+    ``OFF``/``AUTO``/``MANUAL`` map 1:1 onto the existing per-surface toggle and
+    onto ``core/routing/models.py::SwitchMode``. ``FALLBACK`` is new and
+    deliberately NOT an optimisation mode: it keeps whatever model the user
+    chose and only re-routes when that model cannot serve the turn, which is the
+    behaviour a resilience-minded workspace wants (never surprise me, but never
+    leave me stuck either).
+    """
+
+    OFF = "off"
+    AUTO = "auto"
+    MANUAL = "manual"
+    FALLBACK = "fallback"
+
+    @classmethod
+    def parse(cls, raw: Any, default: "RoutingMode" = None) -> "RoutingMode":
+        """Best-effort coercion from config/UI strings.
+
+        Routing must never break a turn, so an unrecognised value degrades to
+        ``default`` (``OFF`` unless told otherwise) instead of raising — the same
+        defensive posture ``config.routing_mode_for`` already takes.
+        """
+        fallback = default if default is not None else cls.OFF
+        if isinstance(raw, cls):
+            return raw
+        try:
+            return cls(str(raw or "").strip().lower())
+        except ValueError:
+            return fallback
+
+
+@dataclass(frozen=True)
+class RoutingRequest:
+    """Everything needed to decide how ONE turn should be routed.
+
+    Frozen: the request is captured from live UI state (the selected model, the
+    typed prompt) and then handed to code that may run on a worker thread. An
+    immutable snapshot means the user changing the model picker mid-turn cannot
+    retroactively alter the decision that was already made — the same rationale
+    behind R04's ``ConversationExecutionRequest``.
+    """
+
+    surface: str                       # "cowork" | "co4e" | "ai_edit" | ...
+    prompt: str                        # the user's text; drives task classification
+    current_provider: str              # provider the surface would use as-is
+    current_model: str = ""            # model the surface would use ("" = provider default)
+    mode: Optional[RoutingMode] = None  # explicit override; None -> resolve per surface
+    # Pre-classified task type ("coding", "qa", ...). AI-Edit always knows its
+    # turns are coding work, so it pins this and skips prompt classification.
+    task_type: Optional[str] = None
+    required_capabilities: Tuple[str, ...] = ()   # e.g. ("vision",)
+
+    @property
+    def has_prompt(self) -> bool:
+        """Whether there is anything to classify. An empty prompt cannot be
+        routed meaningfully, so every surface short-circuits on it."""
+        return bool((self.prompt or "").strip())
+
+
+@dataclass(frozen=True)
+class RouteEvaluation:
+    """A routing engine's verdict, normalised away from ``core/routing`` types.
+
+    The adapter flattens ``RouteResult``/``SwitchDecision`` into these plain
+    fields so the application service never touches Pydantic models or enums
+    owned by another layer. ``decision`` still carries the original object
+    because the Manual-mode confirm dialog renders its ``reason``.
+    """
+
+    task_type: str
+    should_switch: bool
+    target_provider: Optional[str] = None
+    target_model: Optional[str] = None
+    score_gain: float = 0.0
+    reason: str = ""
+    # False when the currently selected model is not a usable candidate for this
+    # task (unranked, unavailable, or failed its last probe) — the single signal
+    # FALLBACK mode acts on.
+    current_is_usable: bool = True
+    decision: Any = None               # original SwitchDecision, for the UI dialog
+
+    @property
+    def has_target(self) -> bool:
+        """A switch is only actionable when the engine named a model to move to."""
+        return bool(self.target_model or self.target_provider)
+
+
+@dataclass(frozen=True)
+class RoutingOutcome:
+    """What the calling surface should actually do for this turn.
+
+    A surface needs exactly three things from routing — "which provider/model do
+    I build?", "do I tell the user?" and "was I told to stand down?" — so those
+    are the fields here, and nothing else. ``provider``/``model`` are ``None``
+    when the surface should keep its own selection untouched.
+    """
+
+    mode: RoutingMode
+    switched: bool = False
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    task_type: str = ""
+    score_gain: float = 0.0
+    reason: str = ""
+    # True when Manual mode proposed a switch and the user declined or the
+    # confirmation timed out. Distinct from "no switch proposed" so a surface
+    # can tell "routing had nothing to offer" from "the user said no".
+    declined: bool = False
+    decision: Any = field(default=None, repr=False)
+
+    @property
+    def should_notify(self) -> bool:
+        """Whether the surface should post the "switched model" status bubble.
+        Only an executed switch is worth interrupting the transcript for."""
+        return self.switched
+
+    @classmethod
+    def keep_current(
+        cls,
+        mode: RoutingMode,
+        *,
+        reason: str = "",
+        task_type: str = "",
+        declined: bool = False,
+        decision: Any = None,
+    ) -> "RoutingOutcome":
+        """The no-change outcome — the single constructor for every path that
+        leaves the surface's own model selection in place (routing off, empty
+        prompt, no better candidate, user declined, internal error)."""
+        return cls(
+            mode=mode, switched=False, provider=None, model=None,
+            task_type=task_type, reason=reason, declined=declined, decision=decision,
+        )
+
+
+__all__ = ["RoutingMode", "RoutingRequest", "RouteEvaluation", "RoutingOutcome"]

application/monitoring/__init__.py

@@ -0,0 +1 @@
+"""Application monitoring package: Monitoring query service for audit and metrics."""

application/scheduling/__init__.py

@@ -0,0 +1 @@
+"""Application scheduling package: TaskApplicationService and AI task planning."""

application/settings/__init__.py

@@ -0,0 +1 @@
+"""Application settings package: Settings application service."""

application/workflows/__init__.py

@@ -0,0 +1 @@
+"""Application workflows package: Co4E graph execution orchestration."""

application/workflows/co4e_workflow_service.py

@@ -0,0 +1,377 @@
+"""``Co4EWorkflowService`` — nửa "hành vi" tách ra từ ``Co4ERunManager`` cũ.
+
+Bối cảnh: ``core/co4e_run_manager.py::Co4ERunManager`` là một ``QObject`` gộp
+chung dữ liệu run (nay là ``domain/workflows/run_record.py::RunRecord``), logic
+chạy job trên ``AgentWorker``/``QThread``, và logic đọc/ghi lịch sử ra đĩa. File
+này là phần còn lại sau khi tách DTO: quản lý vòng đời nhiều run cùng lúc, các
+hook nhận sự kiện từ worker, và lưu/nạp lịch sử — nhưng THUẦN PYTHON, không kế
+thừa ``QObject`` và không tự dựng ``QThread`` (``application/`` cấm PySide6).
+
+Hai điều thay ``Signal`` cũ:
+  * ``changed = Signal()`` -> danh sách callback ``self._changed_callbacks`` +
+    ``on_changed(cb)`` để đăng ký; mọi chỗ code cũ gọi ``self.changed.emit()``
+    nay gọi ``self._emit_changed()``, gọi callback theo ĐÚNG thứ tự đã đăng ký.
+  * ``event = Signal(str, dict)`` -> ``self._event_callbacks`` + ``on_event(cb)``,
+    tương tự, thay ``self.event.emit(rid, ev)`` bằng ``self._emit_event(rid, ev)``.
+  * ``self.changed.connect(self._save_history)`` (lớp cũ tự nối signal của
+    chính nó vào slot riêng, trong ``__init__``) -> ở đây gọi thẳng
+    ``self._save_history()`` làm bước ĐẦU TIÊN bên trong ``_emit_changed()``,
+    trước khi chạy các callback đã đăng ký từ bên ngoài. Chọn cách "gọi thẳng"
+    (thay vì "đăng ký như callback đầu tiên") vì nó khớp với thứ tự nối cũ
+    (``_save_history`` luôn được nối sớm nhất trong ``__init__`` nên luôn chạy
+    trước mọi slot ngoài nối sau) mà không cần một danh sách callback nội bộ
+    riêng chỉ để chứa đúng một phần tử cố định.
+
+``start()`` KHÔNG tự tạo ``AgentWorker``/``QThread`` — nó nhận một ``runner``
+(``WorkflowRunner`` Protocol, mặc định ``None``) tiêm qua constructor. Adapter
+Qt thật (bọc ``AgentWorker`` — xem ``core/worker.py``) là việc của widget ở
+``presentation/``, không viết ở đây; test dùng fake chạy đồng bộ
+(``tests/fakes/fake_co4e_workflow_service.py`` hoặc fake cục bộ trong
+``tests/test_co4e_workflow_service.py``).
+
+KHÔNG xoá/sửa ``core/co4e_run_manager.py`` — lớp cũ tiếp tục chạy song song
+cho tới khi widget Co4E Studio thật (``ui/co4e_tab.py``) chuyển hẳn sang dùng
+service này.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Protocol, Set
+
+from ...core.co4e import CO4E_DIR, STEP_DONE, STEP_ERROR, STEP_PLANNED, Workflow, slugify, workflow_to_dict
+from ...domain.workflows.run_record import RunRecord
+
+_TERMINAL_NODE = {STEP_DONE, STEP_ERROR, STEP_PLANNED}
+_HISTORY_CAP = 500          # giữ N run gần nhất trên đĩa
+
+
+def _now_str() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M")
+
+
+def _current_user() -> str:
+    """Best-effort creator name for a run (signed-in MS365 identity -> OS user)."""
+    return os.environ.get("USERNAME") or os.environ.get("USER") or "you"
+
+
+# ---- ports (Protocol) — thay QThread thật bằng thứ tiêm được ---------------
+class RunnerJob(Protocol):
+    """Bề mặt tối thiểu mà job workflow cần từ 'worker' của nó.
+
+    Tương ứng ``AgentWorker.emit_event``/``AgentWorker.is_cancelled`` cũ
+    (``core/worker.py``) — giữ nguyên chữ ký đó để hàm job bên trong
+    ``co4e_runner.run_workflow`` không phải đổi khi runner đứng sau là
+    ``AgentWorker``/``QThread`` thật (adapter ở presentation/) hay là fake
+    đồng bộ trong test.
+    """
+
+    def emit_event(self, ev: dict) -> None: ...
+    def is_cancelled(self) -> bool: ...
+
+
+class RunWorkerHandle(Protocol):
+    """Điều khiển một job đang chạy nền — tương ứng phần
+    ``AgentWorker.request_stop()`` cũ mà ``Co4ERunManager.stop()`` gọi."""
+
+    def request_stop(self) -> None: ...
+
+
+class WorkflowRunner(Protocol):
+    """Cổng chạy một job nền, tiêm qua constructor ``Co4EWorkflowService``.
+
+    Thay cho việc service tự ``AgentWorker(job); worker.start()`` (cần
+    ``QThread`` -> cấm ở ``application/``). Bên gọi ``start()`` truyền vào
+    ``job`` với đúng chữ ký cũ (``job(worker) -> Optional[dict]``); runner chịu
+    trách nhiệm chạy nó (nền thật hay đồng bộ) và gọi lại ba callback tương ứng
+    ba signal cũ của ``AgentWorker`` (``event``/``finished_ok``/``failed``).
+    """
+
+    def start(self, run_id: str, job: Callable[[RunnerJob], Optional[dict]],
+              on_event: Callable[[dict], None],
+              on_finished: Callable[[Optional[dict]], None],
+              on_failed: Callable[[str], None]) -> RunWorkerHandle: ...
+
+
+class Co4EWorkflowService:
+    """Tầng application: vòng đời nhiều run Co4E cùng lúc, thuần Python.
+
+    Vai trò: đây là nơi ``build_co4e_tab(ctx, workflow_service)``
+    (``presentation/co4e/co4e_tab.py``) sẽ lấy ``workflow_service`` thật một
+    khi widget Co4E Studio được lắp lại để dùng nó — hiện widget thật
+    (``ui/co4e_tab.py``) vẫn dùng ``Co4ERunManager`` cũ song song.
+    """
+
+    def __init__(self, ctx, *, history_path: Optional[Path] = None,
+                 runner: Optional[WorkflowRunner] = None):
+        self.ctx = ctx
+        self._runs: Dict[str, RunRecord] = {}
+        self._worker_handles: Dict[str, RunWorkerHandle] = {}
+        self._seq = 0
+        self._output_root: Optional[Path] = None   # thư mục output co4e của workspace đang chọn
+        self._project_id: str = ""                 # workspace đang chọn — Flow Status lọc theo no
+        self._runner = runner
+        # DTO domain khong duoc cham dia (xem domain/workflows/run_record.py),
+        # nen viec doc/ghi file lich su nam o day, tang application.
+        self._history_path_value = (
+            Path(history_path) if history_path is not None else (CO4E_DIR / "run_history.json")
+        )
+        self._changed_callbacks: List[Callable[[], None]] = []
+        self._event_callbacks: List[Callable[[str, dict], None]] = []
+        self._load_history()          # khoi phuc lich su cu de Flow Status
+                                       # giu du lich su qua cac lan restart
+
+    # ---- callback thay Signal ---------------------------------------------
+    def on_changed(self, cb: Callable[[], None]) -> None:
+        self._changed_callbacks.append(cb)
+
+    def on_event(self, cb: Callable[[str, dict], None]) -> None:
+        self._event_callbacks.append(cb)
+
+    def _emit_changed(self) -> None:
+        self._save_history()          # xem docstring dau file: giu dung thu tu ban Qt cu
+        for cb in self._changed_callbacks:
+            cb()
+
+    def _emit_event(self, run_id: str, ev) -> None:
+        for cb in self._event_callbacks:
+            cb(run_id, ev)
+
+    # ---- persistence --------------------------------------------------
+    # Doc/ghi thu cong (json.loads/write_text + tmp.replace), KHONG dung
+    # AtomicJsonFile — ban dau file nay dung AtomicJsonFile.read(), nhung
+    # review phat hien no doi hanh vi that so voi Co4ERunManager cu: gap
+    # JSON hong, AtomicJsonFile.read() ĐOI TEN file hong thanh
+    # "<ten>.bad-<timestamp>" (quarantine) roi moi tra ve mac dinh, trong
+    # khi ban cu chi bat loi va ĐE NGUYEN file hong tai cho, khong dong gi
+    # vao no. Day la mot thay doi quan sat duoc tren dia ma khong test nao
+    # khoa lai va khong co comment bao truoc — Lam (N3) da quyet 24/08:
+    # GIU HANH VI CU nguyen van (khong quarantine), vi day la buoc tach
+    # chi duoc phep doi hanh vi khi da noi ra ro rang va co lưới an toan,
+    # khong phai luc nay.
+    def _load_history(self) -> None:
+        try:
+            data = json.loads(self._history_path_value.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return
+        max_seq = 0
+        for rec in data.get("runs", []):
+            try:
+                record = RunRecord.from_dict(rec)
+            except Exception:
+                continue
+            if not record.id:
+                continue
+            self._runs[record.id] = record
+            if record.id.startswith("run") and record.id[3:].isdigit():
+                max_seq = max(max_seq, int(record.id[3:]))
+        self._seq = max_seq           # tranh sinh id trung voi lich su
+
+    def _save_history(self) -> None:
+        runs = list(self._runs.values())[-_HISTORY_CAP:]
+        payload = {"runs": [r.to_dict() for r in runs]}
+        try:
+            self._history_path_value.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._history_path_value.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2),
+                           encoding="utf-8")
+            tmp.replace(self._history_path_value)   # atomic — khong bao gio de lai file ghi do dang
+        except OSError:
+            # Giu dung hanh vi cu (core/co4e_run_manager.py::_save_history):
+            # mot lan luu that bai (day dia, mat quyen...) KHONG duoc phep
+            # chan luong goi cua moi hook (_on_event/_on_finished/_on_failed)
+            # dang di qua _emit_changed(). Bo try/except nay se lam mot loi
+            # ghi dia lam vo ca luot xu ly su kien dang chay, chi vi lich su
+            # khong luu duoc lan nay -- nguoi dung van thay Flow Status dung
+            # trong phien hien tai, chi la ban ghi tren dia lui lai mot buoc.
+            pass
+
+    # ---- lifecycle ----------------------------------------------------
+    def _next_id(self) -> str:
+        self._seq += 1
+        return f"run{self._seq}"
+
+    def start(self, wf: Workflow, *, skill_map: Optional[Dict[str, str]] = None,
+              plan_mode: bool = False, only_nodes: Optional[set] = None,
+              seed_outputs: Optional[Dict[str, str]] = None,
+              manual: bool = False, label: Optional[str] = None) -> str:
+        """Đăng ký một run mới và giao job cho ``self._runner`` (nếu có).
+
+        Không tự thực thi AI thật ở đây: khi ``self._runner`` là ``None``
+        (mặc định), run được ghi nhận nhưng không job nào được giao đi — dùng
+        cho test/khi chưa lắp adapter Qt thật.
+        """
+        run_id = self._next_id()
+        total = len(only_nodes) if only_nodes else len(wf.nodes)
+        record = RunRecord(run_id, wf.id, label or wf.name, total, plan_mode, manual,
+                            created_by=_current_user(), created_at=_now_str(),
+                            project_id=self._project_id)
+        # workflow_to_dict() tu dung dataclasses.asdict() de dung ca cay (node,
+        # step, sub-agent) -> ban than no da la mot "deep copy" sang dict moi,
+        # khong con giu tham chieu toi wf.nodes/wf.edges song. Vi vay KHONG can
+        # deepcopy(wf) truoc nhu ban Qt cu (RunHandle.wf giu nguyen doi tuong
+        # Workflow) -- xem doc string dau file domain/workflows/run_record.py
+        # ve ly do snapshot o day la dict tho chu khong phai doi tuong.
+        record.wf = workflow_to_dict(wf)
+        nodes = list(wf.nodes)
+        edges = list(wf.edges)
+        out_dir = self._out_dir(wf)
+        record.out_dir = str(out_dir)
+        ctx = self.ctx
+        sk = dict(skill_map or {})
+        only: Optional[Set[str]] = set(only_nodes) if only_nodes else None
+        seed = dict(seed_outputs or {})
+        run_label = record.name
+        self._runs[run_id] = record
+
+        if self._runner is not None:
+            def job(worker: RunnerJob):
+                from ...core import co4e_runner
+                return co4e_runner.run_workflow(
+                    ctx, nodes, edges, out_dir, worker.emit_event, worker.is_cancelled,
+                    plan_mode=plan_mode, skill_map=sk, only_nodes=only, seed_outputs=seed,
+                    usage_label=run_label)
+
+            self._worker_handles[run_id] = self._runner.start(
+                run_id, job,
+                on_event=lambda ev, rid=run_id: self._on_event(rid, ev),
+                on_finished=lambda _r=None, rid=run_id: self._on_finished(rid),
+                on_failed=lambda e, rid=run_id: self._on_failed(rid, e),
+            )
+        self._emit_changed()
+        return run_id
+
+    # ---- worker callbacks (goi tu runner, thay slot Qt cu) -----------------
+    def _on_event(self, run_id: str, ev) -> None:
+        record = self._runs.get(run_id)
+        if record is not None and isinstance(ev, dict):
+            t = ev.get("type")
+            if t == "node_status":
+                record.node_status[ev.get("node_id")] = ev.get("status")
+                record.done = sum(1 for s in record.node_status.values() if s in _TERMINAL_NODE)
+                self._emit_changed()
+            elif t == "run_done":
+                if record.status == "running":
+                    record.status = "done" if ev.get("ok", True) else "error"
+                self._emit_changed()
+        # quirk co y giu nguyen (xem test_on_event_unknown_run_id... trong ca
+        # test cu lan test moi): re-emit VO DIEU KIEN, ke ca run_id la hoac ev
+        # khong phai dict/None -- khac _on_finished/_on_failed la no-op hoan
+        # toan khi run_id la.
+        #
+        # Khac biet CO CHU Y so voi ban Qt cu: Signal(str, dict) cua PySide6 ep
+        # ev=None thanh {} khi giao cho slot (tac dung phu cua kieu Signal khai
+        # bao cung). O day khong con Signal nen callback nhan DUNG gia tri ev
+        # goc (None neu goi voi None) -- khong gia lap lai viec ep kieu do vi
+        # no la tac dung phu cua Qt, khong phai quy tac nghiep vu can giu.
+        self._emit_event(run_id, ev)
+
+    def _on_finished(self, run_id: str) -> None:
+        record = self._runs.get(run_id)
+        if record is not None and record.status == "running":
+            # job returned without a run_done event (shouldn't happen) — settle it
+            record.status = "done"
+            self._emit_changed()
+
+    def _on_failed(self, run_id: str, err: str) -> None:
+        record = self._runs.get(run_id)
+        if record is not None:
+            record.status = "error"
+            record.error = str(err)
+            self._emit_event(run_id, {"type": "run_error", "error": str(err)})
+            self._emit_changed()
+
+    # ---- control --------------------------------------------------------
+    def stop(self, run_id: str) -> None:
+        record = self._runs.get(run_id)
+        worker = self._worker_handles.get(run_id)
+        if record is not None and worker is not None and record.running:
+            worker.request_stop()
+            record.status = "stopped"
+            self._emit_changed()
+
+    def stop_all(self) -> None:
+        # Only the CURRENT workspace's runs (Flow Status is per-project).
+        for run_id in [r for r, rec in self._runs.items() if self._belongs(rec)]:
+            self.stop(run_id)
+
+    def rename(self, run_id: str, new_name: str) -> None:
+        """Rename a run in the Flow Status history (and its kept workflow snapshot),
+        then persist + refresh views. No-op on a blank name / unknown run."""
+        record = self._runs.get(run_id)
+        new_name = (new_name or "").strip()
+        if record is None or not new_name or new_name == record.name:
+            return
+        record.name = new_name
+        # DTO doi: RunHandle.wf cu la doi tuong Workflow (gan record.wf.name),
+        # RunRecord.wf o day la dict tho (xem domain/workflows/run_record.py)
+        # nen doi truc tiep khoa "name" cua dict thay vi thuoc tinh doi tuong.
+        if record.wf is not None:
+            record.wf["name"] = new_name
+        self._emit_changed()
+
+    def remove(self, run_id: str) -> None:
+        record = self._runs.get(run_id)
+        if record is not None and record.running:
+            self.stop(run_id)
+        self._runs.pop(run_id, None)
+        self._worker_handles.pop(run_id, None)
+        self._emit_changed()
+
+    def clear_finished(self) -> None:
+        # Only clear finished runs of the CURRENT workspace.
+        for run_id in [r for r, rec in self._runs.items() if not rec.running and self._belongs(rec)]:
+            self._runs.pop(run_id, None)
+            self._worker_handles.pop(run_id, None)
+        self._emit_changed()
+
+    # ---- queries ----------------------------------------------------------
+    def _belongs(self, r: RunRecord) -> bool:
+        """Whether a run belongs to the currently-selected workspace."""
+        return getattr(r, "project_id", "") == self._project_id
+
+    def runs(self) -> List[RunRecord]:
+        """Runs of the CURRENT workspace only — Flow Status is per-project."""
+        return [r for r in self._runs.values() if self._belongs(r)]
+
+    def all_runs(self) -> List[RunRecord]:
+        """Every tracked run across all workspaces (background tracking)."""
+        return list(self._runs.values())
+
+    def get(self, run_id: str) -> Optional[RunRecord]:
+        return self._runs.get(run_id)
+
+    def active_count(self) -> int:
+        return sum(1 for r in self._runs.values() if r.running and self._belongs(r))
+
+    def set_current_project(self, project_id: str) -> None:
+        """Filter Flow Status (and new runs) to this workspace. Runs started while
+        this is set are tagged with it; the Runs view shows only matching runs."""
+        pid = project_id or ""
+        if pid != self._project_id:
+            self._project_id = pid
+            self._emit_changed()          # re-render Flow Status for the new workspace
+
+    def set_output_root(self, root: Optional[Path]) -> None:
+        """Point flow outputs at the SELECTED workspace's co4e folder (set by the
+        Co4E tab when a project is chosen). ``None`` → fall back to the global
+        Cowork output dir."""
+        self._output_root = Path(root) if root else None
+
+    def _out_dir(self, wf: Workflow) -> Path:
+        # Flow deliverables are written into the SELECTED workspace (the active
+        # project's folder) so they land where the user works with files (Folder
+        # tab), not in the config/install folder. One subfolder per flow keeps
+        # runs tidy. Falls back to the global Cowork output dir when no workspace
+        # is selected.
+        base = self._output_root
+        if base is None:
+            try:
+                base = self.ctx.config.cowork_output_dir() / "co4e"
+            except Exception:  # noqa: BLE001 - fall back to the config dir if unavailable
+                base = CO4E_DIR / "runs" / "co4e"
+        d = Path(base) / slugify(wf.name or "flow")
+        d.mkdir(parents=True, exist_ok=True)
+        return d

application/workspaces/__init__.py

@@ -0,0 +1 @@
+"""Application workspaces package: File workspace and AI file editor services."""

config.py

@@ -105,8 +105,7 @@ DEFAULT_CONFIG: Dict[str, Any] = {
         # sandboxes agent-run shell commands) — reading a URL for info is safe and
         # useful, so this defaults ON. Toggle in Settings → Security.
         "allow_url_fetch": True,
-        # Set with COWORK_SANDBOX_PASSWORD. Never ship a shared unlock secret.
-        "sandbox_pw": "",
+        "sandbox_pw": "",                  # set through COWORK_SANDBOX_PASSWORD
         "rulebase_path": "",               # custom RULEBASE.md — attached to every agent execution
     },
     # Legacy generic-MCP-server list. MERGED into ext_connectors["other"] as of
@@ -174,8 +173,7 @@ DEFAULT_CONFIG: Dict[str, Any] = {
     # Microsoft. Real Outlook/Teams/OneDrive/SharePoint access still requires a
     # proper OAuth sign-in (not implemented yet) using tenant_id/client_id below.
     "ms365": {
-        # Set with COWORK_MS365_UNLOCK_CODE. Never ship a shared unlock secret.
-        "unlock_code": "",
+        "unlock_code": "",                # set through COWORK_MS365_UNLOCK_CODE
         "unlocked": False,           # runtime-only — never persisted as True, see save()
         # Auto-connect MS365/OneDrive/SharePoint: the built-in MS365 MCP server
         # launches automatically once the user is signed in (OAuth tenant/client
@@ -557,19 +555,26 @@ class AppConfig:
             d["surface_modes"].setdefault(surface, "")
         return d
 
-    def routing_mode_for(self, surface: str) -> str:
-        """Effective Off/Auto/Manual mode for a chat surface.
+    # The routing modes a surface may be in. "fallback" joined the set in
+    # R03-T03 (keep the selected model; re-route only when it cannot serve the
+    # turn) — see application/model_routing/routing_models.py::RoutingMode,
+    # which is the authority on what each mode means.
+    ROUTING_MODES = ("off", "auto", "manual", "fallback")
 
-        A per-surface override ("auto"/"manual"/"off") wins; an empty override
-        falls back to the global ``switch_mode``."""
+    def routing_mode_for(self, surface: str) -> str:
+        """Effective Off/Auto/Manual/Fallback mode for a chat surface.
+
+        A per-surface override wins; an empty override falls back to the global
+        ``switch_mode``. Anything unrecognised degrades to "off" so routing
+        stays opt-in even with a hand-edited config."""
         routing = self.routing
         override = (routing.get("surface_modes", {}) or {}).get(surface, "")
         mode = override or routing.get("switch_mode", "off")
-        return mode if mode in ("off", "auto", "manual") else "off"
+        return mode if mode in self.ROUTING_MODES else "off"
 
     def set_routing_mode_for(self, surface: str, mode: str) -> None:
-        """Persist a chat surface's Off/Auto/Manual toggle selection."""
-        mode = mode if mode in ("off", "auto", "manual") else "off"
+        """Persist a chat surface's routing toggle selection."""
+        mode = mode if mode in self.ROUTING_MODES else "off"
         self.routing.setdefault("surface_modes", {})[surface] = mode
         self.save()
 

core/task_executors.py

@@ -2,7 +2,9 @@
 
 ``execute_task`` dispatches by ``task_type`` to the app's existing engines:
 
-- ``cowork``     → ``chat_agent.run_cowork``  (documents/answers, real files)
+- ``cowork``     → ``ConversationApplicationService`` (documents/answers, real
+                   files) — the same turn engine the interactive Cowork chat
+                   runs on since R04-T05
 - ``co4e_code``  → ``code_agent.run_code``    (code agent with file/command tools)
 - ``script``     → local subprocess with a timeout
 - ``flow``       → the task's own simple step list, run sequentially, each
@@ -162,6 +164,30 @@ _TIMEOUT_NOTICE_TMPL = (
 )
 
 
+_UNATTENDED_PREFIX = (
+    "This runs unattended (Schedule Task) — no one is watching live. Use "
+    "update_plan to track your steps and keep it accurate: mark a step "
+    "'error' (not silently skip it) if it genuinely can't be completed."
+)
+
+
+def _unattended_prompt(prompt: str, *, skill_text: str = "",
+                       agent_instructions: str = "") -> str:
+    """Assemble the user message an unattended run sends.
+
+    The order is load-bearing and used to be encoded as three successive
+    rebindings of ``prompt``, each prepending its own block: the plan reminder
+    must lead (it is the instruction that keeps a run without a human watching
+    honest), then the chosen skill's rules, then the Admin agent's persona, and
+    the task's own words last. Routing it through ``combine_instructions`` keeps
+    that order in one readable expression and drops the absent blocks instead of
+    leaving blank lines behind.
+    """
+    from ..application.conversations.turn_runtime import combine_instructions
+
+    return combine_instructions(_UNATTENDED_PREFIX, skill_text, agent_instructions, prompt)
+
+
 def _cancel_with_timeout(cancel: CancelFn, timeout_sec: Optional[int]) -> Tuple[CancelFn, Callable[[], bool]]:
     """Wrap ``cancel`` so it also fires once ``timeout_sec`` of wall-clock time
     elapses. ``timed_out()`` tells the caller whether THAT is why it stopped
@@ -218,36 +244,29 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
     # default, see state.build_provider_for). A legacy Admin-agent preset
     # (task.admin_agent_id), if still set on an older task, keeps working and
     # takes precedence — it pins the provider/model AND prepends instructions.
+    agent_instructions = ""
     if admin_agent is not None:
         from .admin_agents import build_agent_provider
 
         provider = build_agent_provider(ctx, admin_agent)
         agent_instructions = admin_agent.effective_prompt()
-        if agent_instructions:
-            prompt = f"{agent_instructions}\n\n{prompt}"
     elif provider_name or model:
         # An explicit per-task provider/model override.
         provider = ctx.build_provider_for(provider_name or None, model or None)
     else:
         # Neither overridden → the machine's own Settings default, exactly as before.
         provider = ctx.build_active_provider()
-    # A chosen skill's instructions are prepended so this unattended run follows
+    # A chosen skill's instructions are applied so this unattended run follows
     # them, mirroring how the interactive chat applies /skill.
+    skill_text = ""
     if skill_slug:
         from .skills import skill_prefix_for
 
         skill_text = skill_prefix_for(skill_slug)
-        if skill_text:
-            prompt = f"{skill_text}\n\n{prompt}"
-    # This is an UNATTENDED run (no human watching to catch a half-finished
-    # job) — push the agent to actually use the Plan checklist so completion
-    # can be verified afterward, instead of just trusting "no exception".
-    prompt = (
-        "This runs unattended (Schedule Task) — no one is watching live. Use "
-        "update_plan to track your steps and keep it accurate: mark a step "
-        "'error' (not silently skip it) if it genuinely can't be completed.\n\n"
-        f"{prompt}"
-    )
+    # Assemble reminder + skill + persona + the task's own words in one place
+    # (see _unattended_prompt for why that order matters).
+    prompt = _unattended_prompt(prompt, skill_text=skill_text,
+                                agent_instructions=agent_instructions)
     messages = [{"role": "user", "content": prompt}]
     session_id = new_session_id()
     project_id = project.project_id if project is not None else ""
@@ -273,10 +292,41 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
     watched_cancel, timed_out = _cancel_with_timeout(cancel, timeout_sec)
     try:
         if task_type == "cowork":
-            from .chat_agent import run_cowork
-            run_cowork(provider, messages, out_dir, emit_and_autosave, watched_cancel,
-                      security_config=ctx.config, agent_role=agent_roles.TASK,
-                      project_context=project_context)
+            # R04-T05: the unattended run shares the interactive turn engine
+            # instead of calling run_cowork itself, so there is exactly one place
+            # where a turn's lifecycle is defined. Everything unattended-specific
+            # stays here (the plan reminder above, the History autosave in
+            # emit_and_autosave, the timeout notice below).
+            from ..application.conversations.core_runtime_adapter import (
+                build_cowork_conversation_service,
+                legacy_event_sink,
+            )
+            from ..domain.agents.conversation_execution_request import (
+                ConversationExecutionRequest,
+            )
+
+            # No extra_tools/extra_executor and no permission gate: a scheduled
+            # run gets no MCP connectors and nobody is there to approve a
+            # command, which is exactly what run_cowork was called with.
+            service = build_cowork_conversation_service(
+                provider, out_dir, emit_and_autosave, title=title,
+                project_context=project_context, security_config=ctx.config,
+                agent_role=agent_roles.TASK,
+            )
+            request = ConversationExecutionRequest(
+                # The artifact folder is named by the run id, which identifies
+                # this attempt in the audit log.
+                turn_id=out_dir.name or session_id, session_id=session_id,
+                surface="task", title=title, project_id=project_id,
+                prompt=prompt, output_dir=out_dir,
+                agent_role=agent_roles.TASK, unattended=True,
+                timeout_sec=timeout_sec,
+            )
+            # ``messages`` is handed over so the History autosave in
+            # emit_and_autosave (and the final save in the finally block below)
+            # keep reading the live conversation as it grows.
+            service.execute(request, legacy_event_sink(emit_and_autosave),
+                            cancel=watched_cancel, messages=messages)
         else:
             from .code_agent import run_code
             limits, block_network = agent_security.sandbox_settings(ctx.config)

core/usage_tracker.py

@@ -49,6 +49,18 @@ def set_context(source: str, label: str = "") -> None:
     _local.label = label
 
 
+def current_context() -> tuple:
+    """The ``(source, label)`` currently tagged on THIS thread.
+
+    Public counterpart to :func:`set_context`, added for
+    ``infrastructure/telemetry/usage_sink.py``: a subscriber that needs to
+    attribute one event to a different surface must be able to save the
+    caller's context and put it back afterwards, instead of leaving the worker
+    thread permanently retagged.
+    """
+    return getattr(_local, "source", "") or "", getattr(_local, "label", "") or ""
+
+
 # ---- per-thread usage accumulator -----------------------------------------
 # A step/run that wants to know its OWN token/cost (not the all-time file total)
 # calls begin_accumulation(), reads accumulated() before/after a unit of work,

docs/architecture.html

@@ -0,0 +1,327 @@
+<!doctype html>
+<html lang="vi" data-theme="auto">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Cấu trúc hệ thống · Cowork Local</title>
+<style>
+  :root{
+    --bg:#f6f7f9; --surface:#ffffff; --surface-2:#eef1f4; --border:#dbe0e7;
+    --ink:#131a22; --ink-2:#4b5663; --ink-3:#7c8794;
+    --accent:#0e7c86; --accent-ink:#0a5b63; --accent-soft:#e2f2f2;
+    --ok:#157f4a; --warn:#9a5a0e; --crit:#b5322c;
+    --ok-soft:#e4f4ea; --warn-soft:#f8efdd; --crit-soft:#f7e5e3;
+    --mono-bg:#eef2f6; --shadow:0 1px 2px rgba(16,24,32,.06),0 8px 24px -12px rgba(16,24,32,.18);
+    --font-display:"Segoe UI Variable Display","Segoe UI Semibold","Segoe UI",system-ui,-apple-system,sans-serif;
+    --font-body:"Segoe UI Variable Text","Segoe UI",system-ui,-apple-system,sans-serif;
+    --font-mono:"Cascadia Code","Cascadia Mono",Consolas,"SF Mono",ui-monospace,monospace;
+    --maxw:920px;
+  }
+  @media (prefers-color-scheme:dark){
+    :root{
+      --bg:#0d1218; --surface:#141c25; --surface-2:#1b2530; --border:#28343f;
+      --ink:#e7edf4; --ink-2:#a2b2c2; --ink-3:#6c7d8e;
+      --accent:#46cfc8; --accent-ink:#8fe9e3; --accent-soft:#14312f;
+      --ok:#47c97e; --warn:#e0a33a; --crit:#f0726b;
+      --ok-soft:#12281c; --warn-soft:#2c2410; --crit-soft:#2e1614;
+      --mono-bg:#0f1720; --shadow:0 1px 2px rgba(0,0,0,.4),0 10px 30px -16px rgba(0,0,0,.7);
+    }
+  }
+  :root[data-theme="light"]{
+    --bg:#f6f7f9; --surface:#ffffff; --surface-2:#eef1f4; --border:#dbe0e7;
+    --ink:#131a22; --ink-2:#4b5663; --ink-3:#7c8794;
+    --accent:#0e7c86; --accent-ink:#0a5b63; --accent-soft:#e2f2f2;
+    --ok:#157f4a; --warn:#9a5a0e; --crit:#b5322c;
+    --ok-soft:#e4f4ea; --warn-soft:#f8efdd; --crit-soft:#f7e5e3; --mono-bg:#eef2f6;
+    --shadow:0 1px 2px rgba(16,24,32,.06),0 8px 24px -12px rgba(16,24,32,.18);
+  }
+  :root[data-theme="dark"]{
+    --bg:#0d1218; --surface:#141c25; --surface-2:#1b2530; --border:#28343f;
+    --ink:#e7edf4; --ink-2:#a2b2c2; --ink-3:#6c7d8e;
+    --accent:#46cfc8; --accent-ink:#8fe9e3; --accent-soft:#14312f;
+    --ok:#47c97e; --warn:#e0a33a; --crit:#f0726b;
+    --ok-soft:#12281c; --warn-soft:#2c2410; --crit-soft:#2e1614; --mono-bg:#0f1720;
+    --shadow:0 1px 2px rgba(0,0,0,.4),0 10px 30px -16px rgba(0,0,0,.7);
+  }
+  *{box-sizing:border-box}
+  html{scroll-behavior:smooth}
+  @media (prefers-reduced-motion:reduce){html{scroll-behavior:auto}}
+  body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--font-body);
+    font-size:16.5px;line-height:1.62;-webkit-font-smoothing:antialiased;}
+  .wrap{max-width:var(--maxw);margin:0 auto;padding:0 24px}
+
+  /* top bar */
+  header.top{position:sticky;top:0;z-index:20;background:color-mix(in srgb,var(--surface) 88%,transparent);
+    backdrop-filter:saturate(1.4) blur(10px);border-bottom:1px solid var(--border)}
+  .top .wrap{display:flex;align-items:center;gap:18px;height:58px}
+  .brand{font-family:var(--font-mono);font-weight:600;font-size:14px;letter-spacing:.02em;
+    color:var(--ink);display:flex;align-items:center;gap:9px;white-space:nowrap}
+  .brand .dot{width:10px;height:10px;border-radius:2px;background:var(--accent);
+    box-shadow:0 0 0 3px var(--accent-soft)}
+  nav.doc{display:flex;gap:4px;margin-left:auto;flex-wrap:wrap}
+  nav.doc a{font-size:13.5px;color:var(--ink-2);text-decoration:none;padding:7px 12px;border-radius:8px;
+    font-weight:550;white-space:nowrap}
+  nav.doc a:hover{background:var(--surface-2);color:var(--ink)}
+  nav.doc a[aria-current="page"]{background:var(--accent-soft);color:var(--accent-ink)}
+  .toggle{border:1px solid var(--border);background:var(--surface);color:var(--ink-2);
+    width:36px;height:34px;border-radius:9px;cursor:pointer;font-size:15px;display:grid;place-items:center}
+  .toggle:hover{color:var(--ink);border-color:var(--accent)}
+  .toggle:focus-visible,nav.doc a:focus-visible,a:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+
+  /* hero */
+  .hero{padding:64px 0 34px}
+  .eyebrow{font-family:var(--font-mono);font-size:12px;letter-spacing:.18em;text-transform:uppercase;
+    color:var(--accent-ink);font-weight:600;margin:0 0 14px}
+  h1{font-family:var(--font-display);font-weight:700;font-size:clamp(2.1rem,5vw,3.1rem);line-height:1.06;
+    letter-spacing:-.02em;margin:0 0 18px;text-wrap:balance}
+  .lead{font-size:1.16rem;color:var(--ink-2);max-width:64ch;margin:0}
+  .meta{display:flex;gap:10px;flex-wrap:wrap;margin-top:26px}
+  .tag{font-family:var(--font-mono);font-size:12px;padding:5px 11px;border-radius:999px;
+    background:var(--surface-2);border:1px solid var(--border);color:var(--ink-2)}
+
+  section{padding:34px 0;border-top:1px solid var(--border)}
+  h2{font-family:var(--font-display);font-weight:650;font-size:1.6rem;letter-spacing:-.01em;margin:0 0 6px;
+    display:flex;align-items:baseline;gap:12px;text-wrap:balance}
+  h2 .num{font-family:var(--font-mono);font-size:.85rem;color:var(--accent-ink);font-weight:600}
+  h3{font-family:var(--font-display);font-weight:600;font-size:1.13rem;margin:26px 0 8px;letter-spacing:-.01em}
+  p{margin:.6em 0}
+  .sub{color:var(--ink-2);margin:2px 0 20px;max-width:66ch}
+  a{color:var(--accent-ink);text-underline-offset:3px}
+  strong{font-weight:650;color:var(--ink)}
+  code,.k{font-family:var(--font-mono);font-size:.86em;background:var(--mono-bg);
+    padding:2px 6px;border-radius:6px;border:1px solid var(--border);color:var(--ink)}
+
+  /* layer stack diagram */
+  .stack{display:flex;flex-direction:column;gap:0;margin:24px 0}
+  .layer{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:16px 18px;
+    box-shadow:var(--shadow);position:relative}
+  .layer + .layer{margin-top:26px}
+  .layer + .layer::before{content:"";position:absolute;top:-20px;left:50%;width:2px;height:14px;
+    background:var(--border);transform:translateX(-50%)}
+  .layer + .layer::after{content:"▾";position:absolute;top:-14px;left:50%;transform:translateX(-50%);
+    color:var(--ink-3);font-size:13px}
+  .layer .lh{display:flex;align-items:center;gap:10px;margin-bottom:12px}
+  .layer .lh .tier{font-family:var(--font-mono);font-size:11px;letter-spacing:.12em;text-transform:uppercase;
+    color:#fff;background:var(--accent);padding:3px 8px;border-radius:6px;font-weight:600}
+  .layer .lh h4{margin:0;font-family:var(--font-display);font-weight:600;font-size:1.02rem}
+  .layer .lh small{color:var(--ink-3);margin-left:auto;font-size:12.5px}
+  .chips{display:flex;flex-wrap:wrap;gap:8px}
+  .chip{font-family:var(--font-mono);font-size:12.5px;background:var(--surface-2);border:1px solid var(--border);
+    border-radius:8px;padding:6px 10px;color:var(--ink-2)}
+  .chip b{color:var(--ink);font-weight:600}
+
+  /* cards */
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:16px;margin-top:8px}
+  .card{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px 18px;
+    box-shadow:var(--shadow)}
+  .card h4{margin:0 0 6px;font-family:var(--font-display);font-size:1.04rem;font-weight:600;
+    display:flex;align-items:center;gap:9px}
+  .card h4 .ic{width:26px;height:26px;border-radius:7px;background:var(--accent-soft);color:var(--accent-ink);
+    display:grid;place-items:center;font-size:14px;flex:none}
+  .card p{margin:0;color:var(--ink-2);font-size:14.5px}
+  .card .files{margin-top:10px;display:flex;flex-wrap:wrap;gap:6px}
+  .card .files code{font-size:11.5px}
+
+  /* flow steps */
+  .flow{display:flex;flex-direction:column;gap:10px;margin:18px 0;counter-reset:fl}
+  .flow li{list-style:none;display:flex;gap:14px;align-items:flex-start;background:var(--surface);
+    border:1px solid var(--border);border-radius:12px;padding:13px 15px}
+  .flow li::before{counter-increment:fl;content:counter(fl);font-family:var(--font-mono);font-weight:600;
+    font-size:13px;color:var(--accent-ink);background:var(--accent-soft);border-radius:8px;
+    width:28px;height:28px;display:grid;place-items:center;flex:none}
+  .flow b{color:var(--ink)}
+  .flow small{color:var(--ink-3);display:block;font-size:13px}
+
+  .note{border:1px solid var(--border);border-left:3px solid var(--accent);background:var(--surface);
+    border-radius:0 12px 12px 0;padding:14px 16px;margin:18px 0;font-size:14.5px;color:var(--ink-2)}
+  .note b{color:var(--ink)}
+
+  footer{border-top:1px solid var(--border);padding:34px 0 60px;color:var(--ink-3);font-size:13.5px}
+  footer .wrap{display:flex;justify-content:space-between;gap:16px;flex-wrap:wrap;align-items:center}
+  footer a{color:var(--ink-2)}
+  @media (max-width:560px){.brand span.full{display:none}.hero{padding:40px 0 24px}}
+</style>
+</head>
+<body>
+<header class="top"><div class="wrap">
+  <span class="brand"><span class="dot"></span>cowork_local<span class="full">&nbsp;· docs</span></span>
+  <nav class="doc" aria-label="Tài liệu">
+    <a href="architecture.html" aria-current="page">Cấu trúc</a>
+    <a href="security.html">Bảo mật</a>
+    <a href="usage.html">Cách dùng</a>
+  </nav>
+  <button class="toggle" id="themeBtn" title="Đổi giao diện sáng/tối" aria-label="Đổi giao diện">◐</button>
+</div></header>
+
+<main>
+<div class="wrap hero">
+  <p class="eyebrow">Cowork Local · Tài liệu kỹ thuật</p>
+  <h1>Cấu trúc hệ thống</h1>
+  <p class="lead">Trợ lý AI dạng agent chạy <strong>cục bộ trên máy</strong> (desktop, ưu tiên Windows). Người dùng trò chuyện, chạy luồng nhiều bước, thao tác tệp và lên lịch tác vụ — mọi thứ được bọc trong một khung bảo mật nhiều lớp.</p>
+  <div class="meta">
+    <span class="tag">PySide6 / Qt6</span>
+    <span class="tag">Local-first</span>
+    <span class="tag">Provider-agnostic</span>
+    <span class="tag">~53K dòng Python</span>
+    <span class="tag">Windows · macOS · Linux</span>
+  </div>
+</div>
+
+<section class="wrap">
+  <h2><span class="num">01</span> Tổng quan &amp; nguyên tắc</h2>
+  <p class="sub">Bốn nguyên tắc định hình toàn bộ kiến trúc.</p>
+  <div class="grid">
+    <div class="card"><h4><span class="ic">▤</span>Local-first</h4><p>Cấu hình, lịch sử hội thoại, workspace và nhật ký đều nằm trên máy người dùng. Chỉ lệnh gọi mô hình mới ra ngoài.</p></div>
+    <div class="card"><h4><span class="ic">⛨</span>Bảo mật nhiều lớp</h4><p>Mọi tool có tác động (chạy lệnh, ghi tệp, tải URL) đi qua chuỗi kiểm soát fail-closed; xem tài liệu <a href="security.html">Bảo mật</a>.</p></div>
+    <div class="card"><h4><span class="ic">⧉</span>Đa workspace</h4><p>Nhiều project chạy song song, mỗi project nhiều hội thoại Cowork và nhiều luồng Co4E — không cái nào chặn cái nào.</p></div>
+    <div class="card"><h4><span class="ic">⇄</span>Provider-agnostic</h4><p>Nhiều nhà cung cấp mô hình (OpenAI-compatible…), tự động định tuyến chọn mô hình phù hợp trong số các model được bật.</p></div>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">02</span> Ngăn xếp công nghệ</h2>
+  <p class="sub">Những thư viện/thành phần chủ chốt và vai trò của chúng.</p>
+  <div class="chips">
+    <span class="chip"><b>PySide6/Qt6</b> · toàn bộ giao diện, đa luồng QThread</span>
+    <span class="chip"><b>FastAPI + uvicorn</b> · Routing API (chỉ localhost)</span>
+    <span class="chip"><b>MCP</b> · kết nối công cụ ngoài (Model Context Protocol)</span>
+    <span class="chip"><b>MSAL</b> · đăng nhập Microsoft 365</span>
+    <span class="chip"><b>openpyxl / python-pptx</b> · đọc Office</span>
+    <span class="chip"><b>opendataloader-pdf</b> · trích xuất PDF</span>
+    <span class="chip"><b>networkx</b> · đồ thị cấu trúc (GraphRAG)</span>
+    <span class="chip"><b>keyring</b> · lưu bí mật qua OS</span>
+    <span class="chip"><b>ctypes / Win32</b> · sandbox AppContainer &amp; Job Object</span>
+    <span class="chip"><b>Pygments</b> · tô màu mã nguồn</span>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">03</span> Kiến trúc phân lớp</h2>
+  <p class="sub">Một yêu cầu đi từ giao diện xuống lớp thực thi rồi ra ngoài — mỗi lớp có trách nhiệm rõ ràng.</p>
+  <div class="stack">
+    <div class="layer">
+      <div class="lh"><span class="tier">UI</span><h4>Lớp giao diện — PySide6</h4><small>người dùng thao tác</small></div>
+      <div class="chips">
+        <span class="chip">MainWindow</span><span class="chip">WorkspaceTab / WorkspacePane</span>
+        <span class="chip">CoworkTab (chat)</span><span class="chip">Co4ETab (flow canvas)</span>
+        <span class="chip">FolderTab</span><span class="chip">ScheduleTaskTab</span>
+        <span class="chip">MonitoringTab → Security</span><span class="chip">SettingsDialog</span>
+      </div>
+    </div>
+    <div class="layer">
+      <div class="lh"><span class="tier">Agent</span><h4>Lớp agent / lõi thực thi</h4><small>điều phối lượt chạy</small></div>
+      <div class="chips">
+        <span class="chip"><b>chat_agent</b> · run_cowork</span>
+        <span class="chip"><b>code_agent</b> · run_code</span>
+        <span class="chip"><b>co4e_runner</b> · run_workflow</span>
+        <span class="chip"><b>task_executors</b> · tác vụ theo lịch</span>
+        <span class="chip"><b>model_routing</b> · assess &amp; chọn model</span>
+        <span class="chip"><b>agent_security</b> · guardrail</span>
+      </div>
+    </div>
+    <div class="layer">
+      <div class="lh"><span class="tier">Tool</span><h4>Lớp công cụ &amp; sandbox</h4><small>ranh giới tin cậy</small></div>
+      <div class="chips">
+        <span class="chip"><b>ToolContext</b> · confine đường dẫn + scope</span>
+        <span class="chip">execute_tool</span>
+        <span class="chip">read/write/edit/list_dir</span>
+        <span class="chip">run_command · install_package</span>
+        <span class="chip">fetch_url · jira</span>
+        <span class="chip"><b>SandboxManager</b> + backends</span>
+      </div>
+    </div>
+    <div class="layer">
+      <div class="lh"><span class="tier">Provider</span><h4>Lớp nhà cung cấp mô hình</h4><small>gọi ra mạng an toàn</small></div>
+      <div class="chips">
+        <span class="chip">providers/* (OpenAI-compatible…)</span>
+        <span class="chip"><b>tls_trust</b> · phục hồi TLS gateway</span>
+        <span class="chip">usage_tracker · đo token/chi phí</span>
+      </div>
+    </div>
+    <div class="layer">
+      <div class="lh"><span class="tier">Ngoài</span><h4>Dịch vụ bên ngoài</h4><small>không tin cậy mặc định</small></div>
+      <div class="chips">
+        <span class="chip">LLM APIs</span><span class="chip">MCP servers</span>
+        <span class="chip">Microsoft 365</span><span class="chip">Jira</span><span class="chip">Web (fetch_url)</span>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">04</span> Các subsystem chính</h2>
+  <p class="sub">Mỗi khối là một tính năng lớn người dùng thấy được, ánh xạ tới module tương ứng.</p>
+  <div class="grid">
+    <div class="card"><h4><span class="ic">▦</span>Workspaces &amp; Projects</h4><p>Nhiều project song song, mỗi cái một pane riêng với sandbox bật/tắt để tiết kiệm tài nguyên.</p><div class="files"><code>workspace_tab.py</code><code>workspace_pane.py</code></div></div>
+    <div class="card"><h4><span class="ic">💬</span>Cowork · đa hội thoại</h4><p>Nhiều hội thoại trong một project; lượt chạy nền giữ đúng hội thoại gốc kể cả khi bạn chuyển tab.</p><div class="files"><code>chat_panel.py</code><code>cowork_tab.py</code></div></div>
+    <div class="card"><h4><span class="ic">◈</span>Co4E flows</h4><p>Canvas nhiều bước, agent tùy biến, chế độ auto/plan/manual, chạy song song &amp; theo dõi ở Flow Status.</p><div class="files"><code>co4e_tab.py</code><code>co4e_runner.py</code></div></div>
+    <div class="card"><h4><span class="ic">⇉</span>Model routing</h4><p>Tự đánh giá &amp; chọn mô hình tốt nhất trong số model được bật theo policy (chất lượng/chi phí/độ trễ).</p><div class="files"><code>core/routing/*</code></div></div>
+    <div class="card"><h4><span class="ic">⛨</span>Sandbox</h4><p>Chọn backend theo mức rủi ro: best-effort → AppContainer → Windows Sandbox VM.</p><div class="files"><code>sandbox_manager.py</code><code>appcontainer_sandbox.py</code></div></div>
+    <div class="card"><h4><span class="ic">⏱</span>Scheduler</h4><p>Tác vụ theo lịch (Cowork/Code/Flow), phụ thuộc chuỗi, opt-in chạy lệnh.</p><div class="files"><code>task_scheduler.py</code><code>task_executors.py</code></div></div>
+    <div class="card"><h4><span class="ic">📊</span>Monitoring</h4><p>Tổng quan chi phí, nhật ký sự kiện/bảo mật, quản trị Tool/Agent, trang Security.</p><div class="files"><code>monitoring_tab.py</code></div></div>
+    <div class="card"><h4><span class="ic">🗄</span>Lưu trữ</h4><p>Cấu hình + lịch sử theo project + workspace + audit log, tất cả trên máy.</p><div class="files"><code>config.py</code><code>core/history.py</code></div></div>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">05</span> Mô hình đồng thời</h2>
+  <p class="sub">Vì sao nhiều lượt chạy song song không giẫm chân nhau.</p>
+  <h3>Cô lập theo lượt (per-turn)</h3>
+  <p>Mỗi lượt chat chạy trong một <code>AgentWorker</code> (QThread) riêng. Tại thời điểm bắt đầu, lượt chụp lại bối cảnh <span class="k">home_*</span> (id hội thoại, thư mục làm việc, project) — nên dù người dùng chuyển sang hội thoại khác, lượt nền vẫn ghi kết quả về <strong>đúng hội thoại gốc</strong> và quét đúng thư mục của nó.</p>
+  <h3>Quản lý luồng Co4E dùng chung</h3>
+  <p>Một <code>Co4ERunManager</code> duy nhất phục vụ mọi pane, mỗi run gắn <span class="k">project_id</span> để lọc. Khi dừng một worker bị treo, nó được "park" giữ tham chiếu (không GC luồng đang chạy → tránh crash <em>QThread destroyed while running</em>).</p>
+  <div class="note"><b>Cách ly dừng (Stop):</b> nút Stop chỉ tác động lên các worker của <em>chính</em> hội thoại đó và xóa hàng đợi của riêng nó — dừng ở hội thoại này không ảnh hưởng hội thoại khác.</div>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">06</span> Luồng dữ liệu một lượt chat</h2>
+  <p class="sub">Từ tin nhắn người dùng đến kết quả — mỗi bước là một điểm kiểm soát.</p>
+  <ol class="flow">
+    <li><div><b>Tin nhắn + đính kèm</b><small>Người dùng gửi; tệp/thư mục workspace được nạp qua <code>_augment</code>.</small></div></li>
+    <li><div><b>Bọc nội dung không tin cậy</b><small>Nội dung tệp/web/tool được rào trong khối <span class="k">UNTRUSTED DATA</span> — model coi là dữ liệu, không phải mệnh lệnh.</small></div></li>
+    <li><div><b>Định tuyến mô hình</b><small>Auto Routing có thể chọn mô hình phù hợp trong số model được bật.</small></div></li>
+    <li><div><b>Gọi provider</b><small><code>provider.chat()</code> qua <code>tls_trust</code>; usage_tracker ghi token/chi phí theo hội thoại gốc.</small></div></li>
+    <li><div><b>Model gọi tool</b><small>Mỗi tool qua: kiểm scope ở executor → human-gate (nếu bật) → classifier → sandbox.</small></div></li>
+    <li><div><b>Kết quả &amp; lưu</b><small>Văn bản/diff hiện realtime; hội thoại lưu vào <code>.cowork_history</code> của project.</small></div></li>
+  </ol>
+</section>
+
+<section class="wrap">
+  <h2><span class="num">07</span> Lưu trữ trên máy</h2>
+  <p class="sub">Dữ liệu nằm ở đâu.</p>
+  <div class="chips">
+    <span class="chip"><b>~/.cowork_local/config.json</b> · cấu hình (perm 0o600)</span>
+    <span class="chip"><b>&lt;project&gt;/.cowork_history</b> · hội thoại theo project</span>
+    <span class="chip"><b>workspaces/</b> · thư mục làm việc mỗi project</span>
+    <span class="chip"><b>audit log</b> · mọi tool-call &amp; quyết định quyền (lưu hash lệnh)</span>
+    <span class="chip"><b>trusted_certs/</b> · cert gateway đã pin</span>
+    <span class="chip"><b>appcontainer_grants.json</b> · cache cấp quyền sandbox</span>
+  </div>
+  <div class="note">Vị trí lịch sử có thể trỏ vào thư mục đồng bộ OneDrive — tiện chia sẻ, nhưng lưu ý dữ liệu tệp đã nạp sẽ được sao lên cloud dạng plaintext. Xem khuyến nghị ở tài liệu <a href="security.html">Bảo mật</a>.</div>
+</section>
+</main>
+
+<footer><div class="wrap">
+  <span>Cowork Local — tài liệu nội bộ · Cấu trúc hệ thống</span>
+  <span><a href="security.html">Bảo mật →</a> &nbsp; <a href="usage.html">Cách dùng →</a></span>
+</div></footer>
+
+<script>
+  (function(){
+    var root=document.documentElement, key="cowork_docs_theme";
+    var saved=null; try{saved=localStorage.getItem(key)}catch(e){}
+    if(saved==="dark"||saved==="light") root.setAttribute("data-theme",saved);
+    else root.removeAttribute("data-theme");
+    document.getElementById("themeBtn").addEventListener("click",function(){
+      var cur=root.getAttribute("data-theme");
+      if(!cur){ // currently following OS → flip to opposite of OS
+        cur=window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";
+      }
+      var next=cur==="dark"?"light":"dark";
+      root.setAttribute("data-theme",next);
+      try{localStorage.setItem(key,next)}catch(e){}
+    });
+  })();
+</script>
+</body>
+</html>

docs/architecture/ADR-001-layered-architecture.md

@@ -0,0 +1,103 @@
+# ADR-001: 4-Tier Clean Architecture for Desktop Local Application
+
+* **Status**: ACCEPTED / ENFORCED
+* **Date**: 2026-08-21
+* **Deciders**: Team Duy (Tech Lead & AI Runtime), Team Nam (Governance & Automation), Team Hoa (Workspace & Scheduling)
+* **Target Project**: Cowork Local (Cowork-Local BamBOO)
+
+---
+
+## 1. Context and Problem Statement
+
+Cowork Local is a desktop application written in Python using PySide6 (Qt) and designed for local-first execution.
+Historically, the codebase suffered from architectural coupling across layers:
+1. **God-Widget Problem**: Monolithic UI widgets (e.g., `ui/chat_panel.py` >1,800 LOC, `ui/co4e_tab.py` >1,400 LOC) mixed UI rendering, network I/O, business rules, filesystem operations, and background worker lifecycle.
+2. **Untestable Business Logic**: Core algorithms (model routing, conversation turn management, schedule calculation) were tightly coupled to `PySide6` widgets or `QTimer`, making unit testing in headless CI environments impossible without a graphical display server.
+3. **Circular Dependencies & Global State Leaks**: Uncontrolled module imports (`model_pricing.py` ↔ `usage_tracker.py`, `agent_security.py` ↔ `agent_security_alert.py`) and mutable global state (`state.py::AppContext.active_project_id`) caused race conditions in background task runs.
+
+---
+
+## 2. Decision: 4-Tier Clean Architecture
+
+We enforce a strict **4-Tier Clean Architecture** based on the Dependency Inversion Principle:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      PRESENTATION                           │
+│  (PySide6 Widgets, Dialogs, Qt Signals/Slots, View Models)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ depends on
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      APPLICATION                            │
+│  (Use Case Services, Turn Orchestrators, Route Dispatchers) │
+│             *** STRICTLY PURE PYTHON (0 Qt) ***             │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ depends on
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   DOMAIN & RUNTIME CORE                     │
+│  (Entities, Value Objects, Domain Events, Tool Descriptors)  │
+│             *** STRICTLY PURE PYTHON (0 Qt) ***             │
+└──────────────────────────────▲──────────────────────────────┘
+                               │ implemented by
+┌──────────────────────────────┴──────────────────────────────┐
+│                     INFRASTRUCTURE                          │
+│  (LLM Providers, Keyring Secrets, Atomic Persistence, MCP)  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Layer Definitions and Responsibilities
+
+### Tier 1: Presentation Layer (`presentation/`)
+* **Responsibilities**: UI component layout, user event capture, progress display, visual animations, confirmation dialog triggers.
+* **Allowed Imports**: `PySide6.*`, `application.*`, `domain.*`.
+* **Forbidden**: Direct database queries, raw LLM API calls, disk writes outside UI cache, executing tool commands directly.
+* **Constraints**: Every widget file must strictly be **under 400 lines of code (LOC)**.
+
+### Tier 2: Application Layer (`application/`)
+* **Responsibilities**: Orchestrate single use cases (e.g. `ConversationApplicationService`, `RoutingApplicationService`, `TaskApplicationService`). Convert UI requests into domain requests, coordinate domain services with infrastructure adapters.
+* **Allowed Imports**: `domain.*`, `infrastructure.*` interfaces/contracts, standard Python libraries.
+* **Forbidden**: `PySide6`, `PyQt5`, `PyQt6`, `ui.*`, `app.*`.
+* **Nature**: **100% Pure Python**. Must be executable and testable in headless CI environments without a display driver.
+
+### Tier 3: Domain Layer (`domain/`)
+* **Responsibilities**: Core domain models, frozen DTO snapshots (`ConversationExecutionRequest`), typed event streams (`AgentEvent`), descriptors (`ToolDescriptor`, `ProviderDescriptor`), deterministic calculation algorithms (`ScheduleCalculator`).
+* **Allowed Imports**: Standard Python library only (`dataclasses`, `typing`, `enum`, `datetime`, `pathlib`, `abc`).
+* **Forbidden**: `PySide6`, `PyQt*`, `requests`, `sqlalchemy`, filesystem mutations, OS network calls.
+* **Nature**: Completely isolated and zero-dependency core.
+
+### Tier 4: Infrastructure Layer (`infrastructure/`)
+* **Responsibilities**: Adapters for external systems (OpenAI/Anthropic/Ollama/FPT providers, OS Keyring via `SecretStore`, `AtomicJsonFile` persistence, MCP child processes, filesystem tools).
+* **Allowed Imports**: Third-party SDKs, OS libraries, `domain.*`.
+* **Forbidden**: `presentation.*`, `PySide6.QtWidgets`.
+
+---
+
+## 4. Architectural Rules and Non-Negotiable Invariants
+
+1. **Zero Qt in Business Logic**:
+   - `domain/` and `application/` must never import `PySide6` or `PyQt*`.
+   - Verified via AST parser script `scripts/check_imports.py`.
+2. **Immutable Request Snapshots**:
+   - Turns are initiated using immutable frozen dataclasses (`ConversationExecutionRequest`) to decouple runtime state from mutable UI state.
+3. **Thread Safety and Signal Decoupling**:
+   - AI generation and tool calls run asynchronously in worker threads.
+   - UI updates occur strictly on the Qt main thread by consuming `AgentEvent` streams through Qt Signal bridges.
+4. **Single Responsibility and Modularity**:
+   - Production files must stay within **400 LOC**.
+5. **English In-Code Comments**:
+   - Every modified or created line/block must include concise English comments explaining design decisions and processing logic.
+
+---
+
+## 5. Consequences and Compliance
+
+* **Positive**:
+  - Full testability: Unit tests run in milliseconds without GUI or network mocks.
+  - Zero circular dependencies: Clear top-down data flow.
+  - Resilience: UI crashes do not corrupt background tasks or files.
+* **Verification**:
+  - Automated CI gate: `python scripts/check_imports.py` and `python scripts/check_loc.py`.

docs/architecture/co4e-refactor-run-report-canvas-widget.md

@@ -0,0 +1,101 @@
+# Báo cáo hoàn tất — extract:co4e_canvas_widget (lane N3 — Co4E Studio)
+
+- **Ngày:** 2026-08-25
+- **Người:** hiephv3@fpt.com (N3)
+- **Nhánh:** `gamma/refactor`
+- **Lệnh đo dùng xuyên suốt:** `.venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors`
+
+---
+
+## 1. Số test thay đổi so với baseline
+
+Baseline (Phase 0, trước khi tách):
+
+```
+323 passed, 1 skipped in 9.34s
+```
+
+Đo lại sau khi tách — chạy 3 lần liên tiếp trong lượt này:
+
+| Lần | Kết quả |
+|---|---|
+| 1 | `1 failed, 345 passed, 1 skipped in 12.25s` — `FAILED tests/test_no_ignored_source.py::test_khong_file_py_nao_bi_bo_quen_chua_theo_doi` |
+| 2 | `346 passed, 1 skipped in 13.31s` |
+| 3 | `346 passed, 1 skipped in 12.48s` |
+
+| | passed | failed | collection_errors | skipped |
+|---|---|---|---|---|
+| Trước (baseline) | 323 | 0 | 0 | 1 |
+| Sau (lần 2, 3 — ổn định) | 346 | 0 | 0 | 1 |
+
+**Về cái fail ở lần 1 — KHÔNG phải hồi quy của lane canvas-widget.** Tại đúng thời điểm chạy lần 1, `git status --porcelain` cho thấy `tests/characterization/test_co4e_runs_page.py` và `presentation/co4e/co4e_run_control_widget.py` đang ở trạng thái untracked (`??`) — đây là sản phẩm của một phiên Claude khác (lane run-control) đang làm việc song song trên cùng thư mục và chưa kịp `git add`. `test_no_ignored_source` kiểm tra "mọi file `.py` phải đã được git add trong clone sạch", nên nó bắt trúng khoảnh khắc file kia chưa staged — đây chính là kiểu hiện tượng "nhiều phiên Claude song song" mà tài liệu hướng dẫn có cảnh báo. Kiểm tra lại `git status` ngay sau đó xác nhận hai file này đã chuyển sang trạng thái `A` (đã add), và lần đo 2, 3 chạy lại đều xanh ổn định (346 passed, 0 failed cả hai lần) — không phải flaky do code của lane này, không phải do `test_atomic_json` (test flaky đã biết) xuất hiện lần nào trong 3 lần chạy.
+
+Kết luận: `passed` tăng 323 → 346 (+23, đến từ bộ test đặc tả mới `test_co4e_canvas_widget.py` của lane này cộng với các lane khác đang chạy song song trên cùng nhánh). Không có test fail mới thuộc phạm vi lane canvas-widget. `collection_errors` = 0 ở cả hai mốc. `skipped` giữ nguyên 1 (mốc cũ có giải thích trong docstring, không phải nợ phát sinh từ lane này).
+
+---
+
+## 2. File tạo mới / đã sửa
+
+**Tạo mới (thuộc phạm vi lane canvas-widget):**
+- `presentation/co4e/co4e_canvas_widget.py`
+- `presentation/co4e/canvas_items.py`
+- `presentation/co4e/canvas_interaction_mixin.py`
+- `tests/characterization/test_co4e_canvas_widget.py`
+- `docs/architecture/co4e-split-map-canvas-widget.md`
+- `docs/architecture/co4e-split-map-canvas-widget.json`
+- `docs/architecture/co4e-refactor-run-report-canvas-widget.md` (chính file này)
+
+**Đã sửa:**
+- `ui/co4e_canvas.py` — giữ lại làm shim tương thích ngược, xem mục 5.
+
+**Không thuộc lane này** (xuất hiện trong `git status --porcelain` chung của repo, do các lane khác — node-property, run-control, v.v. — đang chạy song song, liệt kê để tránh nhận vơ): `application/workflows/co4e_workflow_service.py`, `domain/workflows/run_record.py`, `presentation/co4e/agent_list_panel.py`, `presentation/co4e/canvas_geometry.py`, `presentation/co4e/co4e_tab.py`, `presentation/co4e/node_property_panel.py`, `presentation/co4e/node_property_actions_mixin.py`, `presentation/co4e/skills_list_panel.py`, `presentation/co4e/step_config_section.py`, `presentation/co4e/co4e_run_control_widget.py`, `ui/co4e_tab.py`, `ui/co4e_config_panel.py`, `tests/characterization/test_co4e_agent_panel.py`, `tests/characterization/test_co4e_run_manager_behavior.py`, `tests/characterization/test_co4e_skills_panel.py`, `tests/characterization/test_node_property_panel.py`, `tests/characterization/test_co4e_runs_page.py`, `tests/fakes/fake_co4e_workflow_service.py`, `tests/test_build_co4e_tab.py`, `tests/test_co4e_workflow_service.py`, `docs/architecture/co4e-split-map.md`, `docs/architecture/co4e-split-map.json`, `docs/architecture/co4e-split-map-node-property.md`, `docs/architecture/co4e-split-map-node-property.json`, `docs/architecture/co4e-split-map-run-control.md`, `docs/architecture/co4e-split-map-run-control.json`, `docs/architecture/co4e-refactor-run-report.md`, `docs/architecture/co4e-refactor-run-report-node-property.md`.
+
+---
+
+## 3. Kết quả cổng ranh giới
+
+**ĐỎ (FAIL)** — theo kết quả Phase 5 đã chạy (`clean: false`). Chi tiết:
+
+- **13 vi phạm FORBIDDEN**: đều là các đường dẫn thuộc quyền sở hữu N1 (node-property, run-control) hoặc file dùng chung cấm sửa cho mọi lane — ví dụ `ui/co4e_tab.py`, `ui/co4e_config_panel.py`, `presentation/co4e/node_property_panel.py`, `node_property_actions_mixin.py`, `step_config_section.py`, `docs/architecture/co4e-split-map-node-property.*`, `co4e-refactor-run-report-node-property.md`, `co4e-split-map.md/json`, `co4e-refactor-run-report.md`, `co4e-split-map-run-control.*`. **Không cái nào trong số này do lane canvas-widget đụng tới trong lượt làm việc này.**
+- **14 vi phạm OUT-OF-WHITELIST**: `application/workflows/co4e_workflow_service.py`, `domain/workflows/run_record.py`, `presentation/co4e/agent_list_panel.py`, `presentation/co4e/canvas_geometry.py`, `presentation/co4e/co4e_tab.py`, `presentation/co4e/skills_list_panel.py`, `tests/characterization/test_co4e_agent_panel.py`, `tests/characterization/test_co4e_canvas_geometry.py`, `tests/characterization/test_co4e_run_manager_behavior.py`, `tests/characterization/test_co4e_skills_panel.py`, `tests/characterization/test_node_property_panel.py`, `tests/fakes/fake_co4e_workflow_service.py`, `tests/test_build_co4e_tab.py`, `tests/test_co4e_workflow_service.py`, và mới phát sinh `tests/characterization/test_co4e_runs_page.py`. **Cũng không phải sản phẩm của lane canvas-widget** — đây là artefact của các lane khác đang chạy song song, cùng nằm trong `git status` chung của repo vì cổng chặn quét trạng thái toàn repo chứ không tách theo phiên.
+
+Đối chiếu với whitelist được cấp cho chính lane này (`tests/characterization/test_co4e_canvas_widget.py`, `presentation/co4e/co4e_canvas_widget.py`, `presentation/co4e/canvas_items.py`, `presentation/co4e/canvas_interaction_mixin.py`, `ui/co4e_canvas.py`, `docs/architecture/co4e-split-map-canvas-widget.md/json`): **không có mục nào trong 7 file này xuất hiện trong danh sách vi phạm** — cổng đỏ hoàn toàn do trạng thái git dùng chung của các lane khác chưa dọn/commit, không phải do vi phạm ranh giới của lane canvas-widget.
+
+---
+
+## 4. Kết quả bước soát output (Phase Review) — 2 lượt
+
+**Không có phát hiện nào ở mức CHAN trong cả 2 lượt soát.** Cả hai đều verdict `DAT` (đạt), `repaired: false` (không cần sửa lại trong lúc soát).
+
+### Lượt 1 — subject: `tests/characterization/test_co4e_canvas_widget.py` (verdict: DAT)
+- Mức CHAN: không có.
+- Mức SUA: không có.
+- Mức GHI_NHAN (4):
+  1. `test_relayout_on_empty_canvas_is_a_safe_noop` (dòng 723-724): assert dựa trên giá trị hardcode `True` ngay sau khi gọi `relayout()` — chỉ là phép thử "không ném exception", không khoá được giá trị/hành vi cụ thể nào của `relayout()` trên canvas rỗng. Không phải lỗi, nhưng không phải lưới an toàn thật cho trường hợp này.
+  2. Comment tại `test_zoom_in_clamps_at_max_after_7_steps_from_1_0` (dòng 686-696) lệch một đơn vị so với tính toán độc lập (chạm 3.0 ở lần áp dụng thứ 8, không phải thứ 7 như comment nói) — nhưng giá trị assert (mảng 20 phần tử) vẫn đúng 100% với hành vi thật, chỉ comment giải thích bị lệch.
+  3. `ui/co4e_canvas.py` có 2 "equivalent mutant" phát hiện qua mutation-test: xoá điều kiện `src != target_id` trong `_finish_connect` và xoá guard `if source == target: return` trong `_make_edge` đều không làm test đỏ, vì các điểm gọi `_make_edge` đã tự lọc `source != target` từ trước — hai lớp bảo vệ trùng nhau. Không phải lỗi hành vi hiện tại, nhưng là điểm cần lưu ý cho người tách sau: nếu một lớp bảo vệ mất đi trong tương lai mà không có lớp kia, quirk "tự nối vào mình" sẽ mất hiệu lực mà test này không bắt được tại đúng điểm đó.
+  4. Ghi nhận về git status: 2 file `docs/architecture/co4e-split-map-run-control.md/json` xuất hiện thêm giữa lúc soát — xác nhận là sản phẩm của một agent khác chạy song song (cùng mtime), không phải do lượt soát này gây ra; `ui/co4e_canvas.py` không đổi trạng thái và pytest 43/43 vẫn xanh sau khi khôi phục mutation.
+
+### Lượt 2 — subject: `presentation/co4e/co4e_canvas_widget.py` (verdict: DAT)
+- Mức CHAN: không có.
+- Mức SUA (1): `co4e_canvas_widget.py` dòng 75-89 (`Co4ECanvas.load`) — điểm chuyển từ domain (list Node/Edge) sang item hiển thị thiếu comment giải thích quirk "edge có source/target không nằm trong `self._nodes` bị âm thầm bỏ qua". Quirk có thật, kế thừa nguyên văn từ `ui/co4e_canvas.py` gốc (không phải lỗi mới do lần tách này gây ra — đã đối chứng bằng `git show HEAD`), nhưng theo yêu cầu B4 (bắt buộc có comment tại các điểm chuyển tầng DTO), cần bổ sung comment trong lượt sửa tiếp theo.
+- Mức GHI_NHAN (4):
+  1. Hai khối comment mâu thuẫn nhau trong `canvas_items.py` dòng 128-133 (`_NodeItem.paint`) về vị trí cổng (một khối nói "top-center/bottom-center", khối liền sau nói "left-center/right-center" — code thực tế vẽ left-center/right-center). Lỗi tồn tại sẵn trong bản gốc, được dời nguyên văn đúng kỷ luật B1 "không đổi", không phải lỗi mới. Cần dọn ở lượt sau.
+  2. Docstring của 3 file (`co4e_canvas_widget.py`, `canvas_items.py`, `canvas_interaction_mixin.py`) dẫn số dòng cụ thể của `ui/co4e_canvas.py` (ví dụ "289-317", "701 dòng tổng") không khớp với `ui/co4e_canvas.py` tại git HEAD hiện tại (791 dòng, class `Co4ECanvas` bắt đầu ở dòng 379, không phải 289). Nội dung code đã được xác minh khớp 100% bằng AST diff độc lập — đây là vấn đề chất lượng tài liệu (số dòng tham chiếu một trạng thái trung gian chưa commit), không phải lỗi hành vi.
+  3. Suite tổng đỏ 1 test (`test_no_ignored_source`) tại thời điểm soát, do file `tests/characterization/test_co4e_runs_page.py` (thuộc nhánh tách khác) chưa được `git add` — không liên quan 3 file thuộc phạm vi soát này, đã tự hết khi lane kia add file (khớp với mục 1 của báo cáo này).
+  4. `docs/architecture/co4e-refactor-run-report-canvas-widget.md` chưa được tạo tại thời điểm soát — ghi nhận thiếu deliverable, không chặn. (Báo cáo này chính là file được yêu cầu tạo, viết trong lượt hiện tại.)
+
+---
+
+## 5. Việc để lại cho lần sau
+
+- **`ui/co4e_canvas.py` vẫn còn chạy song song** với `presentation/co4e/co4e_canvas_widget.py` — hiện đóng vai trò shim/re-export để các chỗ import cũ (`from .co4e_canvas import Co4ECanvas, CO4E_MIME`) không vỡ. Cần dọn các nơi còn import theo đường cũ, chuyển sang import trực tiếp từ `presentation/co4e/co4e_canvas_widget.py`, rồi mới an toàn để rút gọn/xoá shim.
+- **1 điểm SUA từ lượt soát 2 chưa được sửa**: bổ sung comment giải thích quirk bỏ-qua-edge-mồ-côi tại `presentation/co4e/co4e_canvas_widget.py` (hàm `load`, dòng 75-89) theo đúng yêu cầu B4.
+- **2 GHI_NHAN không chặn nhưng nên dọn cùng đợt sau**: (a) comment mâu thuẫn vị trí cổng trong `canvas_items.py` dòng 128-133 (kế thừa từ bản gốc); (b) số dòng tham chiếu trong docstring của 3 file mới không khớp trạng thái HEAD hiện tại — cần cập nhật lại số dòng khi file được commit để người đọc sau đối chiếu lại được.
+- `docs/architecture/co4e-split-map-canvas-widget.md/json` là input cho bước dọn shim `ui/co4e_canvas.py` ở lượt tiếp theo.
+- Cổng ranh giới hiện đang đỏ do trạng thái git dùng chung của nhiều lane chưa commit/dọn — cần các lane liên quan (node-property, run-control, v.v.) tự commit hoặc dọn phần của mình để cổng có thể xanh trở lại cho toàn repo; lane canvas-widget không có vi phạm nào trong whitelist của chính nó (xem mục 3).
+
+## 6. Cần báo người khác trong team
+
+- Không có phát hiện mới nằm ngoài phạm vi lane này cần báo riêng (không có kiểu phát hiện như vụ `.gitignore` nuốt `infrastructure/secrets/` trước đây).
+- Đáng lưu ý (không cần hành động thêm, chỉ để các lane khác biết): trong lúc đo baseline lần 1 của lượt này, `test_no_ignored_source` đỏ thoáng qua vì lane run-control (`tests/characterization/test_co4e_runs_page.py`, `presentation/co4e/co4e_run_control_widget.py`) chưa kịp `git add` hai file mới của họ. Tự hết ở lần đo thứ 2 sau khi họ add xong. Gợi ý: các lane nên `git add` sớm sau khi tạo file mới để tránh gate/test đỏ giả khi nhiều phiên Claude chạy song song trên cùng thư mục.

docs/architecture/co4e-refactor-run-report-chat-view.md

@@ -0,0 +1,156 @@
+# Báo cáo refactor — Chat view / Composer (widget cuối) — làn N3 Co4E Studio
+
+- **Ngày:** 2026-08-25
+- **Người:** Lâm (hiephv3@fpt.com)
+- **Nhánh:** `gamma/refactor`
+- **Phạm vi:** trích xuất `_ChatInput`, `_skill_names`, `_agent_names`, `_directive_token`
+  và phần dựng UI của `ChatPanel` (từ `_build_chat` cũ) trong `ui/co4e_tab.py` sang
+  `presentation/co4e/co4e_chat_view.py`.
+
+---
+
+## 1. Số test thay đổi thế nào so với baseline
+
+Lệnh đo (chạy lại đúng lệnh baseline ngay trước khi viết báo cáo này):
+
+```
+.venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors
+```
+
+Kết quả vừa đo:
+
+```
+347 passed, 1 skipped in 8.10s
+```
+
+So với baseline được giao (Phase 0): `346 passed, 0 failed, 0 collection_errors, 1 skipped`.
+
+| | Trước (Phase 0) | Sau (vừa đo lại) |
+|---|---|---|
+| passed | 346 | 347 |
+| failed | 0 | 0 |
+| collection_errors | 0 | 0 |
+| skipped | 1 (giữ nguyên, lý do đã biết — thứ tự import `CONFIG_DIR` giữa các file test, không liên quan chat view) | 1 (cùng lý do) |
+
+**+1 passed** đúng bằng đúng 1 test mới `tests/characterization/test_co4e_chat_view.py`
+được thêm trong đợt này. Không có test fail mới, không có collection error mới →
+**không hồi quy**.
+
+- Lỗi MỐC CŨ có từ trước (nợ của làn khác): **không có** — 0 collection error, 0 failed
+  ở cả trước và sau.
+- Flaky đã biết (`tests/test_atomic_json.py::test_ghi_de_nhieu_lan_van_dung`,
+  `PermissionError [WinError 5]` khi Windows giữ khoá file tạm): **không xuất hiện**
+  trong lần đo cuối cùng này (347 passed, 0 failed). Trong lượt soát trước đó nó có
+  xuất hiện đúng 1 lần trên 2 lần chạy (`1 failed, 346 passed, 1 skipped`), rồi lần
+  chạy kế tiếp lại xanh (`347 passed, 1 skipped`) — đúng đặc điểm flaky đã biết, không
+  quy cho đợt trích xuất này.
+
+## 2. File đã tạo, file đã sửa
+
+Theo `git status --porcelain` (đối chiếu với whitelist được cấp cho lượt chat-view):
+
+**Tạo mới (thuộc lượt này):**
+- `presentation/co4e/co4e_chat_view.py` — file production mới (258 dòng, ≤ 400 dòng,
+  chỉ import PySide6.QtCore/QtWidgets, không đụng domain/application).
+- `tests/characterization/test_co4e_chat_view.py` — test đặc trưng hoá hành vi cũ.
+- `docs/architecture/co4e-split-map-chat-view.md`
+- `docs/architecture/co4e-split-map-chat-view.json`
+- `docs/architecture/co4e-refactor-run-report-chat-view.md` — chính file báo cáo này
+  (trước lượt này file chưa tồn tại — đây là khoảng thiếu mà bước soát đã ghi nhận,
+  nay bù lại).
+
+**Sửa (thuộc lượt này):**
+- `ui/co4e_tab.py` — dây lại để dùng `ChatPanel`/`_ChatInput` từ module mới thay vì
+  định nghĩa tại chỗ.
+
+**Các mục khác trong `git status` (canvas widget, node property, run control, agent
+panel, run manager, v.v.) không thuộc lượt chat-view** — đó là dấu vết của các làn/
+phiên khác đang chạy song song trên cùng thư mục làm việc (repo này có nhiều phiên
+Claude chạy đồng thời). Không đụng, không sửa trong lượt này.
+
+## 3. Cổng chặn (Phase 5)
+
+**Kết quả: ĐỎ** (`"clean": false`).
+
+Tuy nhiên toàn bộ vi phạm liệt kê **không thuộc phần lượt chat-view đã viết ra** — kiểm
+tra riêng 5 đường dẫn thuộc whitelist của lượt này
+(`presentation/co4e/co4e_chat_view.py`, `tests/characterization/test_co4e_chat_view.py`,
+`docs/architecture/co4e-split-map-chat-view.md`, `.json`, `ui/co4e_tab.py`): **không có
+đường dẫn nào trong 5 file này xuất hiện trong danh sách `violations`.**
+
+Danh sách vi phạm thật (đỏ) đến từ file của các làn khác đang tồn tại chung trong working
+tree (không do lượt chat-view tạo ra):
+
+- `FORBIDDEN` (khớp `forbidden_paths` của N1): `presentation/co4e/canvas_interaction_mixin.py`,
+  `canvas_items.py`, `co4e_canvas_widget.py`, `co4e_run_control_widget.py`,
+  `node_property_actions_mixin.py`, `node_property_panel.py`, `step_config_section.py`,
+  `ui/co4e_canvas.py`, `ui/co4e_config_panel.py`, cùng các `docs/architecture/co4e-split-map*.md/json`
+  và `co4e-refactor-run-report*.md` khác của N1.
+- `OUTSIDE_WHITELIST` (file mới không khớp `allowed_write_globs` của *lượt này*):
+  `application/workflows/co4e_workflow_service.py`, `domain/workflows/run_record.py`,
+  `presentation/co4e/agent_list_panel.py`, `canvas_geometry.py`,
+  `presentation/co4e/co4e_tab.py` (khác `ui/co4e_tab.py` được phép), `skills_list_panel.py`,
+  và các test/fakes tương ứng (`test_co4e_agent_panel.py`, `test_co4e_canvas_geometry.py`,
+  `test_co4e_canvas_widget.py`, `test_co4e_run_manager_behavior.py`, `test_co4e_runs_page.py`,
+  `test_co4e_skills_panel.py`, `test_node_property_panel.py`, `fake_co4e_workflow_service.py`,
+  `test_build_co4e_tab.py`, `test_co4e_workflow_service.py`).
+
+Kết luận: cổng chặn báo đỏ ở mức **toàn working tree**, không phải đỏ do lượt
+chat-view — vì cổng chặn quét nguyên `git status` chung, còn nhiều làn/phiên khác đang
+ghi đè cùng thư mục. Phần việc riêng của lượt chat-view (5 đường dẫn whitelist) **sạch**.
+
+## 4. Bước soát output — 2 lượt
+
+Không có phát hiện ở mức **CHAN** (chặn) trong bất kỳ lượt soát nào — cả hai lượt đều
+có `verdict: "DAT"` (đạt).
+
+**Lượt 1 — soát `tests/characterization/test_co4e_chat_view.py`:** verdict **DAT**.
+Một phát hiện mức `SUA`:
+- Dòng 193: `assert ci._popup.width() == max(280, ci.width())` — assertion rỗng nghĩa
+  cho riêng claim "280" vì `ci.width()` mặc định (chưa show/setFixedWidth) là 640 trong
+  môi trường test, luôn thắng trong `max()` bất kể 280 đổi thành gì < 640. Xác nhận bằng
+  mutation thật (280→300 trong `ui/co4e_tab.py`): test vẫn xanh (`1 passed in 2.01s`).
+  23 case còn lại trong file đều bắt được mutation tương ứng (11/12 hành vi bị làm hỏng
+  → test đỏ đúng như kỳ vọng).
+
+**Lượt 2 — soát `presentation/co4e/co4e_chat_view.py`:** verdict **DAT**. Hai phát hiện
+mức `SUA`, một mức `GHI_NHAN`:
+- `SUA`: `docs/architecture/co4e-refactor-run-report-chat-view.md` (đúng file này) chưa
+  tồn tại tại thời điểm soát — thiếu deliverable bắt buộc của quy trình. **Đã bù lại
+  bằng chính báo cáo này.**
+- `SUA`: docstring module (dòng 6-7, 15-18) trích sai số dòng gốc trong `ui/co4e_tab.py`
+  (lệch 3-35 dòng, ví dụ `_build_chat` ghi "1030-1093" nhưng thật là "1065-1128" theo
+  `git show HEAD`). Không ảnh hưởng hành vi — thân hàm đã được đối chiếu bằng
+  `ast.get_source_segment` + `difflib` và **IDENTICAL** 100% với bản gốc. Đây là lỗi
+  trích dẫn tài liệu, chưa sửa trong lượt viết báo cáo này (ngoài phạm vi được giao cho
+  lượt này — chỉ viết báo cáo, không sửa code sản xuất).
+- `GHI_NHAN`: hai file `docs/architecture/co4e-refactor-run-report-node-property.md` và
+  `co4e-refactor-run-report-run-control.md` (thuộc `forbidden_paths` của lượt chat-view)
+  có thay đổi/tồn tại — nhưng nội dung xác nhận thuộc lane khác (node-property, run-control),
+  không phải do lượt chat-view đụng vào. Không quy lỗi cho lượt này.
+
+Ngoài ra, bước soát đã tự chạy lại bộ test 2 lần độc lập để loại trừ flaky trước khi kết
+luận: lần 1 gặp `1 failed` (đúng flaky `test_atomic_json` đã biết), lần 2 `347 passed,
+1 skipped, 0 failed` — nhất quán với con số ở mục 1.
+
+## 5. Việc để lại cho lần chạy sau / cần báo người khác
+
+**Để lại cho lần sau (trong phạm vi lượt chat-view, chưa làm ở lượt viết báo cáo này):**
+- Sửa docstring module trong `presentation/co4e/co4e_chat_view.py` (dòng 6-7, 15-18) để
+  khớp đúng số dòng thật trong `ui/co4e_tab.py` (HEAD): `_skill_names` 60-64,
+  `_agent_names` 67-70, `_directive_token` 121-133, `_ChatInput` 136-225, `_build_chat`
+  1065-1128 — hiện ghi sai (63-73, 124-228, 1030-1093).
+- Làm chặt lại assertion popup-width-floor tại `tests/characterization/test_co4e_chat_view.py:193`
+  (claim "280" hiện không được khoá thật vì `ci.width()` mặc định 640 luôn thắng trong
+  `max()`) — cần set `ci` về chiều rộng nhỏ hơn 280 trước khi assert, hoặc mock riêng, để
+  test thực sự khoá hằng số 280.
+- `ui/co4e_tab.py` vẫn còn nhiều phần khác chưa tách (không thuộc phạm vi widget
+  chat/composer) — các widget khác đã có báo cáo riêng của N1
+  (`canvas-widget`, `node-property`, `run-control`).
+
+**Cần báo người khác trong team:** không có phát hiện mới nào ngoài phạm vi làn này cần
+escalate ở lượt này. Ghi nhận (không phải lỗi mới, chỉ là quan sát): repo đang có nhiều
+phiên Claude/nhiều làn chạy song song trên cùng một working tree, khiến cổng chặn của
+lượt chat-view báo đỏ ở mức toàn cục do file của các làn khác — điều này không phải do
+lượt chat-view gây ra và không cần hành động thêm từ N3, nhưng đội điều phối nên biết để
+không hiểu nhầm là lượt này làm vỡ ranh giới của N1.

docs/architecture/co4e-refactor-run-report-node-property.md

@@ -0,0 +1,226 @@
+# Báo cáo chạy — tách `StepConfigPanel` khỏi `ui/co4e_config_panel.py`
+
+- **Ngày:** 2026-08-24
+- **Người:** hiephv3@fpt.com
+- **Nhánh:** gamma/refactor
+- **Làn:** N3 — Co4E Studio, phạm vi `node_property_panel`
+
+Ghi chú: repo này có nhiều phiên Claude chạy song song trên cùng một thư mục
+làm việc. Báo cáo dưới đây chỉ trả lời 5 câu bắt buộc, không lan sang phần đã
+viết ở các lượt trước (chi tiết cắt-dán từng dòng xem
+`docs/architecture/co4e-split-map-node-property.md`/`.json`).
+
+## 1. Số test thay đổi thế nào so với baseline
+
+Lệnh đo (baseline Phase 0, chạy trước khi làn này bắt đầu):
+
+```
+.venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors
+279 passed, 1 skipped
+```
+
+Lệnh đo lại (chạy ngay bây giờ, sau khi làn này đã xong):
+
+```
+$ .venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors
+330 passed, 1 skipped in 10.15s
+```
+
+| | passed | failed | collection_errors | skipped |
+|---|---|---|---|---|
+| Trước (Phase 0) | 279 | 0 | 0 | 1 |
+| Sau (bây giờ) | 330 | 0 | 0 | 1 |
+
+- **Không có test fail nào**, mới hay cũ. `passed` sau ≥ passed trước
+  (330 ≥ 279) → không hồi quy theo tiêu chí so lệch.
+- Chênh lệch +51 **không** đến từ riêng làn này. Làn này chỉ thêm đúng 1 test
+  mới (`tests/characterization/test_node_property_panel.py`). +50 còn lại đến
+  từ các làn song song khác đã nhập vào cùng thư mục làm việc trong lúc làn
+  này chạy (`test_co4e_agent_panel.py`, `test_co4e_canvas_geometry.py`,
+  `test_co4e_canvas_widget.py`, `test_co4e_skills_panel.py`,
+  `test_build_co4e_tab.py`, `test_co4e_workflow_service.py`, ...) — thấy rõ
+  trong `git status --porcelain` ở câu 2, không phải việc của làn N3.
+- **1 skip** là mốc cũ có từ trước, không phải do lượt này gây ra:
+  `tests/characterization/test_co4e_run_manager_behavior.py:140` — tự skip
+  vì `cowork_local.config` bị file test khác import với `HOME` thật trước nó
+  trong cùng phiên pytest (giới hạn đã biết, ghi rõ trong docstring đầu file
+  đó, không liên quan `StepConfigPanel`).
+- Test flaky đã biết của repo
+  (`tests/test_atomic_json.py::test_ghi_de_nhieu_lan_van_dung`, do
+  `os.replace()` gặp khoá file tạm trên Windows) **không xuất hiện** trong
+  lần chạy này — không có gì để báo thêm về nó.
+- Chưa cần chạy lại lần hai để xác nhận vì không có test nào đỏ ở cả hai lần
+  đo (Phase 0 và bây giờ) — không có ca nghi flaky cần phân xử.
+
+## 2. File đã tạo, file đã sửa
+
+`git status --porcelain` (nguyên văn, chạy ngay lúc viết báo cáo):
+
+```
+AM application/workflows/co4e_workflow_service.py
+A  docs/architecture/co4e-refactor-run-report-node-property.md
+A  docs/architecture/co4e-split-map-node-property.json
+A  docs/architecture/co4e-split-map-node-property.md
+A  domain/workflows/run_record.py
+A  presentation/co4e/agent_list_panel.py
+A  presentation/co4e/canvas_geometry.py
+A  presentation/co4e/co4e_tab.py
+A  presentation/co4e/node_property_actions_mixin.py
+A  presentation/co4e/node_property_panel.py
+A  presentation/co4e/skills_list_panel.py
+A  presentation/co4e/step_config_section.py
+A  tests/characterization/test_co4e_agent_panel.py
+AM tests/characterization/test_co4e_canvas_geometry.py
+A  tests/characterization/test_co4e_canvas_widget.py
+AM tests/characterization/test_co4e_run_manager_behavior.py
+AM tests/characterization/test_co4e_skills_panel.py
+A  tests/characterization/test_node_property_panel.py
+A  tests/fakes/fake_co4e_workflow_service.py
+A  tests/test_build_co4e_tab.py
+AM tests/test_co4e_workflow_service.py
+ M ui/co4e_canvas.py
+M  ui/co4e_config_panel.py
+ M ui/co4e_tab.py
+?? .codegraph/
+?? cowork_local
+?? docs/architecture/co4e-refactor-run-report.md
+?? docs/architecture/co4e-split-map.json
+?? docs/architecture/co4e-split-map.md
+?? run_app.bat
+?? stop_running.ps1
+```
+
+**Của đúng làn N3 (`node_property_panel`) — khớp danh sách đường dẫn được
+cấp quyền:**
+
+- Mới: `presentation/co4e/node_property_panel.py` (293 dòng),
+  `presentation/co4e/node_property_actions_mixin.py` (202 dòng),
+  `presentation/co4e/step_config_section.py` (134 dòng),
+  `tests/characterization/test_node_property_panel.py`,
+  `docs/architecture/co4e-split-map-node-property.md`,
+  `docs/architecture/co4e-split-map-node-property.json`,
+  `docs/architecture/co4e-refactor-run-report-node-property.md` (chính file
+  này).
+- Sửa: `ui/co4e_config_panel.py` (528 dòng → 14 dòng, chỉ còn re-export
+  `StepConfigPanel`).
+- Cả 3 file production mới đều ≤ 400 dòng (293/202/134).
+
+**Không thuộc làn N3 — xuất hiện trong `git status` vì có phiên khác đang
+chạy song song trên cùng thư mục, làn này không đụng tới:**
+`application/workflows/co4e_workflow_service.py`,
+`domain/workflows/run_record.py`, `presentation/co4e/agent_list_panel.py`,
+`presentation/co4e/canvas_geometry.py`, `presentation/co4e/co4e_tab.py`,
+`presentation/co4e/skills_list_panel.py`,
+`tests/characterization/test_co4e_agent_panel.py`,
+`tests/characterization/test_co4e_canvas_geometry.py`,
+`tests/characterization/test_co4e_canvas_widget.py`,
+`tests/characterization/test_co4e_run_manager_behavior.py`,
+`tests/characterization/test_co4e_skills_panel.py`,
+`tests/fakes/fake_co4e_workflow_service.py`, `tests/test_build_co4e_tab.py`,
+`tests/test_co4e_workflow_service.py`, `ui/co4e_canvas.py`,
+`ui/co4e_tab.py`, cùng các file untracked
+`docs/architecture/co4e-split-map.md`/`.json`,
+`docs/architecture/co4e-refactor-run-report.md`, `.codegraph/`,
+`cowork_local`, `run_app.bat`, `stop_running.ps1`.
+
+## 3. Cổng ranh giới: xanh hay đỏ
+
+**Đỏ** (`clean: false`), nhưng **không phải vì làn N3 tự ý sửa các file cấm**
+— tất cả vi phạm đều là file thuộc phạm vi làn khác (N1) hoặc làn song song
+khác đang có mặt trong cùng thư mục làm việc tại thời điểm chạy cổng chặn:
+
+- **FORBIDDEN** (đúng danh sách cấm tuyệt đối của N3, thuộc làn N1):
+  `ui/co4e_tab.py` (M), `ui/co4e_canvas.py` (M),
+  `docs/architecture/co4e-split-map.md` (mới), `docs/architecture/co4e-split-map.json` (mới),
+  `docs/architecture/co4e-refactor-run-report.md` (mới).
+- **OUTSIDE-WHITELIST** (không khớp `allowed_write_globs` của N3):
+  `application/workflows/co4e_workflow_service.py`,
+  `domain/workflows/run_record.py`,
+  `presentation/co4e/agent_list_panel.py`,
+  `presentation/co4e/canvas_geometry.py`, `presentation/co4e/co4e_tab.py`,
+  `presentation/co4e/skills_list_panel.py`,
+  `tests/characterization/test_co4e_agent_panel.py`,
+  `tests/characterization/test_co4e_canvas_geometry.py`,
+  `tests/characterization/test_co4e_canvas_widget.py`,
+  `tests/characterization/test_co4e_run_manager_behavior.py`,
+  `tests/characterization/test_co4e_skills_panel.py`,
+  `tests/fakes/fake_co4e_workflow_service.py`, `tests/test_build_co4e_tab.py`,
+  `tests/test_co4e_workflow_service.py`.
+- `loc_over_cap`: rỗng — không file nào của làn N3 vượt 400 dòng.
+- `pyside_leaks`: rỗng — không có import PySide6/PyQt trong
+  `domain/`/`application/` (kiểm bằng AST parse, không phải grep).
+
+Kết luận: 8 file đúng phạm vi được cấp cho làn N3 (danh sách 400-file ở đầu
+prompt) đều nằm gọn trong whitelist, không file nào của làn N3 chạm vào danh
+sách cấm. Cổng đỏ là do **trạng thái chung của working tree** (nhiều làn ghi
+song song), không phải hồi quy do thay đổi của làn này gây ra. Người quyết
+định commit cần biết: nếu commit y nguyên `git status` hiện tại, sẽ commit
+luôn cả các thay đổi của những làn khác (N1 và các làn Co4E khác) — cần
+tách bằng `git add` đúng danh sách 8 file của N3 trước khi commit, không
+`git add -A`.
+
+## 4. Bước soát output — 2 lượt, tách riêng theo mức `CHAN`
+
+**Không lượt soát nào phát hiện mức `CHAN`.** (Mức `CHAN` = test không bắt
+được lỗi, hoặc code bị viết lại thay vì dời — không có trường hợp nào như
+vậy trong cả 2 lượt.)
+
+- **Lượt 1 — chủ thể `tests/characterization/test_node_property_panel.py`,
+  verdict: ĐẠT.**
+  1 phát hiện mức **SUA** (không phải `CHAN`): file test mới chưa
+  `git add`, nên khi chạy full suite làm đỏ
+  `tests/test_no_ignored_source.py::test_khong_file_py_nao_bi_bo_quen_chua_theo_doi`.
+  Không phải lỗi logic của test — chỉ là bước staging còn thiếu, đã tự sửa
+  bằng cách stage file (đã staged, xem `git status` ở câu 2: `A
+  tests/characterization/test_node_property_panel.py`).
+  Xác nhận qua bite-test: phá 14/14 hành vi riêng của
+  `ui/co4e_config_panel.py` (bản gốc, trước khi tách) đều bị test bắt được,
+  đã khôi phục lại nguyên trạng sau khi thử.
+
+- **Lượt 2 — chủ thể `presentation/co4e/node_property_panel.py`, verdict:
+  ĐẠT.**
+  1 phát hiện mức **GHI_NHẬN** (không phải `CHAN`, không phải `SUA`): số
+  test trong báo cáo cũ (`287 passed, 1 skipped`) lệch với hiện trạng lúc
+  soát (`330 passed, 1 skipped`) — do các làn song song khác nhập test mới
+  vào giữa lúc viết báo cáo và lúc soát, không phải lỗi của việc tách
+  `StepConfigPanel`. Báo cáo này (bản viết lại) đã cập nhật đúng số thật
+  330/1 ở mục 1.
+  Xác nhận thân hàm `__init__`/`load_step`/`clear_step`/`_on_edit` trong
+  `node_property_panel.py` **giống byte-for-byte** (240/240 dòng) với bản
+  gốc `ui/co4e_config_panel.py` tại HEAD; 8 method trong
+  `node_property_actions_mixin.py` chỉ khác đúng độ sâu import
+  (`..core` → `...core`, đúng do file dời sâu thêm 1 cấp thư mục); bite-test
+  phá 5 hành vi riêng trong 2 file production mới đều bị test bắt được, đã
+  khôi phục nguyên trạng. `tools/check_co4e.py` (cổng kiểm soát riêng): giữ
+  nguyên `27/27` control cũ.
+
+## 5. Việc để lại cho lần sau / cần báo người khác
+
+**Để lại cho lần sau (thuộc phạm vi làn N3 hoặc làn kế tiếp có liên quan):**
+
+1. `docs/architecture/co4e-split-map.md` (làn N1, không được sửa ở đây) vẫn
+   liệt kê `node_property_panel.py` như một đích còn dở của việc tách
+   `ui/co4e_tab.py`/`ui/co4e_canvas.py` qua Signal
+   `node_selected`/`node_activated`. Sau lượt này `StepConfigPanel` đã có nơi
+   ở thật (`presentation/co4e/node_property_panel.py`); làn phụ trách tách
+   `ui/co4e_tab.py` có thể import thẳng từ đó thay vì qua
+   `ui/co4e_config_panel.py`, nhưng đó là quyết định của làn N1, không tự
+   đổi ở đây.
+2. `_ai_draft`/`_load_models` trong `node_property_actions_mixin.py` vẫn
+   dùng `AgentWorker`/`QThread` thật (chưa tách phần logic thuần khỏi UI).
+   Nếu có lượt sau muốn đẩy xuống `application/`, cần định nghĩa `Protocol`
+   cho runner tiêm qua constructor — ngoài phạm vi cắt-dán của lượt này.
+3. `ui/co4e_config_panel.py` (14 dòng) vẫn còn sống song song làm lớp
+   re-export — chưa xoá, vì `ui/co4e_tab.py` (thuộc N1) còn import từ đó.
+   Xoá file này là quyết định của người sở hữu `ui/co4e_tab.py`.
+
+**Cần báo người khác trong team:**
+
+Không có phát hiện mới ngoài phạm vi làn này (không có kiểu phát hiện như
+tiền lệ `.gitignore`/`secrets/` nêu trong hướng dẫn). Điểm duy nhất đáng nhắc
+lại — không phải phát hiện mới mà là nhắc để tránh hiểu nhầm khi đọc mục 3:
+cổng ranh giới của làn N3 báo đỏ hoàn toàn do có nhiều phiên làm việc song
+song ghi vào cùng thư mục (`ui/co4e_tab.py`, `ui/co4e_canvas.py`,
+`presentation/co4e/agent_list_panel.py`, v.v. — thuộc N1 và các làn Co4E
+khác), không phải do thay đổi của làn N3. Ai gộp nhánh cần tách commit theo
+đúng danh sách 8 file ở mục 2/3, không gộp `git add -A`.

docs/architecture/co4e-refactor-run-report-run-control.md

@@ -0,0 +1,149 @@
+# Báo cáo refactor — Flow Status (Runs page) — làn N3 Co4E Studio
+
+- **Ngày:** 2026-08-25
+- **Người:** Lâm (N3 — Co4E Studio), hiephv3@fpt.com
+- **Nhánh:** `gamma/refactor`
+- **Phạm vi cho phép ghi (whitelist của làn này):**
+  `tests/characterization/test_co4e_runs_page.py`,
+  `presentation/co4e/co4e_run_control_widget.py`,
+  `docs/architecture/co4e-split-map-run-control.md`,
+  `docs/architecture/co4e-split-map-run-control.json`,
+  `ui/co4e_tab.py`,
+  `docs/architecture/co4e-refactor-run-report-run-control.md`
+
+---
+
+## 1. Số test thay đổi thế nào so với baseline
+
+Lệnh đo (chạy lại đúng nguyên văn):
+
+```
+.venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors
+```
+
+| Mốc | passed | failed | collection_errors | skipped |
+|---|---|---|---|---|
+| Baseline (Phase 0) | 323 | 0 | 0 | 1 |
+| Sau lượt này (đo lại vừa xong) | 346 | 0 | 0 | 1 |
+
+Kết quả đo lại, 15 dòng cuối nguyên văn:
+
+```
+PASSED tests/test_settings_facade.py::test_provider_doc_duoc_ba_truong
+PASSED tests/test_settings_facade.py::test_ollama_khong_can_khoa_van_tinh_la_da_cau_hinh
+PASSED tests/test_settings_facade.py::test_thieu_model_thi_chua_cau_hinh
+PASSED tests/test_settings_facade.py::test_gia_tri_None_tra_ve_mac_dinh_chu_khong_None
+PASSED tests/test_settings_facade.py::test_routing_kieu_du_lieu_dung
+PASSED tests/test_settings_facade.py::test_tat_dinh_tuyen
+PASSED tests/test_settings_facade.py::test_sua_qua_khung_nhin_la_sua_vao_dict_that
+PASSED tests/test_settings_facade.py::test_raw_de_khong_ai_bi_ket
+PASSED tests/test_settings_facade.py::test_security_mac_dinh_la_bat
+PASSED tests/test_settings_facade.py::test_settings_noi_vao_repo
+PASSED tests/test_settings_facade.py::test_doi_provider_thi_khung_nhin_theo_ngay
+SKIPPED [1] tests\characterization\test_co4e_run_manager_behavior.py:140: cowork_local.config da bi mot file test khac import voi HOME that TRUOC file nay trong cung phien pytest (thu tu collect) -- CONFIG_DIR=WindowsPath('C:/Users/LamHV7/.cowork_local') khong con nam trong sandbox cua file nay. Day la gioi han da biet (xem docstring dau file), KHONG phai mat an toan du lieu: moi test hook trong file nay tu va thang Co4ERunManager._history_path (doc lap voi CONFIG_DIR) nen khong test nao trong file thuc su cham vao lich su run that.
+346 passed, 1 skipped in 25.78s
+```
+
+Nhận định:
+
+- `passed` tăng 323 → 346 (+23), đúng bằng 23 test mới trong `tests/characterization/test_co4e_runs_page.py` (đã được xác nhận `23 passed` khi chạy riêng file này ở bước Phase Review). Không có test cũ nào bị mất.
+- `failed`: 0 ở cả hai mốc — **không có test fail mới**. Không có hồi quy theo tiêu chí "không fail mới ngoài danh sách baseline".
+- `collection_errors`: 0 ở cả hai mốc — không tăng.
+- 1 skip — **giữ nguyên từ baseline**, là giới hạn đã biết từ trước (thứ tự collect ảnh hưởng `CONFIG_DIR` trong `test_co4e_run_manager_behavior.py`), không phải do lượt này gây ra.
+- Test flaky đã biết (`tests/test_atomic_json.py::test_ghi_de_nhieu_lan_van_dung`) — không xuất hiện trong danh sách fail ở cả hai lần chạy toàn bộ suite được ghi trong Phase Review (346 passed, 1 skipped cả hai lần) và không xuất hiện ở lần đo lại vừa rồi. Không có gì để báo về test này trong lượt này.
+
+**Kết luận:** không có hồi quy.
+
+---
+
+## 2. File đã tạo, file đã sửa
+
+Theo `git status --porcelain` (đo lại tại thời điểm viết báo cáo này) và đối chiếu whitelist của làn:
+
+**Trong whitelist của làn này (run-control) — đã có mặt đầy đủ, cả 5 mục:**
+- Tạo mới, đã `git add` (trạng thái `A`): `presentation/co4e/co4e_run_control_widget.py`, `tests/characterization/test_co4e_runs_page.py`
+- Tạo mới, chưa `git add` (trạng thái `??`): `docs/architecture/co4e-split-map-run-control.md`, `docs/architecture/co4e-split-map-run-control.json`
+- Sửa, chưa stage (trạng thái ` M`): `ui/co4e_tab.py`
+- (file báo cáo này, `docs/architecture/co4e-refactor-run-report-run-control.md`, do lượt này vừa ghi — chưa `git add` tại thời điểm viết)
+
+**Ngoài whitelist của làn này (thuộc làn khác/song song, KHÔNG do lượt này tạo ra — liệt kê để minh bạch trạng thái thư mục làm việc, không phải việc của làn này):**
+`application/workflows/co4e_workflow_service.py`, `domain/workflows/run_record.py`,
+`presentation/co4e/agent_list_panel.py`, `presentation/co4e/canvas_geometry.py`,
+`presentation/co4e/canvas_interaction_mixin.py`, `presentation/co4e/canvas_items.py`,
+`presentation/co4e/co4e_canvas_widget.py`, `presentation/co4e/co4e_tab.py`,
+`presentation/co4e/node_property_actions_mixin.py`, `presentation/co4e/node_property_panel.py`,
+`presentation/co4e/skills_list_panel.py`, `presentation/co4e/step_config_section.py`,
+`tests/characterization/test_co4e_agent_panel.py`, `tests/characterization/test_co4e_canvas_geometry.py`,
+`tests/characterization/test_co4e_canvas_widget.py`, `tests/characterization/test_co4e_run_manager_behavior.py`,
+`tests/characterization/test_co4e_skills_panel.py`, `tests/characterization/test_node_property_panel.py`,
+`tests/fakes/fake_co4e_workflow_service.py`, `tests/test_build_co4e_tab.py`, `tests/test_co4e_workflow_service.py`,
+`ui/co4e_canvas.py`, `ui/co4e_config_panel.py`,
+`docs/architecture/co4e-refactor-run-report-node-property.md`, `docs/architecture/co4e-split-map-node-property.json`,
+`docs/architecture/co4e-split-map-node-property.md`, `docs/architecture/co4e-refactor-run-report-canvas-widget.md`,
+`docs/architecture/co4e-refactor-run-report.md`, `docs/architecture/co4e-split-map-canvas-widget.json`,
+`docs/architecture/co4e-split-map-canvas-widget.md`, `docs/architecture/co4e-split-map.json`,
+`docs/architecture/co4e-split-map.md`,
+và các mục không do agent tạo: `.codegraph/`, `cowork_local` (file rỗng có sẵn), `run_app.bat`, `stop_running.ps1`.
+
+Lượt này **không đụng** đến bất kỳ file nào trong danh sách "TUYỆT ĐỐI KHÔNG Edit/Write".
+
+---
+
+## 3. Cổng chặn (boundary gate) — xanh hay đỏ
+
+**ĐỎ** — kết quả Phase 5 do hệ thống chấm gửi kèm ghi `"clean": false`, với các vi phạm sau:
+
+- **Vi phạm nặng (forbidden_paths của N1 bị đụng):** `ui/co4e_canvas.py`, `ui/co4e_config_panel.py`,
+  `presentation/co4e/co4e_canvas_widget.py`, `presentation/co4e/canvas_items.py`,
+  `presentation/co4e/canvas_interaction_mixin.py`, `presentation/co4e/node_property_panel.py`,
+  `presentation/co4e/node_property_actions_mixin.py`, `presentation/co4e/step_config_section.py`,
+  `docs/architecture/co4e-split-map.md`, `docs/architecture/co4e-split-map.json`,
+  `docs/architecture/co4e-refactor-run-report.md`, `docs/architecture/co4e-refactor-run-report-node-property.md`,
+  `docs/architecture/co4e-split-map-node-property.md`, `docs/architecture/co4e-split-map-node-property.json`.
+- **Ngoài whitelist (allowed_write_globs) của làn run-control:** `application/workflows/co4e_workflow_service.py`,
+  `domain/workflows/run_record.py`, `presentation/co4e/agent_list_panel.py`, `presentation/co4e/canvas_geometry.py`,
+  `presentation/co4e/co4e_tab.py` (lưu ý: khác `ui/co4e_tab.py` đang được whitelist),
+  `presentation/co4e/skills_list_panel.py`, và các file test/tài liệu liên quan (danh sách đầy đủ ở mục 2).
+
+**Quan trọng:** Đối chiếu với timestamp (`co4e-refactor-run-report-node-property.md` sửa lần cuối 24/08 21:33, còn `presentation/co4e/co4e_run_control_widget.py` — sản phẩm của lượt này — có mtime 25/08 10:00, cách nhau ~13 tiếng) và nội dung diff của các file vi phạm nói về canvas/node-property (không liên quan runs page), kết luận: **các vi phạm trên là dirty state sót lại từ các làn khác (N1 — canvas widget, node-property) chạy song song trên cùng thư mục làm việc, không phải do lượt run-control này tạo ra hay sửa.** Lượt này chỉ tạo/sửa đúng các file trong whitelist của mình (mục 2).
+
+Cổng chặn không phân biệt được "ai gây ra" — nó chỉ nhìn `git status` tại thời điểm chấm, nên bị đỏ do cộng dồn trạng thái của nhiều làn cùng lúc. Đây là hạn chế đã biết của việc nhiều phiên Claude làm việc song song trên cùng repo (xem mục 5).
+
+---
+
+## 4. Bước soát output (Phase Review) — 2 lượt, mỗi mức CHAN nêu riêng
+
+Có 2 lượt soát, không có mức `CHAN` nào ở cả hai lượt (cả hai đều **ĐẠT**).
+
+**Lượt 1 — `tests/characterization/test_co4e_runs_page.py`:** verdict **DAT**, `repaired: true`.
+Không có mức CHAN. Có 1 ghi nhận mức `GHI_NHAN` (không chặn): khi chạy full-suite, file này còn ở trạng thái untracked (`??`) nên `tests/test_no_ignored_source.py::test_khong_file_py_nao_bi_bo_quen_chua_theo_doi` báo 1 failed — đây là lỗi hygiene do file chưa `git add`, không phải lỗi hành vi của bản thân test. (Ghi chú: theo `git status --porcelain` đo lại tại thời điểm viết báo cáo này, file đã chuyển sang trạng thái `A` — đã được `git add` — nên phát hiện này coi như đã được xử lý; không cần hành động thêm.)
+
+Đã kiểm 5 hạng mục (A1–A5), tất cả đạt:
+- A1: chạy riêng `23 passed, 0 failed, 0 lỗi collection`.
+- A2: AST đếm assert — cả 23 hàm test đều có ≥1 assert thực chất, không có assert giả (`assert True`, `x==x`, isinstance-suông).
+- A3: chạy probe script độc lập qua subprocess, đối chiếu JSON thật với từng assert — khớp 100%.
+- A4: 4 mutation thuộc 4 loại khác nhau trên `ui/co4e_tab.py` (đảo điều kiện, hoán dây connect, lật cờ edit-trigger, xoá `setObjectName`) — cả 4 đều làm đúng test tương ứng ĐỎ, sau đó khôi phục nguyên trạng (verify bằng `git status`/`git diff --stat` trước-sau giống hệt nhau).
+- A5: xác nhận probe chạy trong sandbox HOME riêng (tmp_path), không đụng `~/.cowork_local` thật (36 file trước/sau giống hệt, không file nào bị tạo/sửa/xoá).
+
+**Lượt 2 — `presentation/co4e/co4e_run_control_widget.py`:** verdict **DAT**, `repaired: false`.
+Không có mức CHAN. Có 3 ghi nhận mức `GHI_NHAN` (không chặn):
+1. `__init__` mới có 7 thuộc tính đổi tên (ví dụ `runs_back_btn`→`back_btn`, `run_stop_btn`→`stop_btn`, `runs_table`→`table`, v.v.) và các `.clicked`/`.itemDoubleClicked`/`.customContextMenuRequested.connect(...)` bị chuyển ra khỏi hàm dựng — vượt quá phạm vi "chỉ đổi import" theo định nghĩa gốc của B1, nhưng có tài liệu trong docstring, đúng tiền lệ (`AgentListPanel`/`SkillsListPanel`), và caller (`ui/co4e_tab.py` dòng 880-897) đã rewiring lại đúng thứ tự/target cũ — 23/23 test đặc tả hành vi vẫn xanh.
+2. `docs/architecture/co4e-refactor-run-report-node-property.md` nằm trong danh sách TUYỆT ĐỐI KHÔNG được sửa của lượt này nhưng đang ở trạng thái dở dang chưa stage trong thư mục làm việc — xác nhận qua mtime và nội dung diff là dirty state của làn khác (N1), không phải do lượt run-control gây ra (đã dẫn ở mục 3), nhưng vẫn cần người phụ trách làn đó revert/commit trước khi `git add -A` toàn repo.
+3. Quirk "`clear_btn` là nút DUY NHẤT không có `setIcon(...)`" được đặc tả kỹ trong test nhưng **không có comment tại nơi định nghĩa `clear_btn` trong file sản phẩm** cảnh báo đây là cố ý — rủi ro người sửa sau tưởng thiếu sót và "sửa" làm vỡ quirk đã khoá bằng test.
+
+Đã kiểm 5 hạng mục (B1–B5), tất cả đạt: diff thân hàm dựng cũ/mới, import thật + hasattr-check, đếm dòng (116 ≤ 400), đọc toàn văn đánh giá docstring, chạy lại toàn bộ suite 2 lần + file mới + test flaky riêng — không phát hiện sai lệch.
+
+**Tóm lại:** không có mức `CHAN` nào ở cả hai lượt soát. Cả hai file sản phẩm của lượt này (test mới và widget mới) đều được xác nhận là bắt đúng hành vi thật (không phải test giả), và code được dời (không viết lại tuỳ tiện) có tài liệu hoá đầy đủ.
+
+---
+
+## 5. Việc để lại cho lần sau / cần báo người khác
+
+**Để lại cho lần chạy sau (trong phạm vi làn run-control):**
+- `docs/architecture/co4e-split-map-run-control.md` và `.json` — đã tồn tại trên đĩa nhưng vẫn ở trạng thái `??` (untracked) tại thời điểm viết báo cáo này. Cần `git add` cùng với `presentation/co4e/co4e_run_control_widget.py` và `tests/characterization/test_co4e_runs_page.py` (hiện đã `A` — staged) trước khi coi lượt này là hoàn tất, để `test_khong_file_py_nao_bi_bo_quen_chua_theo_doi` không báo đỏ oan.
+- `ui/co4e_tab.py` còn ở trạng thái sửa nhưng chưa stage (` M`) — cần review diff và `git add` cùng đợt.
+- Comment cảnh báo quirk "`clear_btn` không có icon là cố ý" nên được thêm vào ngay tại `presentation/co4e/co4e_run_control_widget.py` dòng định nghĩa `clear_btn` (hiện chỉ có trong test, chưa có trong code sản phẩm) — để người sửa sau không vô tình làm vỡ.
+
+**Cần báo người khác trong team (ngoài phạm vi làn này, không tự sửa):**
+- Cổng ranh giới đang báo đỏ vì thư mục làm việc đang có dirty state cộng dồn từ nhiều làn chạy song song (N1 — canvas widget, node-property; và làn run-control này). Cụ thể các file bị N1 khoá (`ui/co4e_canvas.py`, `ui/co4e_config_panel.py`, `presentation/co4e/co4e_canvas_widget.py`, `presentation/co4e/node_property_panel.py`, v.v.) và `docs/architecture/co4e-refactor-run-report-node-property.md` đang ở trạng thái sửa dở, chưa stage/commit — đã xác nhận qua mtime và nội dung diff rằng đây không phải do lượt run-control gây ra. Người phụ trách các làn đó cần commit hoặc dọn dẹp phần của mình để cổng chặn của các làn khác (bao gồm làn này) không bị báo đỏ oan do trạng thái chung của thư mục.
+- Tiền lệ đã biết trong repo (không phải phát hiện mới của lượt này, nhắc lại để không quên): pattern `.gitignore` từng nuốt `infrastructure/secrets/` đã được N1 sửa ngày 22/08; không có phát hiện mới cùng loại trong lượt này.

docs/architecture/co4e-refactor-run-report.md

@@ -0,0 +1,297 @@
+# Báo cáo chạy — Co4E Studio (N3)
+
+- **Ngày:** 2026-08-24
+- **Người:** Lâm (N3 — Co4E Studio), hiephv3@fpt.com
+- **Nhánh:** gamma/refactor
+
+## 1. Số test thay đổi thế nào so với baseline?
+
+Lệnh đo (đúng lệnh được giao), chạy **2 lần liên tiếp** cho báo cáo này:
+
+```
+.venv/Scripts/python.exe -m pytest tests -q --tb=no -rA --continue-on-collection-errors
+```
+
+Lần 1: `277 passed in 4.96s`
+Lần 2: `277 passed in 22.35s`
+
+| | Phase 0 (baseline, đề bài đưa vào) | Đo lại hôm nay (2 lần) |
+|---|---|---|
+| passed | 228 | 277 |
+| failed | 0 | 0 |
+| collection_errors | 0 | 0 |
+
+- **Tăng đúng 49 passed** (`228 → 277`), khớp với các file test mới của đợt
+  tách này: `tests/characterization/test_co4e_canvas_geometry.py` (42),
+  `tests/characterization/test_co4e_run_manager_behavior.py` (32 — nhưng
+  không cộng dồn nguyên vẹn vì có test trùng ý với `test_co4e_workflow_service.py`),
+  `tests/characterization/test_co4e_skills_panel.py` (1), `tests/test_build_co4e_tab.py`
+  (1), `tests/test_co4e_workflow_service.py` (nhiều test mới cho
+  `Co4EWorkflowService`/`RunRecord`). Không có test nào khác đổi trạng thái so
+  với baseline.
+- **Không có test fail nào** ở cả 2 lần chạy, cũ lẫn mới → **không hồi quy**
+  theo tiêu chí "không có fail mới ngoài danh sách fail của baseline" (baseline
+  có 0 fail, đo lại cũng 0 fail).
+- **`collection_errors` = 0 ở cả hai mốc**, không tăng. Món nợ cũ (4 module
+  chết vì `.gitignore` nuốt `infrastructure/secrets/`) không xuất hiện ở đợt
+  đo này — đây là nợ N1, đã xử lý từ 22/08, không liên quan lần chạy này.
+- Test flaky đã biết trên Windows,
+  `tests/test_atomic_json.py::test_ghi_de_nhieu_lan_van_dung` — **PASS ở cả 2
+  lần chạy** trong báo cáo này (thấy trong `raw_tail`... thực ra nằm giữa
+  output, không phải 15 dòng cuối, nhưng có mặt và mang trạng thái PASSED ở cả
+  hai lần). Không thấy tái diễn ở đợt đo này, nhưng cơ chế gây lỗi (khoá file
+  tạm trên Windows khi chạy dồn) **chưa được sửa** — nếu lần sau thấy nó đỏ,
+  kiểm tra có phiên `pytest` khác chạy song song trước khi kết luận là hồi quy.
+
+Raw tail (15 dòng cuối, nguyên văn, lần đo thứ hai — `277 passed in 22.35s`):
+
+```
+PASSED tests/test_schema_migration.py::test_repository_tu_chuyen_khoa_khi_mo_file_cu
+PASSED tests/test_schema_migration.py::test_mo_lai_lan_hai_khong_chuyen_lai
+PASSED tests/test_schema_migration.py::test_save_luon_ghi_so_phien_ban
+PASSED tests/test_settings_facade.py::test_provider_doc_duoc_ba_truong
+PASSED tests/test_settings_facade.py::test_ollama_khong_can_khoa_van_tinh_la_da_cau_hinh
+PASSED tests/test_settings_facade.py::test_thieu_model_thi_chua_cau_hinh
+PASSED tests/test_settings_facade.py::test_gia_tri_None_tra_ve_mac_dinh_chu_khong_None
+PASSED tests/test_settings_facade.py::test_routing_kieu_du_lieu_dung
+PASSED tests/test_settings_facade.py::test_tat_dinh_tuyen
+PASSED tests/test_settings_facade.py::test_sua_qua_khung_nhin_la_sua_vao_dict_that
+PASSED tests/test_settings_facade.py::test_raw_de_khong_ai_bi_ket
+PASSED tests/test_settings_facade.py::test_security_mac_dinh_la_bat
+PASSED tests/test_settings_facade.py::test_settings_noi_vao_repo
+PASSED tests/test_settings_facade.py::test_doi_provider_thi_khung_nhin_theo_ngay
+277 passed in 22.35s
+```
+
+## 2. File nào đã tạo, file nào đã sửa
+
+Theo `git status --porcelain` (đo ngay trước khi viết báo cáo này):
+
+```
+AM application/workflows/co4e_workflow_service.py
+A  domain/workflows/run_record.py
+A  presentation/co4e/canvas_geometry.py
+A  presentation/co4e/co4e_tab.py
+A  presentation/co4e/skills_list_panel.py
+A  tests/characterization/test_co4e_canvas_geometry.py
+A  tests/characterization/test_co4e_run_manager_behavior.py
+A  tests/characterization/test_co4e_skills_panel.py
+A  tests/fakes/fake_co4e_workflow_service.py
+A  tests/test_build_co4e_tab.py
+AM tests/test_co4e_workflow_service.py
+ M ui/co4e_canvas.py
+ M ui/co4e_tab.py
+?? .codegraph/
+?? cowork_local
+?? docs/architecture/co4e-refactor-run-report.md
+?? docs/architecture/co4e-split-map.json
+?? docs/architecture/co4e-split-map.md
+?? run_app.bat
+?? stop_running.ps1
+```
+
+**Tạo mới (`A`), thuộc phạm vi làn N3, trong whitelist:**
+
+- `domain/workflows/run_record.py` — `RunRecord`.
+- `presentation/co4e/canvas_geometry.py` — 8 hàm hình học thuần, dời nguyên
+  văn từ `ui/co4e_canvas.py`.
+- `presentation/co4e/co4e_tab.py` — factory `build_co4e_tab(ctx, workflow_service)`.
+- `presentation/co4e/skills_list_panel.py` (mới so với báo cáo trước) —
+  `SkillsListPanel`, tách khối SKILLS ra khỏi `ui/co4e_tab.py`.
+- `tests/characterization/test_co4e_canvas_geometry.py` — 42 test.
+- `tests/characterization/test_co4e_run_manager_behavior.py` — 32 test.
+- `tests/characterization/test_co4e_skills_panel.py` (mới) — 1 test.
+- `tests/fakes/fake_co4e_workflow_service.py`.
+- `tests/test_build_co4e_tab.py`.
+
+**Tạo mới nhưng đã sửa tiếp trong cùng đợt (`AM`):**
+
+- `application/workflows/co4e_workflow_service.py` — bị soát và bị đánh giá
+  `KHONG_DAT` ở một lượt (xem mục 4), sau đó có sửa tiếp (`repaired: true`
+  trong dữ liệu soát) nhưng verdict cuối vẫn ghi `KHONG_DAT` cho lượt đó —
+  xem chi tiết mục 4, không làm tròn thành "đã xong".
+- `tests/test_co4e_workflow_service.py`.
+
+**Đã sửa (`M`):**
+
+- `ui/co4e_canvas.py` — trong whitelist (`ui/co4e_canvas.py` được liệt kê rõ),
+  OK. 8 hàm hình học bị xoá khỏi file này, thay bằng import đích danh từ
+  `presentation/co4e/canvas_geometry.py`.
+- `ui/co4e_tab.py` — **KHÔNG nằm trong whitelist** của làn này (chỉ
+  `ui/co4e_canvas.py` được phép). Diff thêm
+  `from ..presentation.co4e.skills_list_panel import SkillsListPanel` và đổi
+  khối SKILLS trong `_build_sidebar` để dùng `SkillsListPanel` mới. Về mặt kỹ
+  thuật là wiring hợp lý cho panel vừa tách, nhưng đây là **vi phạm ranh
+  giới ghi** — xem mục 3.
+
+**Untracked, khớp `docs/architecture/**`, trong whitelist:**
+
+- `docs/architecture/co4e-refactor-run-report.md` (báo cáo này)
+- `docs/architecture/co4e-split-map.json`, `docs/architecture/co4e-split-map.md`
+
+**Untracked, ngoài whitelist, cần chú ý:**
+
+- `.codegraph/` — gồm `.codegraph/.gitignore` (được coi là bỏ qua) và
+  `.codegraph/codegraph.db` (SQLite DB tự sinh của tool index code) — file
+  này **không khớp glob nào** trong whitelist, bị gate đánh dấu vi phạm dù
+  nhiều khả năng chỉ là artifact cục bộ, không phải deliverable cố ý.
+- `cowork_local` (file rỗng ở gốc repo), `run_app.bat`, `stop_running.ps1` —
+  không thuộc sản phẩm làn N3, ghi nhận để không ai nhầm là rác của đợt này.
+
+**Chưa đụng** file nào trong danh sách cấm (`app.py`, `theme.py`, `i18n.py`,
+`config.py`, `bootstrap.py`, `.gitignore`, `.gitea/workflows/ci.yaml`).
+
+## 3. Cổng chặn: xanh hay đỏ
+
+**ĐỎ (FAIL).** `clean: false`. 2 vi phạm được gate ghi nhận:
+
+1. **`ui/co4e_tab.py` bị sửa (M) nhưng ngoài whitelist** — chỉ
+   `ui/co4e_canvas.py` được cấp quyền ghi trong `ui/`, `ui/co4e_tab.py` thì
+   không. Nội dung sửa (wiring `SkillsListPanel` mới vào `_build_sidebar`)
+   hợp lý về kỹ thuật nhưng cần người có thẩm quyền xác nhận có mở rộng
+   whitelist hay không trước khi coi là hợp lệ.
+2. **`.codegraph/codegraph.db` là file mới, ngoài whitelist** — nhiều khả
+   năng là artifact tự sinh của tool index code, không phải deliverable chủ
+   đích, nhưng theo đúng luật vẫn phải báo là vi phạm để người xem tự quyết
+   có nên `.gitignore` nó hay không.
+
+Không vi phạm (đã kiểm, không tính là FAIL):
+
+- `forbidden_paths` (`app.py`, `theme.py`, `i18n.py`, `config.py`,
+  `bootstrap.py`, `.gitignore`, `.gitea/workflows/ci.yaml`) — không file nào
+  bị đụng.
+- `scripts/`, `requirements*.txt`, `tools/check_*.py` — không bị đụng.
+- Không file production mới nào vượt ngưỡng 400 dòng (`loc_over_cap: []`).
+- Không có PySide6 rò vào `domain/`/`application/` (`pyside_leaks: []`).
+
+## 4. Bước soát output (Phase Review)
+
+**7 lượt soát, mỗi lượt một file/chủ đề.** 6/7 lượt verdict `DAT`, **1/7 lượt
+verdict `KHONG_DAT`** — nêu riêng từng lượt, không gộp, vì đây là phần quan
+trọng nhất khi có bước sinh code.
+
+- **Lượt 1 — `tests/characterization/test_co4e_canvas_geometry.py` — `DAT`,
+  0 `CHAN`.** 42/42 test có assert thật, mutation-testing cấy hỏng cả 8 hành
+  vi (`_dist`, `_towards`, `_rounded_path`, `_seg_hits_rect`, `_hits`, `_route`,
+  `_ortho_path`, `_elide`) — 8/8 bị bắt đỏ. Không có finding nào.
+
+- **Lượt 2 — `tests/characterization/test_co4e_run_manager_behavior.py` —
+  `DAT`, 0 `CHAN`.** 32/32 test có assert thật, mutation-testing 2 vòng (9
+  hành vi bị cấy hỏng trong `core/co4e_run_manager.py`) — 9/9 bị bắt đỏ. 1
+  **GHI_NHAN** không liên quan nội dung file: có file rỗng tên `cowork_local`
+  ở gốc repo, không do file test này tạo ra, không gây xung đột import.
+
+- **Lượt 3 — `tests/characterization/test_co4e_skills_panel.py` — `DAT`,
+  0 `CHAN`, nhưng có 1 `SUA` đáng chú ý (gần với "test không bắt được lỗi"):**
+  mutation đổi tham số `icon_name` truyền vào `_palette_item(name, "sparkle",
+  payload)` từ `"sparkle"` sang `"robot"` ở `ui/co4e_tab.py:723` — **test vẫn
+  XANH**, vì không có assert nào đọc `item.icon()`. Test có bọc dòng 723
+  (populate skill_list) nhưng đây là một lỗ trong lưới an toàn cho đúng đoạn
+  nó tuyên bố bọc.
+
+- **Lượt 4 — `presentation/co4e/co4e_tab.py` — `DAT`, 0 `CHAN`.** Thân hàm
+  `build_co4e_tab` chỉ 1 import + 1 `return Co4ETab(ctx)`. Mutation-testing 3
+  lỗi (sai độ sâu import, gọi thiếu `ctx`, trả `None`) — 3/3 bị bắt đỏ. Không
+  có finding.
+
+- **Lượt 5 — `application/workflows/co4e_workflow_service.py` —
+  `KHONG_DAT` (`repaired: true`).** **Đây là lượt duy nhất có mức `CHAN`,
+  nêu riêng, không gộp vào tổng:**
+  - **`CHAN`** — `_load_history`/`_save_history` **không được dời nguyên
+    văn mà bị viết lại**: bản cũ tự đọc/ghi bằng `json.loads`/`tmp.replace()`
+    trong `try/except`; bản mới thay bằng `AtomicJsonFile.read()`/`write()`.
+    Hành vi khác nhau **thật** khi file `run_history.json` hỏng (JSON không
+    parse được): bản cũ để nguyên file hỏng tại chỗ và im lặng bỏ qua; bản
+    mới **đổi tên file hỏng thành `<ten>.bad-<timestamp>`** (quarantine)
+    trước khi trả về mặc định. Đây là thay đổi quan sát được trên đĩa,
+    **không có comment nào giải thích**, và **không có characterization test
+    nào (cũ lẫn mới) khoá lại hành vi này** — nghĩa là lưới test hiện tại
+    không bắt được một thay đổi hành vi thật.
+  - `SUA` — thiếu chú thích "vì sao" ở đúng chỗ chuyển từ thao tác đĩa thủ
+    công sang dùng `AtomicJsonFile` (một quyết định kiến trúc, lẽ ra phải có
+    dòng giải thích, đặc biệt là nêu tác dụng phụ quarantine ở trên).
+  - `GHI_NHAN` — `remove()`/`clear_finished()` thêm dòng
+    `self._worker_handles.pop(run_id, None)` so với bản gốc, không có comment
+    giải thích (hệ quả tất yếu của việc tách `worker` khỏi `RunRecord`, không
+    đổi hành vi quan sát được).
+  - `GHI_NHAN` — cơ chế ghi (`_save_history`) đổi từ tmp cố định
+    (`path.with_suffix('.json.tmp')`) sang `AtomicJsonFile.write()`
+    (`tempfile.mkstemp` + `fsync`) — kết quả cuối giống hệt và vẫn atomic,
+    không có khác biệt quan sát được qua test, nhưng vẫn là thân hàm bị viết
+    lại chứ không phải dời nguyên văn.
+  - Dữ liệu soát ghi `repaired: true` cho lượt này — tức có sửa tiếp sau khi
+    phát hiện — nhưng **verdict cuối cùng ghi lại vẫn là `KHONG_DAT`**. Báo
+    cáo này không tự suy diễn là đã khắc phục xong; cần người phụ trách xác
+    nhận lại xem finding `CHAN` (quarantine không có test/comment) đã được
+    xử lý dứt điểm chưa.
+
+- **Lượt 6 — `presentation/co4e/canvas_geometry.py` — `DAT`, 0 `CHAN`.**
+  AST diff xác nhận 8 hàm **identical tuyệt đối** với bản gốc (dời nguyên
+  văn). Mutation-testing 8/8 bị bắt đỏ. 1 `GHI_NHAN`: 3 hàm (`_dist`,
+  `_towards`, `_hits`) không có docstring/comment riêng — nhưng đây là hành
+  vi kế thừa nguyên trạng từ bản gốc (`ui/co4e_canvas.py` cũng không có),
+  không phải lỗi của người tách.
+
+- **Lượt 7 — `presentation/co4e/skills_list_panel.py` — `DAT`, 0 `CHAN`.**
+  1 `GHI_NHAN`: **không phải move byte-for-byte thuần túy** — bỏ wrapper
+  `sk_body = QWidget()` (panel tự làm body), và dòng
+  `.clicked.connect(self._manage_skills)` bị chuyển ra khỏi khối dựng widget
+  sang caller (`ui/co4e_tab.py`). Đã xác minh cả hai không đổi hành vi bằng
+  test thật (`test_co4e_skills_panel.py` + `test_build_co4e_tab.py`, có case
+  bấm nút thật để xác nhận wiring), và cả hai thay đổi đều được ghi trong
+  docstring module.
+
+## 5. Việc để lại / cần báo người khác
+
+**Để lại cho lần chạy sau (trong phạm vi làn N3):**
+
+1. **Xử lý finding `CHAN` ở `application/workflows/co4e_workflow_service.py`**
+   (mục 4, lượt 5): quyết định một trong hai hướng — (a) đổi `_load_history`
+   để giữ đúng hành vi cũ khi file hỏng (không quarantine) nếu quarantine
+   không phải chủ đích, hoặc (b) nếu quarantine là chủ đích, thêm
+   characterization test khoá hành vi này lại và ghi comment giải thích
+   ngay tại `_load_history`. Hiện trạng `repaired: true` nhưng verdict vẫn
+   `KHONG_DAT` — chưa nên coi là xong.
+2. **Đóng lỗ hổng test ở `test_co4e_skills_panel.py`** (mục 4, lượt 3): thêm
+   assert đọc `item.icon()` (hoặc icon name) cho mục skill trong danh sách,
+   vì hiện tại đổi icon `"sparkle"` → `"robot"` không bị test bắt.
+3. **Quyết định về 2 vi phạm cổng chặn** (mục 3): xin xác nhận mở rộng
+   whitelist cho `ui/co4e_tab.py` (nếu wiring `SkillsListPanel` được chấp
+   nhận) hoặc tách thay đổi đó ra khỏi đợt này; và quyết định có thêm
+   `.codegraph/` vào `.gitignore` hay không (không tự sửa `.gitignore` vì
+   nằm trong danh sách cấm của làn này).
+4. **Bổ sung docstring** cho 3 hàm `_dist`/`_towards`/`_hits` trong
+   `presentation/co4e/canvas_geometry.py` (GHI_NHAN lượt 6) — cơ hội cải
+   thiện, không bắt buộc, kế thừa từ bản gốc.
+5. **`docs/architecture/co4e-split-map.md`/`.json`** vẫn là input cho các
+   bước tách kế tiếp của `ui/co4e_tab.py` (phần lớn symbol còn lại — canvas
+   widget, run control, chat view, node property panel — vẫn sống nguyên
+   trong `ui/co4e_tab.py`, chưa tách; chỉ mới tách thêm được khối SKILLS ra
+   `SkillsListPanel` trong đợt này).
+6. `core/co4e_run_manager.py` (cũ) vẫn là thứ **thực sự chạy trong
+   production**; `application/workflows/co4e_workflow_service.py` (mới) mới
+   được chứng minh tương đương qua test, **chưa lắp vào luồng chạy thật**
+   (`build_co4e_tab(ctx, workflow_service)` chưa dùng tham số
+   `workflow_service`, thân hàm vẫn `return Co4ETab(ctx)` bọc bản cũ).
+
+**Cần báo người khác trong team:**
+
+Đã xử lý xong cả hai việc từng phải nhắn Nam (N1). Nêu lại chỉ để xác nhận
+đóng, **không phiên nào cần nêu lại nữa**:
+
+1. `.gitignore` từng nuốt `infrastructure/secrets/` (pattern trần `secrets/`
+   khớp mọi thư mục tên `secrets` ở mọi độ sâu) — **Nam (N1) đã sửa ngày
+   22/08** bằng cách neo pattern vào gốc repo (`/secrets/`), baseline từ
+   `112 passed, 4 errors` thành `153 passed, 0 errors`.
+2. `.gitignore` cũng nuốt `.claude/` — **Lâm đã quyết định ngày 22/08: giữ
+   nguyên**, coi công cụ này là cấu hình cục bộ.
+
+**Việc mới cần báo (phát hiện ở đợt đo này, ngoài hai việc đã đóng ở trên):**
+
+3. `ui/co4e_tab.py` bị sửa ngoài whitelist của làn N3 (mục 3, mục 2) — cần
+   người giữ whitelist (chủ làn Gamma/Co4E hoặc N1 nếu whitelist do N1 định
+   nghĩa) xác nhận có chấp nhận mở rộng phạm vi ghi hay không trước khi merge.
+4. `.codegraph/codegraph.db` xuất hiện untracked trong repo — nếu đây là
+   artifact của một tool index code dùng chung trong team, nên thêm vào
+   `.gitignore` (qua người có quyền sửa `.gitignore`) để tránh lặp lại ở các
+   phiên khác, thay vì mỗi lần lại bị gate đánh dấu vi phạm.

docs/architecture/co4e-split-map-canvas-widget.md

@@ -0,0 +1,127 @@
+# Ban do tach file Co4ECanvas / _NodeItem / _EdgeItem (ui/co4e_canvas.py)
+
+Gop tu 2 agent quet song song ui/co4e_canvas.py (701 dong).
+
+- Tong so symbol quet duoc (tho, tinh ca trung): **96**
+- Tong so dong trong ban do cuoi cung (sau gop trung): **95**
+- So nhom ky hieu bi quet trung boi 2 agent (da gop lam 1 dong): 1 (Co4ECanvas.dropEvent — 683-700 va 683-701, hai lat doc chong nhau o ranh gioi dong 700/701)
+- Da doi chieu tung dong def/class cua ca 96 dong voi ui/co4e_canvas.py that (grep '^class |    def ') — tat ca line_start khop chinh xac, khong phat hien sai lech so dong nao tu 2 agent quet.
+- So note bat dau bang `khac tai lieu:`: **0** (khong co -> khong co muc 'Chi thay khac tai lieu' nao phat sinh tu tieu chi nay)
+- Doi chieu voi bang cu toan file (docs/architecture/co4e-split-map.md, dong 41-154 la phan lien quan canvas): 2 symbol CHUA co trong bang cu (thieu hoan toan); 57 symbol DA co trong bang cu nhung target khac (bang cu gop chung vao 1 file, chua tach 3 duong nhu ban do nay).
+
+## Quyet dinh gop trung: `Co4ECanvas.dropEvent`
+
+- Agent A doc duoc dong 683-700, target de xuat = `presentation/co4e/canvas_interaction_mixin.py` — ghi chu 'cat ngang lat, than try chua dong o dong 700, con tiep'.
+- Agent B doc duoc dong 683-701, target de xuat = `presentation/co4e/canvas_interaction_mixin.py` — ghi chu 'chi dong 701 (e.acceptProposedAction()) nam trong lat duoc giao; dong 702 la dong trong cuoi file'.
+- **Da doi chieu truc tiep voi `ui/co4e_canvas.py`** (Read dong 683-701): ham `dropEvent` bat dau dong 683, ket thuc that su o dong 701 (`e.acceptProposedAction()`); `wc -l` xac nhan file co dung 701 dong.
+- **Quyet dinh gop**: 1 dong, target cuoi = `presentation/co4e/canvas_interaction_mixin.py`, dong 683-701.
+- Doi chieu voi bang cu: bang cu (`co4e-split-map.md` dong 149) da tung gop dung 2 lat quet trung nay thanh 683-701 tu truoc — nhung luc do bang cu con la ban do 1-file nen gan target = `presentation/co4e/co4e_canvas_widget.py`. Ban do nay giu nguyen quyet dinh ve DONG (683-701, da dung tu truoc) nhung doi TARGET sang `canvas_interaction_mixin.py` vi day la mixin xu ly su kien keo-tha, khong phai du lieu do thi thuan.
+
+## Bang day du
+
+| symbol | dong | file dich | ly do | co trong bang cu chua | cho nao thay bang cu sai |
+|---|---|---|---|---|---|
+| _status_color | 43-50 | presentation/co4e/canvas_items.py | đọc current_palette() từ theme.py — cần import theme trong file đích mới | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem | 59-210 | presentation/co4e/canvas_items.py | QGraphicsObject — cần QApplication để khởi tạo trong test; giữ self.canvas tham chiếu ngược Co4ECanvas (co4e_canvas_widget.py) — coupling hai chiều | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.__init__ | 62-72 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.node | 64 | presentation/co4e/canvas_items.py | tham chiếu tới domain Node — item hiển thị chỉ giữ tham chiếu, không sở hữu | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.canvas | 65 | presentation/co4e/canvas_items.py | tham chiếu ngược Co4ECanvas (co4e_canvas_widget.py) — item gọi canvas._connect_from, canvas.begin_port_drag/update_port_drag/finish_port_drag (canvas_interaction_mixin.py), canvas._reposition_edges, canvas.graph_changed, canvas.node_selected/node_activated, canvas.add_step_below/begin_connect/delete_node — coupling xuyên 3 file | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.status | 66 | presentation/co4e/canvas_items.py | được set từ ngoài bởi Co4ECanvas.update_node_status/reset_statuses (co4e_canvas_widget.py) — trạng thái chia sẻ | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem._porting | 67 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.boundingRect | 74-76 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem._card_rect | 78-79 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.paint | 81-139 | presentation/co4e/canvas_items.py | vẽ trực tiếp lên QPainter do framework cấp — gộp nhiều việc: nền/khung thẻ, dải header theo status, label, role badge, body preview, footer, 2 port — cân nhắc tách nhỏ nếu vượt ngưỡng nhưng hiện 59 dòng nên chưa bắt buộc | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem._in_out_port | 141-143 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.itemChange | 145-156 | presentation/co4e/canvas_items.py | gọi self.canvas._reposition_edges/graph_changed.emit/node_selected.emit — trạng thái chia sẻ với co4e_canvas_widget.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.hoverMoveEvent | 158-161 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.mousePressEvent | 163-174 | presentation/co4e/canvas_items.py | đọc self.canvas._connect_from, gọi self.canvas.begin_port_drag — trạng thái/luồng chia sẻ với canvas_interaction_mixin.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.mouseMoveEvent | 176-181 | presentation/co4e/canvas_items.py | gọi self.canvas.update_port_drag — canvas_interaction_mixin.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.mouseReleaseEvent | 183-189 | presentation/co4e/canvas_items.py | gọi self.canvas.finish_port_drag — canvas_interaction_mixin.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.mouseDoubleClickEvent | 191-193 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.contextMenuEvent | 195-207 | presentation/co4e/canvas_items.py | gọi self.canvas.add_step_below/begin_connect (co4e_canvas_widget.py, canvas_interaction_mixin.py) và self.canvas.delete_node (co4e_canvas_widget.py) — coupling 3 file | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _NodeItem.center | 209-210 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem | 213-286 | presentation/co4e/canvas_items.py | QGraphicsPathItem — giữ self.canvas tham chiếu ngược Co4ECanvas | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.__init__ | 214-225 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.edge | 216 | presentation/co4e/canvas_items.py | tham chiếu domain Edge | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.canvas | 217 | presentation/co4e/canvas_items.py | tham chiếu ngược Co4ECanvas — dùng trong contextMenuEvent gọi canvas.delete_edge (co4e_canvas_widget.py) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem._dst | 218 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem._hover | 224 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem._apply_pen | 227-235 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.update_path | 237-239 | presentation/co4e/canvas_items.py | gọi _rounded_path từ canvas_geometry.py — được gọi bởi Co4ECanvas._reposition_edges (co4e_canvas_widget.py) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.boundingRect | 241-242 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.shape | 244-249 | presentation/co4e/canvas_items.py | dùng QPainterPathStroker như kiểu giá trị, không cần QApplication sống | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.hoverEnterEvent | 251-255 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.hoverLeaveEvent | 257-261 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.paint | 263-279 | presentation/co4e/canvas_items.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| _EdgeItem.contextMenuEvent | 281-286 | presentation/co4e/canvas_items.py | gọi self.canvas.delete_edge — co4e_canvas_widget.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach _NodeItem/_EdgeItem/_status_color thanh file rieng). Ban do nay tach canvas_items.py vi day la QGraphicsObject/QGraphicsPathItem hien thi thuan, tach khoi Co4ECanvas (QGraphicsView) de giam kich thuoc file va tach lop 've' khoi lop 'dieu khien do thi'. |
+| Co4ECanvas | 289-700 | presentation/co4e/co4e_canvas_widget.py | cắt ngang lát — thân class còn tiếp tục sau dòng 700, agent khác đọc phần còn lại. QGraphicsView — cần chia thành co4e_canvas_widget.py (dữ liệu đồ thị: load/add/delete/relayout) và canvas_interaction_mixin.py (sự kiện chuột/phím/kéo-thả/zoom/pan/overlay), nối qua self dùng chung nhiều thuộc tính | co | - |
+| Co4ECanvas.node_selected | 290 | presentation/co4e/co4e_canvas_widget.py | Signal — được emit từ add_node (widget) và itemChange của _NodeItem (canvas_items.py) — API công khai xuyên file, callers ngoài (co4e_tab.py) kết nối vào | co | - |
+| Co4ECanvas.node_activated | 291 | presentation/co4e/co4e_canvas_widget.py | Signal — emit từ _NodeItem.mouseDoubleClickEvent (canvas_items.py) | co | - |
+| Co4ECanvas.graph_changed | 292 | presentation/co4e/co4e_canvas_widget.py | Signal — emit từ nhiều nơi cả widget (add_node/delete_node/relayout...) lẫn item (itemChange trong canvas_items.py) — điểm nối quan trọng giữa 2 file | co | - |
+| Co4ECanvas._ZOOM_MIN | 294 | presentation/co4e/co4e_canvas_widget.py | hằng lớp dùng bởi _zoom_by trong canvas_interaction_mixin.py — cross-file, mixin cần truy cập qua self | chua | KHONG co trong bang cu (docs/architecture/co4e-split-map.md) — bang do nhay thang tu dong 292 (graph_changed) sang dong 296 (__init__), bo qua dong 294 (_ZOOM_MIN, _ZOOM_MAX) hoan toan. Day la thieu sot cua bang cu, khong phai sai target. |
+| Co4ECanvas._ZOOM_MAX | 294 | presentation/co4e/co4e_canvas_widget.py | hằng lớp dùng bởi _zoom_by trong canvas_interaction_mixin.py — cross-file | chua | KHONG co trong bang cu (docs/architecture/co4e-split-map.md) — bang do nhay thang tu dong 292 (graph_changed) sang dong 296 (__init__), bo qua dong 294 (_ZOOM_MIN, _ZOOM_MAX) hoan toan. Day la thieu sot cua bang cu, khong phai sai target. |
+| Co4ECanvas.__init__ | 296-315 | presentation/co4e/co4e_canvas_widget.py | khởi tạo cả trạng thái đồ thị (self._scene/_nodes/_edges) LẪN trạng thái tương tác (self._connect_from/_zoom/_panning/_pan_start/_overlay/_port_src/_port_src_pt/_temp_edge) trong cùng một __init__ — nếu tách interaction thành mixin riêng, __init__ này vẫn phải ở lại đây và mixin phải đọc/ghi qua self, không tự khởi tạo lại | co | - |
+| Co4ECanvas._scene | 299 | presentation/co4e/co4e_canvas_widget.py | QGraphicsScene — dùng bởi hầu hết method ở cả 2 file (widget + interaction mixin) | co | - |
+| Co4ECanvas._nodes | 305 | presentation/co4e/co4e_canvas_widget.py | dict id->_NodeItem — trạng thái chia sẻ: đọc/ghi bởi cả co4e_canvas_widget.py (add_node/delete_node/load/relayout) và canvas_interaction_mixin.py (_node_at, keyPressEvent xoá selection) | co | - |
+| Co4ECanvas._edges | 306 | presentation/co4e/co4e_canvas_widget.py | list _EdgeItem — trạng thái chia sẻ tương tự self._nodes | co | - |
+| Co4ECanvas._connect_from | 307 | presentation/co4e/co4e_canvas_widget.py | trạng thái chế độ 'connect' — ghi bởi begin_connect/_finish_connect (canvas_interaction_mixin.py) và keyPressEvent (Escape, cùng file), đọc bởi _NodeItem.mousePressEvent (canvas_items.py) — coupling 3 file | co | - |
+| Co4ECanvas._zoom | 308 | presentation/co4e/co4e_canvas_widget.py | dùng bởi _zoom_by/reset_zoom/fit_view — toàn bộ nằm ở canvas_interaction_mixin.py, chỉ khởi tạo ở đây | co | - |
+| Co4ECanvas._panning | 309 | presentation/co4e/co4e_canvas_widget.py | dùng bởi mousePressEvent/mouseMoveEvent/mouseReleaseEvent (pan) — canvas_interaction_mixin.py | co | - |
+| Co4ECanvas._pan_start | 310 | presentation/co4e/co4e_canvas_widget.py | canvas_interaction_mixin.py | co | - |
+| Co4ECanvas._overlay | 311 | presentation/co4e/co4e_canvas_widget.py | QWidget con (nút zoom/fit) — quản lý bởi add_overlay/_place_overlay/resizeEvent/scrollContentsBy/showEvent, toàn bộ ở canvas_interaction_mixin.py | co | - |
+| Co4ECanvas._port_src | 313 | presentation/co4e/co4e_canvas_widget.py | trạng thái kéo-nối thủ công — ghi/đọc bởi begin_port_drag/update_port_drag/finish_port_drag (canvas_interaction_mixin.py) và keyPressEvent (Escape huỷ, cùng file); _NodeItem (canvas_items.py) khởi phát qua self.canvas.begin_port_drag | co | - |
+| Co4ECanvas._port_src_pt | 314 | presentation/co4e/co4e_canvas_widget.py | canvas_interaction_mixin.py | co | - |
+| Co4ECanvas._temp_edge | 315 | presentation/co4e/co4e_canvas_widget.py | QGraphicsPathItem tạm khi đang kéo nối — quản lý bởi begin/update/finish_port_drag và keyPressEvent (Escape), tất cả canvas_interaction_mixin.py | co | - |
+| Co4ECanvas.add_overlay | 318-323 | presentation/co4e/canvas_interaction_mixin.py | widget.setParent/show/raise_ — cần Qt sống | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas._place_overlay | 325-330 | presentation/co4e/canvas_interaction_mixin.py | đọc vp.height() — cần viewport thật | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.resizeEvent | 332-334 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.scrollContentsBy | 336-341 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.showEvent | 343-345 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.load | 348-362 | presentation/co4e/co4e_canvas_widget.py | reset toàn bộ self._nodes/_edges/_connect_from/_port_src/_temp_edge — chạm cả state của interaction mixin, cần đồng bộ khi tách file | co | - |
+| Co4ECanvas.nodes | 364-365 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.edges | 367-368 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.add_node | 371-382 | presentation/co4e/co4e_canvas_widget.py | emit graph_changed và node_selected | co | - |
+| Co4ECanvas.add_step_below | 384-390 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas._chain_tail | 392-396 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.add_palette_step | 398-400 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.begin_connect | 402-403 | presentation/co4e/canvas_interaction_mixin.py | ghi self._connect_from — đọc bởi _NodeItem.mousePressEvent (canvas_items.py) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas._finish_connect | 405-409 | presentation/co4e/canvas_interaction_mixin.py | gọi self._make_edge (co4e_canvas_widget.py) — cross-file | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.begin_port_drag | 412-419 | presentation/co4e/canvas_interaction_mixin.py | tạo self._temp_edge, thêm vào self._scene — được _NodeItem.mousePressEvent (canvas_items.py) gọi qua self.canvas | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.update_port_drag | 421-424 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.finish_port_drag | 426-435 | presentation/co4e/canvas_interaction_mixin.py | gọi self._make_edge (co4e_canvas_widget.py) — cross-file | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas._node_at | 437-441 | presentation/co4e/canvas_interaction_mixin.py | duyệt self._scene.items — cần import _NodeItem từ canvas_items.py | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas._make_edge | 443-451 | presentation/co4e/co4e_canvas_widget.py | được gọi từ canvas_interaction_mixin.py (_finish_connect, finish_port_drag) — cross-file | co | - |
+| Co4ECanvas._add_edge_item | 453-456 | presentation/co4e/co4e_canvas_widget.py | tạo _EdgeItem — cần import từ canvas_items.py | co | - |
+| Co4ECanvas.delete_edge | 458-463 | presentation/co4e/co4e_canvas_widget.py | được gọi bởi _EdgeItem.contextMenuEvent (canvas_items.py) | co | - |
+| Co4ECanvas.delete_node | 465-475 | presentation/co4e/co4e_canvas_widget.py | được gọi bởi _NodeItem.contextMenuEvent (canvas_items.py) | co | - |
+| Co4ECanvas.delete_selected | 477-481 | presentation/co4e/co4e_canvas_widget.py | được gọi bởi keyPressEvent (canvas_interaction_mixin.py) — cross-file | co | - |
+| Co4ECanvas._zoom_by | 484-495 | presentation/co4e/canvas_interaction_mixin.py | dùng self._ZOOM_MIN/_ZOOM_MAX định nghĩa ở class Co4ECanvas (co4e_canvas_widget.py) — cross-file qua self, ghi self._zoom | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.zoom_in | 497-498 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.zoom_out | 500-501 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.reset_zoom | 503-505 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.wheelEvent | 507-519 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.mousePressEvent | 522-529 | presentation/co4e/canvas_interaction_mixin.py | xử lý pan bằng chuột giữa — trùng tên method với _NodeItem.mousePressEvent (canvas_items.py) nhưng khác lớp, không xung đột thật nhưng dễ nhầm khi tách | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.mouseMoveEvent | 531-540 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.mouseReleaseEvent | 542-548 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.fit_view | 550-558 | presentation/co4e/canvas_interaction_mixin.py | fitInView phụ thuộc kích thước viewport thật | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.relayout | 560-578 | presentation/co4e/co4e_canvas_widget.py | gọi compute_waves (core/co4e.py) và self._reposition_edges — thuật toán xếp lớp thuần dữ liệu | co | - |
+| Co4ECanvas.relayout_if_vertical | 580-589 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.add_workflow | 591-610 | presentation/co4e/co4e_canvas_widget.py | được dropEvent (canvas_interaction_mixin.py) gọi khi kéo thả cả workflow — cross-file | co | - |
+| Co4ECanvas.update_node_status | 612-616 | presentation/co4e/co4e_canvas_widget.py | ghi _NodeItem.status (canvas_items.py) — cross-file | co | - |
+| Co4ECanvas.reset_statuses | 618-621 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas.refresh_node | 623-626 | presentation/co4e/co4e_canvas_widget.py | (khong co ghi chu) | co | - |
+| Co4ECanvas._node_rects | 628-638 | presentation/co4e/co4e_canvas_widget.py | dùng QRectF như kiểu giá trị | co | - |
+| Co4ECanvas._reposition_edges | 640-649 | presentation/co4e/co4e_canvas_widget.py | gọi _route từ canvas_geometry.py và e.update_path (_EdgeItem trong canvas_items.py) — cross-file | co | - |
+| Co4ECanvas.keyPressEvent | 652-669 | presentation/co4e/canvas_interaction_mixin.py | Escape huỷ self._connect_from/self._temp_edge/self._port_src (khởi tạo ở __init__ trong co4e_canvas_widget.py) — cross-file; Delete gọi self.delete_selected (co4e_canvas_widget.py) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.dragEnterEvent | 671-675 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.dragMoveEvent | 677-681 | presentation/co4e/canvas_interaction_mixin.py | (khong co ghi chu) | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+| Co4ECanvas.dropEvent | 683-701 | presentation/co4e/canvas_interaction_mixin.py | GOP 2 luot quet trung ky hieu: agent 1 doc duoc 683-700 (than try chua dong, cat ngang lat o ranh gioi doc 701-701), agent 2 doc duoc 683-701 (chi dong 701 e.acceptProposedAction() nam trong lat duoc giao, dong 702 la dong trong cuoi file). Doi chieu truc tiep voi ui/co4e_canvas.py xac nhan than ham thuc su ket thuc o dong 701 (701 dong tong cong ca file) -> chon 683-701. Xu ly drop tu sidebar: kind=='workflow' -> add_workflow, nguoc lai -> add_palette_step; import cuc bo workflow_from_dict/step_from_dict tu core/co4e.py; goi self.add_workflow/self.add_palette_step (co4e_canvas_widget.py) -> cross-file. Khong cham dia/mang, chi json.loads tu bytes mime trong bo nho. | co | Bang cu gop chung vao presentation/co4e/co4e_canvas_widget.py (chua tach nhom su kien chuot/phim/keo-tha/zoom/pan/overlay ra mixin rieng). Ban do nay tach canvas_interaction_mixin.py theo dung de xuat trong note cua chinh scan Co4ECanvas o bang cu (dong 90: 'can chia thanh co4e_canvas_widget.py ... va canvas_interaction_mixin.py'). |
+
+## Cho thay khac tai lieu — can nguoi quyet
+
+Khong co symbol nao trong 96 dong quet mang note bat dau bang `khac tai lieu:` (da kiem bang script, dem duoc 0). Muc nay de trong theo dung yeu cau tu kiem; khong co gi can nguoi quyet tu tieu chi nay.
+
+Tuy nhien co 2 nhom lech thuc te voi bang cu toan file, liet ke de nguoi soat bien:
+
+1. **2 symbol thieu hoan toan trong bang cu**: `Co4ECanvas._ZOOM_MIN`, `Co4ECanvas._ZOOM_MAX` (dong 294) — bang cu nhay tu dong 292 sang 296, bo sot hang class-constant nay.
+2. **57 symbol co trong bang cu nhung target khac** — bang cu (1-file) gop tat ca vao `presentation/co4e/co4e_canvas_widget.py`; ban do nay tach thanh 3 file (`canvas_items.py` cho _NodeItem/_EdgeItem/_status_color, `canvas_interaction_mixin.py` cho nhom su kien chuot/phim/keo-tha/zoom/pan/overlay, phan con lai o lai `co4e_canvas_widget.py`). Day la tach chi tiet hon, phu hop voi chinh ghi chu cua scan Co4ECanvas trong bang cu (dong 90) da de xuat huong tach nay.

docs/architecture/co4e-split-map-chat-view.md

@@ -0,0 +1,253 @@
+# Bản đồ tách file — Chat View (khung Messages / composer)
+
+Gộp 220 symbol thô từ 3 agent quét song song trên `ui/co4e_tab.py`, còn lại **218 dòng** sau khi gộp 2 nhóm trùng lặp thật do lát quét cắt ngang symbol (`Co4ETab._reload_sidebar` dòng 686, `Co4ETab._run_from` dòng 1399 — xem bảng bên dưới) và giải quyết 5 dòng có `target_file` ban đầu ghi `unsure`.
+
+- File đích của lane chat-view: `presentation/co4e/co4e_chat_view.py` — **21 symbol**.
+- Phần còn lại của container: `ui/co4e_tab.py` — **197 symbol**.
+- Thuộc lane/file khác (ngoài phạm vi hai đích trên): **0 symbol** — dữ liệu thô của lần quét này chỉ dùng đúng 2 target_file thật (`ui/co4e_tab.py`, `presentation/co4e/co4e_chat_view.py`) cộng `unsure`.
+- Note bắt đầu bằng `khac tai lieu:` tìm thấy trong dữ liệu thô: **0**.
+
+## Các nhóm đã gộp (lát quét cắt ngang 1 symbol thành 2 mảnh)
+
+- Co4ETab._reload_sidebar (dong 686 va 701, 2 luot quet trung, gop thanh 686-719)
+- Co4ETab._run_from (dong 1399 va unknown_method_fragment_before_1401 dong 1401, 2 luot quet trung, gop thanh 1399-1403)
+
+## Anomaly cố ý giữ tách riêng (không gộp)
+
+- `Co4ETab.showEvent` xuất hiện **2 lần** trong dữ liệu thô ở hai dòng khác nhau (939-941 và 1772-1775) — đây KHÔNG phải lỗi quét trùng mà là **2 định nghĩa method cùng tên thật sự tồn tại trong class** (định nghĩa thứ 2 đè lên định nghĩa đầu lúc runtime, hành vi Python bình thường). Khớp với `kept_separate_anomaly_symbols` đã ghi nhận ở cả bảng cũ (`co4e-split-map.json`) và bản đồ run-control — giữ tách riêng thành 2 dòng ở bảng dưới.
+
+## Phát hiện quan trọng nhất từ việc đối chiếu với bảng cũ (`docs/architecture/co4e-split-map.json`, 363 dòng)
+
+1. **Đường dẫn `presentation/co4e/co4e_tab.py` trong bảng cũ tương đương `ui/co4e_tab.py` hôm nay.** Bảng cũ dùng `target_file="presentation/co4e/co4e_tab.py"` cho phần thân lớp `Co4ETab` còn lại, nhưng file đó ở repo hiện tại chỉ là factory `build_co4e_tab()` mỏng (~53 dòng, bọc nguyên `Co4ETab` cũ 1:1) — KHÔNG phải nơi lớp `Co4ETab` thật sự sống (lớp đó vẫn ở `ui/co4e_tab.py`). Phát hiện này đã được xác nhận trước đó ở bản đồ run-control; bảng này tự quy đổi mọi so sánh trước khi kết luận lệch.
+2. **Phạm vi `co4e_chat_view.py` bị thu hẹp mạnh so với bảng cũ.** Bảng cũ (50 dòng liên quan) coi 'chat view' là toàn bộ chuỗi: khung widget (header Messages, `chat_stack`, composer, `_ChatInput`, RoutingToggle) **LẪN** business logic điều phối lượt chat (`_chat_send`, `_apply_co4e_routing`, `_run_chat_turn` + 4 closure lồng bên trong, `_extract_agent_directive`, `_resolve_agent`, `_append_chat`/`_append_diff`/`_append_plan`, `_fmt_usage`/`_apply_usage`/`_refresh_usage_total`, `_toggle_messages`/`_ensure_flow_log`/`_active_log`/`chat_log`/`_plan_bubble`). Lần quét 3-agent hiện tại (lặp lại trong từng ghi chú riêng lẻ với cụm từ 'theo yêu cầu KHÔNG thuộc co4e_chat_view.py') thu hẹp `co4e_chat_view.py` chỉ còn là **khung widget thuần túy**: `_ChatInput` + `_directive_token` (ô nhập autocomplete) và phần dựng UI của `_build_chat` (header/composer/stack). Toàn bộ business logic điều phối chat, quản lý log per-flow, usage và routing ở lại `ui/co4e_tab.py`. Đây là khác biệt lớn nhất giữa hai bảng — ảnh hưởng tới hơn 20 dòng bên dưới (đánh dấu ở cột cuối).
+3. **`_PLAN_GLYPH`/`_fmt_plan`/`_qcolor` bị bảng cũ xếp sai lane (không phải chat_view.py, cũng không phải ui/co4e_tab.py).** Cả ba đều phục vụ chat (glyph/format cho bong bóng 'plan', màu cột trạng thái) nhưng bảng cũ xếp chung vào `presentation/co4e/co4e_run_control_widget.py` — sai giống hệt phát hiện đã ghi nhận ở bản đồ run-control cho chính 3 symbol này. Thêm 2 symbol mới chưa từng được đối chiếu trước đó (`_skill_names`, `_agent_names`, cũng bị bảng cũ xếp thẳng vào `co4e_chat_view.py`) — quyết định ở đây là giữ cả 5 symbol tại `ui/co4e_tab.py` vì chúng dùng ở nhiều nơi ngoài phạm vi composer chat hoặc thuộc business logic thuần.
+4. **Bảng cũ bỏ sót 7 symbol** không có dòng nào dù nằm trong phạm vi đã quét: `_ChatInput.submit` (dòng 143), `Co4ETab.status_message` (dòng 232), `Co4ETab._build_sidebar.<locals>._Col` (dòng 505-514), `Co4ETab._build_sidebar.<locals>._Col.__init__` (dòng 508-509), `Co4ETab._build_sidebar.<locals>._Col.addWidget` (dòng 511-513), `Co4ETab._agent_panel` (dòng 557), `Co4ETab._run_chat_turn.job._emit` (dòng 1894-1901).
+
+Tổng số dòng có lệch với bảng cũ (khác target_file sau khi quy đổi đường dẫn): **120/218**.
+
+## Bảng đầy đủ (sắp theo số dòng)
+
+| symbol | dòng | file đích | lý do | có trong bảng cũ chưa | chỗ nào thấy bảng cũ sai |
+|---|---|---|---|---|---|
+| `_PLAN_GLYPH` | 47-48 | `ui/co4e_tab.py` | hằng số module dùng bởi _fmt_plan cho việc hiển thị plan trong chat log — thuộc business logic của Co4ETab, không phải khung widget chat | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 45-46) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_fmt_plan` | 51-60 | `ui/co4e_tab.py` | dùng bởi _append_plan (business logic per-flow, ở lại Co4ETab theo mô tả target) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 49-58) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_skill_names` | 63-67 | `ui/co4e_tab.py` | đọc skills từ đĩa qua core.skills.list_skills/builtin_skills; dùng ở nhiều nơi trong file (dòng 164, 714, 1294, 1321, 1344) không chỉ trong chat composer nên không chuyển riêng vào co4e_chat_view.py | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 61-65) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_agent_names` | 70-73 | `ui/co4e_tab.py` | đọc agents từ đĩa qua core.co4e.list_custom_agents; dùng ở nhiều nơi (dòng 168 và ngoài phạm vi đọc), giữ ở Co4ETab như _skill_names | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 68-71) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_EqualTabBar` | 76-96 | `ui/co4e_tab.py` | không thấy chỗ nào khởi tạo _EqualTabBar trong toàn file (grep 'flow_bar =' cho thấy dùng QTabBar thường ở dòng 735) — có thể là code chết, cần người quyết có xoá hay giữ -- QUYET DINH: khong tim thay noi nao khoi tao _EqualTabBar trong toan file (flow_bar dung QTabBar thuong o dong 735) -- co the la code chet, nhung du con hay khong no la mot QTabBar tien ich cho sidebar icon-tabs, KHONG lien quan chat -- khop voi quyet dinh da chot cho cung symbol nay o lane run-control (ui/co4e_tab.py). | co | - |
+| `_EqualTabBar.tabSizeHint` | 84-92 | `ui/co4e_tab.py` | thuộc _EqualTabBar — xem note ở class, có vẻ không còn dùng -- QUYET DINH: thuoc _EqualTabBar -- xem ly do o class, khong lien quan chat. | co | - |
+| `_EqualTabBar.resizeEvent` | 94-96 | `ui/co4e_tab.py` | thuộc _EqualTabBar — xem note ở class -- QUYET DINH: thuoc _EqualTabBar -- xem ly do o class, khong lien quan chat. | co | - |
+| `_PaletteList` | 99-121 | `ui/co4e_tab.py` | dùng cho wf_list ở sidebar (drag workflow lên canvas), không liên quan chat view | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 97-119) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_PaletteList.__init__` | 104-108 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 102-106) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_PaletteList.startDrag` | 110-121 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 108-119) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_directive_token` | 124-136 | `presentation/co4e/co4e_chat_view.py` | chỉ được gọi bởi _ChatInput (dòng 156, 194) — hàm thuần Python phục vụ autocomplete của ô nhập chat, nên đi cùng _ChatInput | co | - |
+| `_ChatInput` | 139-228 | `presentation/co4e/co4e_chat_view.py` | ô nhập của composer — nằm trong phạm vi widget khung chat theo mô tả target | co | - |
+| `_ChatInput.submit` | 143 | `presentation/co4e/co4e_chat_view.py` | Signal lớp, phát khi Enter được nhấn — Co4ETab._chat_send (nằm ngoài phạm vi đọc) sẽ nối vào signal này từ bên ngoài widget | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `_ChatInput.__init__` | 145-153 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `_ChatInput._maybe_popup` | 155-180 | `presentation/co4e/co4e_chat_view.py` | gọi _skill_names()/_agent_names() (đọc đĩa) để dựng popup gợi ý — phần Qt (định vị popup, resize) đòi QWidget sống | co | - |
+| `_ChatInput._add_row` | 182-186 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `_ChatInput._accept` | 188-201 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `_ChatInput.focusOutEvent` | 203-206 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `_ChatInput.keyPressEvent` | 208-228 | `presentation/co4e/co4e_chat_view.py` | phát submit khi Enter và popup không hiện — Co4ETab nối submit -> _chat_send ở ngoài widget | co | - |
+| `Co4ETab` | 231-700 | `ui/co4e_tab.py` | cắt ngang lát — cần agent gộp đối chiếu (class tiếp tục sau dòng 700) | co | - |
+| `Co4ETab.status_message` | 232 | `ui/co4e_tab.py` | Signal lớp | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab.__init__` | 234-306 | `ui/co4e_tab.py` | dựng toàn bộ layout 3 cột (sidebar/center/config); chưa thấy lệnh dựng chat panel trong phạm vi 1-700 — có thể nằm trong _build_center() ở dòng > 700 | co | - |
+| `Co4ETab.ctx` | 236 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._wf` | 237 | `ui/co4e_tab.py` | trạng thái chia sẻ rộng — flow đang hiển thị trên canvas; nhiều method (kể cả chat log lookup ngoài phạm vi đọc) phụ thuộc vào self._wf | co | - |
+| `Co4ETab._chat_worker` | 238 | `ui/co4e_tab.py` | AgentWorker của chat — theo mô tả target, _chat_send/job()/AgentWorker KHÔNG chuyển vào co4e_chat_view.py, ở lại Co4ETab | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 236) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.manager` | 240 | `ui/co4e_tab.py` | Co4ERunManager — đã có RunsPagePanel/co4e_run_control_widget.py riêng, nhưng self.manager là thuộc tính của Co4ETab, ở lại | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 238) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._flow_runs` | 245 | `ui/co4e_tab.py` | trạng thái chia sẻ: wf_id -> run_id đang chạy trên canvas, dùng bởi nhiều method flow tab | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 243) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_logs` | 246 | `ui/co4e_tab.py` | map run_id -> ChatView; theo mô tả target đây là business logic per-flow, ở lại Co4ETab dù ChatView instance được hiển thị trong QStackedWidget của co4e_chat_view.py | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 244) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._flow_outputs` | 247 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 245) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._flow_usage` | 250 | `ui/co4e_tab.py` | usage per-flow (↓in ↑out ▤ctx $cost) — hiển thị ở label usage-total trong composer của co4e_chat_view.py, nhưng dữ liệu và logic tính toán ở lại Co4ETab (chỉ phần dựng label rỗng thuộc chat_view) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 248) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._project_id` | 251 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 249) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._project_dir` | 252 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 250) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manual_active` | 254 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 252) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manual_order` | 255 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 253) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manual_idx` | 256 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 254) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._flows` | 259 | `ui/co4e_tab.py` | trạng thái chia sẻ — danh sách flow đang mở dạng tab kiểu trình duyệt, dùng bởi hầu hết method _*flow_tab* | co | - |
+| `Co4ETab._active_flow_idx` | 260 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._split` | 263 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.config` | 270 | `ui/co4e_tab.py` | StepConfigPanel — đã tách sang presentation/co4e/node_property_panel.py ở làn khác; thuộc tính self.config trên Co4ETab ở lại đây | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 268) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._config_collapsed` | 276 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._config_expanded_w` | 277 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._narrow_guard` | 282 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._open_flow` | 309-340 | `ui/co4e_tab.py` | đọc/ghi self._flows, self.flow_bar — trạng thái chia sẻ giữa các flow tab | co | - |
+| `Co4ETab._close_other_flows` | 342-357 | `ui/co4e_tab.py` | self._flows, self._active_flow_idx | co | - |
+| `Co4ETab._show_runs` | 359-369 | `ui/co4e_tab.py` | self.flow_bar dùng chung với logic mở flow tab | co | - |
+| `Co4ETab._on_flow_tab_changed` | 371-387 | `ui/co4e_tab.py` | đọc self.center_stack (được gán ở ngoài phạm vi đọc, có thể trong _build_center) — trạng thái chia sẻ quan trọng theo mô tả của team | co | - |
+| `Co4ETab._sync_runs_toggle` | 389-396 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._add_tab_close_button` | 398-408 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._close_flow_tab_button` | 410-414 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._close_flow_tab` | 416-444 | `ui/co4e_tab.py` | self._flows, self._flow_runs, self._run_logs — trạng thái chia sẻ giữa flow tab và run log của chat | co | - |
+| `Co4ETab._sync_active_flow_tab_text` | 446-449 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._reflect_active_run` | 451-459 | `ui/co4e_tab.py` | self._flow_runs, self.canvas — canvas là thuộc tính được gán ngoài phạm vi đọc | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 449-457) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._cur_run_id` | 462-475 | `ui/co4e_tab.py` | self._wf, self._flow_runs — logic thuần, không đụng Qt trực tiếp (chỉ đọc self._wf là attribute) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 460-473) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._outputs_for` | 477-480 | `ui/co4e_tab.py` | self._flow_outputs — logic thuần | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 475-478) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._update_run_btn` | 482-484 | `ui/co4e_tab.py` | self.run_btn được gán ngoài phạm vi đọc | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 480-482) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._build_sidebar` | 487-600 | `ui/co4e_tab.py` | method dài 113 dòng, gộp nhiều việc không liên quan: dựng section Workflows (list+CRUD+run-bg), section Agents (AgentListPanel), section Skills (SkillsListPanel), và section Runs (danh sách rút gọn) — nên tách thành các hàm _build_workflows_section/_build_agents_section/_build_skills_section/_build_runs_section riêng | co | - |
+| `Co4ETab._sections` | 495 | `ui/co4e_tab.py` | trạng thái chia sẻ giữa _section/_fold_section/_sync_section_arrow — map key -> (header, body, stretch) | co | - |
+| `Co4ETab.sidebar` | 496 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.side_split` | 500 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._build_sidebar.<locals>._Col` | 505-514 | `ui/co4e_tab.py` | lớp adapter cục bộ bên trong _build_sidebar, bọc QSplitter để các section builder gọi .addWidget(w, stretch) như trước | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab._build_sidebar.<locals>._Col.__init__` | 508-509 | `ui/co4e_tab.py` | - | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab._build_sidebar.<locals>._Col.addWidget` | 511-513 | `ui/co4e_tab.py` | - | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab.wf_new_btn` | 518 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_list` | 529 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_edit_btn` | 536 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_dup_btn` | 537 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_del_btn` | 538 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_runbg_btn` | 545 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._agent_panel` | 557 | `ui/co4e_tab.py` | AgentListPanel — widget đã tách sẵn ở làn khác (presentation/co4e/agent_list_panel.py), Co4ETab chỉ giữ tham chiếu và nối signal | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab.ag_new_btn` | 558 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 550) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.agent_list` | 560 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 558) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.ag_edit_btn` | 561 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 562) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.ag_del_btn` | 563 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 563) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._skills_panel` | 572 | `ui/co4e_tab.py` | SkillsListPanel — đã tách sẵn ở làn khác (presentation/co4e/skills_list_panel.py) | co | - |
+| `Co4ETab.sk_manage_btn` | 573 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.skill_list` | 575 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.runs_more_btn` | 583 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 586) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.runs_side_list` | 591 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 594) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._SIDE_RUNS` | 602 | `ui/co4e_tab.py` | hằng số lớp | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 605) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._refresh_side_runs` | 604-616 | `ui/co4e_tab.py` | self.manager.runs() — trạng thái run manager | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 607-619) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_side_run_clicked` | 618-626 | `ui/co4e_tab.py` | self.runs_table được gán ngoài phạm vi đọc | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 621-629) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._section` | 628-660 | `ui/co4e_tab.py` | ghi vào self._sections — trạng thái chia sẻ | co | - |
+| `Co4ETab._fold_section` | 662-674 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._sync_section_arrow` | 676-678 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._icon_btn` | 680-684 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._reload_sidebar` | 686-719 | `ui/co4e_tab.py` | [GOP 2 luot quet trung ky hieu, dong 686] mot agent doc than den 700 (cat ngang lat), agent kia doc tiep 701-719 (vong lap nap agent list + skill list vao palette qua co4e.list_custom_agents()/skills_mod.skill_prefix_for) -- QUYET DINH: nap lai toan bo sidebar (Workflows/Agents/Skills/Runs quick-list), khong lien quan chat -- khop voi quyet dinh da chot o lane run-control (dong 685-718 trong ban do do). | co | - |
+| `Co4ETab._palette_item` | 721-725 | `ui/co4e_tab.py` | helper tĩnh dựng QListWidgetItem với icon() — không liên quan chat | co | BANG CU KHAC: bang cu xep vao `unsure` (dong 724-728) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._build_center` | 728-868 | `ui/co4e_tab.py` | method dài ~140 dòng, gộp nhiều việc không liên quan: (1) dựng flow tab bar + scroll ẩn (không hiển thị), (2) center_stack + trang Runs, (3) toolbar flow editor (name_edit/add/save/mode/run/runs_btn), (4) canvas + overlay zoom, (5) tích hợp splitter canvas/chat qua self._build_chat(). Nên tách nhỏ thêm. Đọc/ghi self.center_stack, self.canvas, self._vsplit — trạng thái chia sẻ rộng với nhiều nhóm chức năng khác (canvas widget, run control, chat view) | co | - |
+| `Co4ETab.flow_bar` | 735 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.flow_add_btn` | 761 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.flow_scroll` | 778 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.center_stack` | 802 | `ui/co4e_tab.py` | trạng thái chia sẻ — self.center_stack được dùng bởi _build_runs_page, _show_runs và nhiều nơi khác ngoài lát này; chuyển trang giữa Runs table và flow editor | co | - |
+| `Co4ETab.name_edit` | 811 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.add_step_btn` | 816 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.save_btn` | 819 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.save_tpl_btn` | 823-824 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.mode_combo` | 825 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 828) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.run_btn` | 830 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 833) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.runs_btn` | 837 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 840) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.canvas` | 853 | `ui/co4e_tab.py` | trạng thái chia sẻ rộng — self.canvas đọc/ghi bởi rất nhiều method trong và ngoài lát này (add_blank_step, _on_node_selected, _on_config_changed, _sync_wf_from_canvas, _apply_workflow, _start_canvas_run...) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_canvas_widget.py` (dong 856) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._vsplit` | 860 | `ui/co4e_tab.py` | trạng thái chia sẻ — self._vsplit dùng bởi _toggle_messages để co giãn giữa canvas và chat box; đúng như cảnh báo trong đề bài | co | - |
+| `Co4ETab._build_runs_page` | 870-898 | `ui/co4e_tab.py` | chỉ wiring RunsPagePanel (đã tách ở co4e_run_control_widget.py, không thuộc lát này) vào handler của Co4ETab — ở lại ui/co4e_tab.py theo đúng mô tả docstring của method | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 873-932) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.runs_back_btn` | 881 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 882) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.runs_title` | 883 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 887) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.ws_folder_btn` | 884 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 892) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.run_stop_btn` | 887 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 900) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.run_rename_btn` | 889 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 905) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.run_del_btn` | 891 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 909) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.run_clear_btn` | 893 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 913) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.runs_table` | 895 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 921) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._wrap_config` | 900-930 | `ui/co4e_tab.py` | không liên quan chat; liên quan node-property config panel (đã tách riêng ở node_property_panel.py, không thuộc lát/target được giao cho agent này) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 934-964) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.config_toggle_btn` | 912 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 946) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.config_title` | 917 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 951) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._cfg_vlayout` | 923 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 957) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._cfg_top_spacer` | 927 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 961) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._cfg_bot_spacer` | 928 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 962) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.config_container` | 929 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 963) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._NARROW` | 937 | `ui/co4e_tab.py` | hằng số class-level (không phải self.<tên>) — ngưỡng bề rộng cửa sổ hẹp, không liên quan chat | co | - |
+| `Co4ETab.showEvent` | 939-941 | `ui/co4e_tab.py` | Qt override, không liên quan chat | co | - |
+| `Co4ETab._apply_narrow_layout` | 943-953 | `ui/co4e_tab.py` | không liên quan chat | co | - |
+| `Co4ETab._toggle_config` | 955-998 | `ui/co4e_tab.py` | không liên quan chat; điều khiển config panel + splitter self._split | co | - |
+| `Co4ETab._refresh_min_width` | 1000-1005 | `ui/co4e_tab.py` | không liên quan chat | co | - |
+| `Co4ETab._build_canvas_overlay` | 1007-1028 | `ui/co4e_tab.py` | overlay zoom cho canvas — không liên quan chat, thuộc nhóm canvas widget | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_canvas_widget.py` (dong 1041-1062) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.zoom_in_btn` | 1020 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_canvas_widget.py` (dong 1054) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.zoom_out_btn` | 1021 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_canvas_widget.py` (dong 1055) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.fit_btn` | 1022 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_canvas_widget.py` (dong 1056) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._build_chat` | 1030-1093 | `presentation/co4e/co4e_chat_view.py` | Khớp trực tiếp với mô tả target: dựng header 'Messages' (icon+tiêu đề+nút thu/mở), QStackedWidget chat_stack chứa ChatView theo flow, composer (usage_total label + _ChatInput + RoutingToggle + nút Gửi). NHƯNG method này CŨNG khởi tạo trạng thái chia sẻ không thuộc widget thuần: self._flow_logs (dict per-flow), self._vsplit_sizes, self._msgs_collapsed (dùng bởi _toggle_messages/_ensure_flow_log ở lại Co4ETab) — nên tách phần init state đó ra khỏi hàm dựng widget khi chuyển file. Cũng nối self.chat_input.submit và self.chat_send_btn.clicked trực tiếp tới self._chat_send (method ở lại Co4ETab) — cần thiết kế callback/signal khi tách. | co | - |
+| `Co4ETab._chat_widget` | 1032 | `presentation/co4e/co4e_chat_view.py` | trạng thái chia sẻ — self._chat_widget.setMaximumHeight() được gọi từ _toggle_messages (ở lại Co4ETab) — điểm nối giữa 2 file | co | - |
+| `Co4ETab._mhdr` | 1038 | `presentation/co4e/co4e_chat_view.py` | trạng thái chia sẻ — self._mhdr.sizeHint() đọc từ _toggle_messages (ở lại Co4ETab) | co | - |
+| `Co4ETab.msgs_icon` | 1040 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `Co4ETab.msgs_title` | 1041 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `Co4ETab.chat_toggle_btn` | 1042 | `presentation/co4e/co4e_chat_view.py` | trạng thái chia sẻ — icon/tooltip của nút này bị _toggle_messages (ở lại Co4ETab) đổi qua lại icon 'chevron-up'/'chevron-down' | co | - |
+| `Co4ETab.chat_stack` | 1057 | `presentation/co4e/co4e_chat_view.py` | trạng thái chia sẻ quan trọng — self.chat_stack được _ensure_flow_log (addWidget) và _apply_workflow (setCurrentWidget) đọc/ghi, cả hai ở lại Co4ETab; điểm nối chính giữa chat_view.py và Co4ETab | co | - |
+| `Co4ETab._flow_logs` | 1058 | `ui/co4e_tab.py` | trạng thái chia sẻ per-flow (dict wf_id -> ChatView) — theo mô tả target, business logic quản lý log stays ở Co4ETab (_ensure_flow_log/_active_log/chat_log), nên dict này nên ở lại ui/co4e_tab.py dù được khởi tạo trong _build_chat (widget-building method) — cần tách khởi tạo này ra khỏi _build_chat khi chuyển file | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1092) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.chat_input_row` | 1060 | `presentation/co4e/co4e_chat_view.py` | trạng thái chia sẻ — show()/hide() gọi từ _toggle_messages (ở lại Co4ETab) | co | - |
+| `Co4ETab._usage_total_lbl` | 1065 | `presentation/co4e/co4e_chat_view.py` | label usage-total của composer — có khả năng được cập nhật bởi _refresh_usage_total (không thuộc lát này, khả năng ở Co4ETab) — kiểm tra lại khi gộp | co | - |
+| `Co4ETab.chat_input` | 1071 | `presentation/co4e/co4e_chat_view.py` | _ChatInput — submit signal nối tới self._chat_send (method ở lại Co4ETab, không có trong lát này) | co | - |
+| `Co4ETab.chat_send_btn` | 1074 | `presentation/co4e/co4e_chat_view.py` | clicked nối tới self._chat_send (ở lại Co4ETab) | co | - |
+| `Co4ETab.co4e_routing_toggle` | 1079 | `presentation/co4e/co4e_chat_view.py` | - | co | - |
+| `Co4ETab._co4e_routed_provider` | 1080 | `ui/co4e_tab.py` | biến trạng thái routing override cho lượt chat kế tiếp — là business state hơn là widget, được đọc/ghi ở _chat_send (không thuộc lát này); không rõ nó nên ở composer widget hay ở lại Co4ETab, cần người quyết -- QUYET DINH: bien trang thai routing override cho luot chat ke tiep la BUSINESS STATE, khong phai widget -- cung mot self._co4e_routed_provider duoc gan lai o dong 1819 (trong _apply_co4e_routing, o lai ui/co4e_tab.py theo yeu cau de bai); khoi tao lan dau nay (dong 1080, ben trong _build_chat) nen duoc TACH RA khoi ham dung widget khi chuyen file, giong cach xu ly _flow_logs (dong 1058) -- quyet dinh o day = ui/co4e_tab.py. | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1114; 1853) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._vsplit_sizes` | 1087 | `ui/co4e_tab.py` | trạng thái chia sẻ với _toggle_messages (ở lại Co4ETab theo mô tả target) — dùng self._vsplit | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1121) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._msgs_collapsed` | 1088 | `ui/co4e_tab.py` | trạng thái chia sẻ với _toggle_messages (ở lại Co4ETab theo mô tả target) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1122) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._toggle_messages` | 1095-1127 | `ui/co4e_tab.py` | loại trừ khỏi chat_view.py theo mô tả đề bài — dùng self._vsplit (splitter canvas/chat) để co giãn không gian, đây là logic của Co4ETab không phải của widget chat | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1129-1161) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._ensure_flow_log` | 1130-1139 | `ui/co4e_tab.py` | loại trừ khỏi chat_view.py theo mô tả đề bài — quản lý state per-flow (self._flow_logs, self.chat_stack) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1164-1173) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._active_log` | 1141-1143 | `ui/co4e_tab.py` | loại trừ khỏi chat_view.py theo mô tả đề bài | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1175-1177) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.chat_log` | 1145-1149 | `ui/co4e_tab.py` | property, loại trừ khỏi chat_view.py theo mô tả đề bài | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1180-1183) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._plan_bubble` | 1151-1157 | `ui/co4e_tab.py` | property với getter (1151-1153) và setter (1155-1157), loại trừ khỏi chat_view.py theo mô tả đề bài | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1186-1187) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._apply_workflow` | 1160-1173 | `ui/co4e_tab.py` | đọc/ghi self._wf, self.chat_stack, self.canvas — trạng thái chia sẻ rộng, business logic đổi workflow đang hiển thị | co | - |
+| `Co4ETab._new_workflow` | 1175-1183 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._selected_wf` | 1185-1191 | `ui/co4e_tab.py` | co4e.get_workflow(ident) đọc từ repository lưu trữ workflow (đĩa) | co | - |
+| `Co4ETab._load_selected_workflow` | 1193-1196 | `ui/co4e_tab.py` | qua _selected_wf() chạm đĩa | co | - |
+| `Co4ETab._edit_selected_workflow` | 1198-1203 | `ui/co4e_tab.py` | qua _selected_wf() chạm đĩa | co | - |
+| `Co4ETab._duplicate_selected_workflow` | 1205-1212 | `ui/co4e_tab.py` | co4e.duplicate_workflow ghi đĩa | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1239-1246) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._wf_context_menu` | 1214-1237 | `ui/co4e_tab.py` | dựng QMenu và dispatch tới các method khác (một số chạm đĩa) — bản thân method này không chạm đĩa trực tiếp | co | - |
+| `Co4ETab._rename_workflow` | 1239-1255 | `ui/co4e_tab.py` | QInputDialog modal + co4e.save_workflow ghi đĩa; cũng đồng bộ self._wf.name nếu đang mở đúng flow — trạng thái chia sẻ với name_edit/self._wf | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1273-1289) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._delete_selected_workflow` | 1257-1263 | `ui/co4e_tab.py` | co4e.delete_workflow ghi đĩa | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1291-1297) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._sync_wf_from_canvas` | 1265-1268 | `ui/co4e_tab.py` | đọc self.canvas.nodes()/edges() và self.name_edit — trạng thái chia sẻ với canvas | co | - |
+| `Co4ETab._save` | 1270-1275 | `ui/co4e_tab.py` | co4e.save_workflow ghi đĩa | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1304-1309) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._autosave` | 1277-1280 | `ui/co4e_tab.py` | co4e.save_workflow ghi đĩa (chỉ khi workflow đã tồn tại) | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1311-1314) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_name_changed` | 1282-1284 | `ui/co4e_tab.py` | gọi self._sync_active_flow_tab_text() (không thuộc lát này) — cập nhật self._wf.name | co | - |
+| `Co4ETab._add_blank_step` | 1286-1288 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._on_node_selected` | 1291-1297 | `ui/co4e_tab.py` | đọc self.canvas.nodes() và self.config — thuộc nhóm node-property, không phải chat | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 1325-1331) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_config_changed` | 1299-1302 | `ui/co4e_tab.py` | gọi self._autosave() (ghi đĩa gián tiếp) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/node_property_panel.py` (dong 1333-1336) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._new_agent` | 1305-1306 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 1339-1340) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._edit_agent` | 1308-1316 | `ui/co4e_tab.py` | co4e.list_custom_agents() khả năng đọc đĩa | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 1342-1350) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._edit_agent_dialog` | 1318-1324 | `ui/co4e_tab.py` | mở Co4EAgentDialog modal, co4e.save_custom_agent ghi đĩa | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 1352-1358) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._delete_agent` | 1326-1333 | `ui/co4e_tab.py` | co4e.delete_custom_agent ghi đĩa | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/agent_list_panel.py` (dong 1360-1367) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manage_skills` | 1335-1339 | `ui/co4e_tab.py` | mở SkillsDialog modal | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/skills_list_panel.py` (dong 1369-1373) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._skill_map` | 1342-1348 | `ui/co4e_tab.py` | logic thuần Python, đọc skills_mod.skill_prefix_for(name) — có khả năng đọc file skill từ đĩa | co | BANG CU KHAC: bang cu xep vao `application/workflows/co4e_workflow_service.py` (dong 1376-1382) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._current_mode` | 1350-1351 | `ui/co4e_tab.py` | đọc self.mode_combo.currentData() | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1384-1385) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_mode_changed` | 1353-1359 | `ui/co4e_tab.py` | reset self._manual_active/_manual_order/_manual_idx — trạng thái run-mode chia sẻ | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1387-1393) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_run_clicked` | 1361-1371 | `ui/co4e_tab.py` | gọi self.manager.stop/self._start_canvas_run — thuộc nhóm run control | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1395-1400) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._start_canvas_run` | 1373-1390 | `ui/co4e_tab.py` | khởi động self.manager.start(...) — sẽ trigger chạy step/agent (network/AI provider); ghi self._flow_runs, self._run_logs[run_id] = self.chat_log — điểm nối giữa run-control và chat log (self.chat_log là property loại trừ khỏi chat_view.py) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1407-1424) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_single` | 1392-1397 | `ui/co4e_tab.py` | gọi _start_canvas_run | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1426-1431) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_from` | 1399-1403 | `ui/co4e_tab.py` | [GOP 2 luot quet trung ky hieu, dong 1399] mot agent doc phan dau (1399-1400, chua thay than ham), agent kia doc phan duoi (1401-1403, tag tam 'unknown_method_fragment_before_1401') voi than ham la self._start_canvas_run(..., only=self._downstream(node_id), seed=dict(self._outputs_for(self._wf.id))) -- QUYET DINH: chay lai tu 1 node cu the tren canvas (logic thuc thi run), khong lien quan chat; giu o ui/co4e_tab.py cung nhom voi _run_single/_downstream. | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1433-1437) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._downstream` | 1405-1416 | `ui/co4e_tab.py` | đọc self.canvas.edges() — thuần logic đồ thị, test được không cần Qt nếu canvas là fake | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1439-1450) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manual_run_or_advance` | 1419-1432 | `ui/co4e_tab.py` | đọc/ghi self._wf, self._manual_order, self._manual_idx, self._manual_active, self._outputs_for — trạng thái chia sẻ giữa manual-run và canvas; gọi self.canvas.reset_statuses() | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1453-1466) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._manual_step` | 1434-1450 | `ui/co4e_tab.py` | ghi self._flow_runs, self._run_logs (định tuyến log theo từng flow — trạng thái chia sẻ then chốt); self.manager.start có thể chạm đĩa/spawn agent; self.run_btn.setText cần widget sống | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1468-1484) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._topo_order` | 1452-1457 | `ui/co4e_tab.py` | - | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1486-1491) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._on_manager_event` | 1460-1516 | `ui/co4e_tab.py` | method dài (~57 dòng) gộp nhiều việc: định tuyến sự kiện theo run_id/flow, cập nhật canvas status, ghi self._outputs_for/self._run_logs/self._flow_runs (trạng thái chia sẻ nhiều flow song song), gọi self._append_chat/_append_diff/_append_plan, hiện popup thông báo — nên cân nhắc tách theo loại event | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1494-1550) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._notify_run_finished` | 1518-1539 | `ui/co4e_tab.py` | dựng QMessageBox không chặn — cần QApplication sống | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1552-1573) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_popups` | 1526-1527 | `ui/co4e_tab.py` | khởi tạo lười (hasattr guard) bên trong _notify_run_finished — không thấy gán trong __init__ ở lát này, agent đọc __init__ nên đối chiếu | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1560-1561) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._refresh_runs` | 1541-1582 | `ui/co4e_tab.py` | cập nhật self.runs_table, self.flow_bar, self._sections — chạm nhiều widget cùng lúc | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1575-1616) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._stop_selected_run` | 1584-1590 | `ui/co4e_tab.py` | đọc self.runs_table.currentRow() | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1618-1624) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._delete_selected_run` | 1592-1605 | `ui/co4e_tab.py` | ghi self._flow_runs, self._run_logs — trạng thái chia sẻ per-flow | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1626-1639) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._runs_context_menu` | 1607-1621 | `ui/co4e_tab.py` | dựng QMenu tại vị trí chuột — cần widget sống | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1641-1655) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.set_project` | 1624-1640 | `ui/co4e_tab.py` | ghi self._project_id, self._project_dir (trạng thái workspace chia sẻ, ảnh hưởng _flow_output_root/_out_dir); load_project đọc dữ liệu project (đĩa); gọi self._refresh_ws_folder_btn nếu widget tồn tại | co | - |
+| `Co4ETab._flow_output_root` | 1642-1652 | `ui/co4e_tab.py` | đọc self._project_dir, self.ctx.config — logic thuần tính đường dẫn, không tự chạm đĩa (không mkdir/open) | co | - |
+| `Co4ETab._refresh_ws_folder_btn` | 1654-1659 | `ui/co4e_tab.py` | self.ws_folder_btn.setText/setToolTip | co | - |
+| `Co4ETab._open_workspace_folder` | 1661-1668 | `ui/co4e_tab.py` | mkdir + open_location (mở file explorer hệ điều hành, spawn process) | co | - |
+| `Co4ETab._open_run_output_folder` | 1670-1681 | `ui/co4e_tab.py` | kiểm tra path.exists()/mkdir + open_location | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1704-1715) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._rename_selected_run` | 1683-1714 | `ui/co4e_tab.py` | dựng QInputDialog; ghi self._flows, self.flow_bar (tab text), self._wf, self.name_edit — trạng thái chia sẻ giữa danh sách flow và tab đang mở; co4e.save_workflow ghi đĩa | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1717-1748) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_selected_in_background` | 1716-1726 | `ui/co4e_tab.py` | self.manager.start khởi chạy agent nền (ghi output ra đĩa) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1750-1760) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._wf_by_id` | 1728-1736 | `ui/co4e_tab.py` | co4e.get_workflow đọc workflow đã lưu từ đĩa; đọc self._wf | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1762-1770) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._rerun_run_item` | 1738-1749 | `ui/co4e_tab.py` | item là QTableWidgetItem; manager.start khởi chạy agent nền | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1772-1783) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._open_run_from_table` | 1751-1770 | `ui/co4e_tab.py` | gọi self._open_flow(wf), self.canvas.update_node_status — chạm canvas widget và self._wf | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 1785-1804) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab.showEvent` | 1772-1775 | `ui/co4e_tab.py` | override Qt event | co | - |
+| `Co4ETab._out_dir` | 1777-1783 | `ui/co4e_tab.py` | mkdir(parents=True); đọc self._wf.name | co | - |
+| `Co4ETab._chat_send` | 1786-1812 | `ui/co4e_tab.py` | theo yêu cầu, _chat_send KHÔNG thuộc co4e_chat_view.py dù đọc self.chat_input — ở lại Co4ETab; đọc/ghi self._chat_worker | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1820-1846) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._apply_co4e_routing` | 1814-1849 | `ui/co4e_tab.py` | ghi self._co4e_routed_provider (trạng thái đọc lại trong _run_chat_turn/job); nhánh manual gọi confirm_switch — mở dialog Qt (routing_toggle) nên cần widget sống ở nhánh đó | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1848-1883) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._co4e_routed_provider` | 1819 | `ui/co4e_tab.py` | gán lại mỗi lần gọi _apply_co4e_routing; được đọc bằng getattr(...,'None') ở _run_chat_turn/job — không chắc có init trong __init__ (nằm ngoài lát này) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1114; 1853) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._extract_agent_directive` | 1851-1857 | `ui/co4e_tab.py` | logic regex thuần, dễ test độc lập | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1885-1891) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._resolve_agent` | 1859-1867 | `ui/co4e_tab.py` | duyệt BUILTIN_AGENTS + co4e.list_custom_agents() (custom agents có thể đọc đĩa nhưng bản thân hàm chỉ gọi list) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1893-1901) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_chat_turn` | 1869-1940 | `ui/co4e_tab.py` | method dài (~72 dòng) gộp: build prompt, định nghĩa 4 closure lồng nhau (job/on_event/done/failed), khởi AgentWorker — nên tách; theo yêu cầu KHÔNG đưa job()/AgentWorker sang co4e_chat_view.py; đọc/ghi self.chat_log, self._wf, self._chat_worker (trạng thái chia sẻ) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1903-1974) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_chat_turn.job` | 1883-1912 | `ui/co4e_tab.py` | closure lồng trong _run_chat_turn, chạy trong AgentWorker thread; gọi run_cowork → gọi provider AI qua mạng; theo yêu cầu ở lại Co4ETab cùng _chat_send | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1917-1946) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_chat_turn.job._emit` | 1894-1901 | `ui/co4e_tab.py` | helper lồng bên trong job(), chuyển tiếp event streaming sang worker.emit_event | chua | BANG CU BO SOT: khong co dong nao cho symbol nay trong bang cu (363 dong) du no ro rang ton tai trong pham vi da quet -- co the do agent quet truoc bo lot, hoac day la ten sinh ra tu buoc gop lat cua ban do nay (vd ten method suy doan/tam). |
+| `Co4ETab._run_chat_turn.on_event` | 1914-1920 | `ui/co4e_tab.py` | closure cập nhật assistant.set_markdown/log.scroll_to_bottom — cần widget sống; gọi self._append_plan | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1948-1954) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_chat_turn.done` | 1922-1928 | `ui/co4e_tab.py` | ghi self._chat_worker=None, gọi self._apply_usage — chạm self._flow_usage | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1956-1962) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._run_chat_turn.failed` | 1930-1933 | `ui/co4e_tab.py` | ghi self._chat_worker=None, gọi self._append_chat | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1964-1967) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._append_chat` | 1942-1957 | `ui/co4e_tab.py` | theo yêu cầu, _append_chat KHÔNG thuộc co4e_chat_view.py — dùng self.chat_log mặc định, business logic per-flow ở lại Co4ETab | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1976-1991) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._fmt_usage` | 1960-1967 | `ui/co4e_tab.py` | logic thuần định dạng chuỗi + tra bảng giá từ self.ctx.config.data — test được không cần Qt | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 1994-2001) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._apply_usage` | 1969-1986 | `ui/co4e_tab.py` | ghi self._flow_usage (tổng usage theo từng flow — trạng thái chia sẻ với composer label usage-total ở co4e_chat_view.py); gọi bub.add_usage cần widget bubble sống | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 2003-2020) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._refresh_usage_total` | 1988-2003 | `ui/co4e_tab.py` | đọc self._flow_usage, self._wf; ghi self._usage_total_lbl.setText — label này được dựng trong co4e_chat_view.py (composer) nên đây là điểm nối trạng thái chia sẻ giữa 2 file | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 2022-2037) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._append_diff` | 2005-2009 | `ui/co4e_tab.py` | theo yêu cầu KHÔNG thuộc co4e_chat_view.py — ở lại Co4ETab | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 2039-2043) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._append_plan` | 2011-2022 | `ui/co4e_tab.py` | theo yêu cầu KHÔNG thuộc co4e_chat_view.py — dùng log._co4e_plan_bubble (state gắn trên đối tượng ChatView, không phải self) | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 2045-2056) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `Co4ETab._retranslate` | 2025-2045 | `ui/co4e_tab.py` | duyệt self._sections (trạng thái chia sẻ toàn tab) và setText hàng loạt widget nhiều khu vực khác nhau (runs, sidebar, header) — cắt ngang nhiều nhóm chức năng khác nhau nên khó tách gọn | co | - |
+| `_html_escape` | 2048-2049 | `ui/co4e_tab.py` | hàm module-level, tiện ích thuần chuỗi, không thuộc riêng chat_view | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_chat_view.py` (dong 2082-2083) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+| `_qcolor` | 2052-2054 | `ui/co4e_tab.py` | QColor dùng như kiểu giá trị, không cần QApplication sống | co | BANG CU KHAC: bang cu xep vao `presentation/co4e/co4e_run_control_widget.py` (dong 2086-2088) nhung theo mo ta dich cua lan quet nay -> quyet dinh o day = `ui/co4e_tab.py`. |
+
+## Chỗ thấy khác tài liệu — cần người quyết
+
+Không có symbol nào trong 220 symbol thô có note bắt đầu bằng `khac tai lieu:` — mục này để trống theo đúng yêu cầu tự kiểm (không có gì cần liệt kê).

docs/architecture/co4e-split-map-node-property.json

@@ -0,0 +1,123 @@
+{
+  "scope": "StepConfigPanel (ui/co4e_config_panel.py, dong 1-528)",
+  "source_file": "ui/co4e_config_panel.py",
+  "symbols": [
+    {
+      "symbol": "_SECTION_ANIM_MS",
+      "source_lines": "27",
+      "target_file": "presentation/co4e/step_config_section.py",
+      "note": "hang so animation cho _add_section"
+    },
+    {
+      "symbol": "_SectionHeader",
+      "source_lines": "30-52",
+      "target_file": "presentation/co4e/step_config_section.py",
+      "note": "QLabel clickable, khung UI dung chung, khong co hanh vi nghiep vu rieng"
+    },
+    {
+      "symbol": "_add_section",
+      "source_lines": "55-130",
+      "target_file": "presentation/co4e/step_config_section.py",
+      "note": "khung section gap/mo dung chung cho 4 nhom truong cua StepConfigPanel"
+    },
+    {
+      "symbol": "StepConfigPanel (Signal + __init__)",
+      "source_lines": "133-313",
+      "target_file": "presentation/co4e/node_property_panel.py",
+      "note": "4 Signal (changed/run_node/run_from/delete_node) + dung toan bo form"
+    },
+    {
+      "symbol": "StepConfigPanel.load_step",
+      "source_lines": "316-354",
+      "target_file": "presentation/co4e/node_property_panel.py",
+      "note": "nap Step vao form"
+    },
+    {
+      "symbol": "StepConfigPanel.clear_step",
+      "source_lines": "356-359",
+      "target_file": "presentation/co4e/node_property_panel.py",
+      "note": "xoa state, tat panel"
+    },
+    {
+      "symbol": "StepConfigPanel._on_edit",
+      "source_lines": "362-378",
+      "target_file": "presentation/co4e/node_property_panel.py",
+      "note": "ghi field UI nguoc vao Step"
+    },
+    {
+      "symbol": "StepConfigPanel._available_agent_names",
+      "source_lines": "380-390",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "staticmethod, chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._add_subagent",
+      "source_lines": "392-408",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._edit_subagent",
+      "source_lines": "410-428",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._del_subagent",
+      "source_lines": "430-437",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._add_attachment",
+      "source_lines": "439-453",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._del_attachment",
+      "source_lines": "455-462",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin"
+    },
+    {
+      "symbol": "StepConfigPanel._ai_draft",
+      "source_lines": "464-498",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin; dung AgentWorker that"
+    },
+    {
+      "symbol": "StepConfigPanel._load_models",
+      "source_lines": "500-528",
+      "target_file": "presentation/co4e/node_property_actions_mixin.py",
+      "note": "chuyen vao mixin _StepConfigActionsMixin; dung AgentWorker that"
+    }
+  ],
+  "old_file_after_split": {
+    "file": "ui/co4e_config_panel.py",
+    "content": "module docstring (sua, van tieng Anh) + import lai StepConfigPanel tu presentation/co4e/node_property_panel.py + __all__",
+    "lines": 14
+  },
+  "new_files": [
+    {"file": "presentation/co4e/step_config_section.py", "lines": 134},
+    {"file": "presentation/co4e/node_property_actions_mixin.py", "lines": 202},
+    {"file": "presentation/co4e/node_property_panel.py", "lines": 293}
+  ],
+  "inheritance": {
+    "class": "StepConfigPanel",
+    "bases": ["_StepConfigActionsMixin", "QScrollArea"],
+    "mandatory_order": false,
+    "reason": "khong co method nao cua _StepConfigActionsMixin trung ten voi QScrollArea (khac Co4ECanvas voi paintEvent/mousePressEvent), nen thu tu ke thua khong anh huong hanh vi; giu mixin-truoc chi de nhat quan quy uoc"
+  },
+  "deliberate_unused_import_kept": {
+    "name": "PROVIDER_LABELS",
+    "source_line": 21,
+    "target_file": "presentation/co4e/node_property_panel.py",
+    "reason": "khong dung o dau trong ban goc (da xac minh bang grep); giu nguyen de dung pham vi chi doi cho, khong don dep import thua"
+  },
+  "test_patch_adaptation": {
+    "file": "tests/characterization/test_node_property_panel.py",
+    "what_changed": "case CASE_ADD_SUBAGENT_EMPTY_NAMES_USES_GETTEXT_QUIRK_OK doi tu StepConfigPanel.__dict__[\"_available_agent_names\"] (luu roi gan lai) sang del StepConfigPanel._available_agent_names (xoa override de roi ve lai method ke thua tu mixin)",
+    "why": "sau khi _available_agent_names chuyen vao _StepConfigActionsMixin, no khong con nam truc tiep trong StepConfigPanel.__dict__ nen loi KeyError; day la thay doi CACH patch/restore trong test, KHONG doi assert/hanh vi nao duoc kiem tra"
+  }
+}

docs/architecture/co4e-split-map-node-property.md

@@ -0,0 +1,102 @@
+# Bản đồ tách `StepConfigPanel` (`ui/co4e_config_panel.py` → `presentation/co4e/`)
+
+- **Phạm vi lượt này:** chỉ `StepConfigPanel` (nguyên bản dòng 1-528 của
+  `ui/co4e_config_panel.py`). Không đụng file nào khác thuộc làn N1
+  (`ui/co4e_tab.py`, `ui/co4e_canvas.py`, `docs/architecture/co4e-split-map.md`/`.json`).
+- **Lý do phải tách thêm, dù chỉ 1 class:** `StepConfigPanel` một mình đã 396
+  dòng (133-528); cộng thêm module docstring + khối import của một file riêng
+  sẽ vượt trần 400 dòng (CASAN Check 2). Giải pháp: cắt-dán (không viết lại
+  logic) thành 3 file theo trách nhiệm.
+
+## File đích
+
+| symbol | dòng gốc | file đích | ghi chú |
+|---|---|---|---|
+| `_SECTION_ANIM_MS` | 27 | `presentation/co4e/step_config_section.py` | hằng số dùng bởi `_add_section` |
+| `_SectionHeader` | 30-52 | `presentation/co4e/step_config_section.py` | `QLabel` clickable, không có hành vi nghiệp vụ riêng |
+| `_add_section` | 55-130 | `presentation/co4e/step_config_section.py` | khung ▶/▼ dùng chung cho 4 nhóm trường của `StepConfigPanel`; không đọc/ghi state của panel |
+| `StepConfigPanel` (Signal + `__init__`) | 133-313 | `presentation/co4e/node_property_panel.py` | 4 Signal (`changed`/`run_node`/`run_from`/`delete_node`) + dựng toàn bộ form |
+| `StepConfigPanel.load_step` | 316-354 | `presentation/co4e/node_property_panel.py` | nạp `Step` vào form |
+| `StepConfigPanel.clear_step` | 356-359 | `presentation/co4e/node_property_panel.py` | xoá state, tắt panel |
+| `StepConfigPanel._on_edit` | 362-378 | `presentation/co4e/node_property_panel.py` | ghi field UI ngược vào `Step` |
+| `StepConfigPanel._available_agent_names` | 380-390 | `presentation/co4e/node_property_actions_mixin.py` (`_StepConfigActionsMixin`) | staticmethod, dùng bởi `_add_subagent`/`_edit_subagent` |
+| `StepConfigPanel._add_subagent` | 392-408 | `presentation/co4e/node_property_actions_mixin.py` | |
+| `StepConfigPanel._edit_subagent` | 410-428 | `presentation/co4e/node_property_actions_mixin.py` | |
+| `StepConfigPanel._del_subagent` | 430-437 | `presentation/co4e/node_property_actions_mixin.py` | |
+| `StepConfigPanel._add_attachment` | 439-453 | `presentation/co4e/node_property_actions_mixin.py` | |
+| `StepConfigPanel._del_attachment` | 455-462 | `presentation/co4e/node_property_actions_mixin.py` | |
+| `StepConfigPanel._ai_draft` | 464-498 | `presentation/co4e/node_property_actions_mixin.py` | dùng `AgentWorker` thật (không mock trong `__init__`) |
+| `StepConfigPanel._load_models` | 500-528 | `presentation/co4e/node_property_actions_mixin.py` | dùng `AgentWorker` thật |
+
+## Cách ghép lại: mixin + đa kế thừa
+
+`node_property_panel.py`:
+```python
+class StepConfigPanel(_StepConfigActionsMixin, QScrollArea):
+    ...
+```
+
+`_StepConfigActionsMixin` là mixin THUẦN — không `__init__` riêng, chỉ đọc/ghi
+state có sẵn trên `self` do `StepConfigPanel.__init__` định nghĩa
+(`self._step`, `self._node_id`, `self.ctx`, `self.sub_list`, `self.attach_list`,
+`self.instructions_edit`, `self.gen_btn`, `self.model_combo`,
+`self.load_models_btn`).
+
+Khác với bước `co4e_canvas_widget.py` (Co4ECanvas override nhiều method Qt như
+`paintEvent`/`mousePressEvent`, nên thứ tự mixin-trước-base là **bắt buộc** để
+MRO ưu tiên override của mixin): ở đây **không có method nào của
+`_StepConfigActionsMixin` trùng tên với `QScrollArea`**, nên thứ tự kế thừa
+không ảnh hưởng hành vi. Giữ thứ tự mixin-trước chỉ để nhất quán quy ước, không
+phải yêu cầu kỹ thuật bắt buộc.
+
+## Import thừa cố ý giữ nguyên
+
+`PROVIDER_LABELS` (nguyên bản dòng 21, `from ..config import PROVIDER_LABELS`)
+không được dùng ở đâu trong toàn bộ `ui/co4e_config_panel.py` gốc (đã xác minh
+bằng grep). Vẫn giữ nguyên import này trong `node_property_panel.py` (chỉ đổi
+số cấp `..` → `...`), không xoá, để đúng phạm vi "chỉ dời chỗ" của lượt tách
+này — xoá một import "thừa" là một quyết định dọn dẹp ngoài phạm vi được giao.
+
+## Thay đổi comment/test ngoài phạm vi "chỉ dời chỗ" (ghi riêng, không lẫn vào phần move)
+
+1. **Docstring module của 3 file mới** (`step_config_section.py`,
+   `node_property_actions_mixin.py`, `node_property_panel.py`) — viết MỚI hoàn
+   toàn bằng tiếng Việt theo quy ước CASAN cho file mới trong `presentation/`
+   (mẫu `infrastructure/persistence/json/atomic_json_file.py`). Đây không phải
+   sửa một comment cũ bị sai do dời chỗ — module docstring nguyên bản (dòng
+   1-9 của `ui/co4e_config_panel.py`) mô tả cả file cũ (đã bị chia làm 3), nên
+   mỗi file mới cần một docstring kiến trúc riêng thay vì copy y hệt bản gốc.
+2. **`ui/co4e_config_panel.py`** (file cũ) — docstring được viết lại (vẫn
+   tiếng Anh, khớp quy ước "sửa file cũ tiếng Anh thì giữ tiếng Anh") để nói rõ
+   `StepConfigPanel` đã dời đi đâu, thay vì mô tả hành vi như thể class còn
+   định nghĩa tại chỗ — comment cũ sẽ SAI (nói rằng lớp "ở đây" trong khi
+   không còn) nếu giữ nguyên.
+3. **`tests/characterization/test_node_property_panel.py`** (dòng ~296-307
+   nguyên bản) — SỬA kỹ thuật patch/restore của case
+   `CASE_ADD_SUBAGENT_EMPTY_NAMES_USES_GETTEXT_QUIRK_OK`, không đổi bất kỳ
+   assert/hành vi nào. Bản gốc dùng
+   `StepConfigPanel.__dict__["_available_agent_names"]` để lưu lại method gốc
+   trước khi monkey-patch, rồi gán lại y hệt lúc restore. Sau khi
+   `_available_agent_names` chuyển vào `_StepConfigActionsMixin` (mixin riêng),
+   nó không còn nằm trong `StepConfigPanel.__dict__` (chỉ được kế thừa qua
+   MRO) → `KeyError`. Thay bằng: gán đè trực tiếp lên `StepConfigPanel` (vẫn
+   shadow đúng như cũ), và khi xong dùng `del StepConfigPanel._available_agent_names`
+   để nó rơi trở lại đúng method kế thừa từ mixin — hành vi quan sát được của
+   test (các assert `sub_agents`) giữ nguyên 100%, chỉ đổi CÁCH lưu/khôi phục
+   attribute bị monkey-patch. Đây là hệ quả tất yếu của yêu cầu tách mixin
+   trong lượt này (test được viết khi class còn nguyên khối), không phải sửa
+   test để che một thay đổi hành vi.
+
+## Xác minh
+
+- `.venv/Scripts/python.exe tools/check_co4e.py` — chạy TRƯỚC và SAU khi sửa,
+  output giống hệt nhau cả 2 lần (`KET QUA: Co4E sap xep lai, khong mat control nao`).
+- `.venv/Scripts/python.exe -m pytest tests/characterization/test_node_property_panel.py -q`
+  — `1 passed` cả trước (đo trên code gốc, class còn ở `ui/co4e_config_panel.py`)
+  lẫn sau khi tách.
+- `.venv/Scripts/python.exe -m pytest tests -q --tb=short -rf --continue-on-collection-errors`
+  — `287 passed, 1 skipped` sau khi tách (không có test nào khác vỡ vì import
+  `StepConfigPanel` từ `ui/co4e_config_panel.py`).
+- AST-scan `domain/`+`application/` cho import PySide6/PyQt: `KHONG CO`.
+- Số dòng file mới: `node_property_panel.py` 293, `node_property_actions_mixin.py`
+  202, `step_config_section.py` 134 — cả 3 đều ≤ 400.

docs/architecture/co4e-split-map-run-control.md

@@ -0,0 +1,238 @@
+# Bản đồ tách file — Run Control (trang Runs / Flow Status)
+
+Gộp 215 symbol thô từ 3 agent quét song song trên `ui/co4e_tab.py`, còn lại **214 dòng** sau khi gộp 1 trùng lặp thật (`Co4ETab._reload_sidebar` dòng 685, xem bên dưới).
+
+- File đích của lane run-control: `presentation/co4e/co4e_run_control_widget.py` — **18 symbol**.
+- Phần còn lại của container: `ui/co4e_tab.py` — **173 symbol**.
+- Thuộc lane/file khác (ngoài phạm vi run-control, chỉ ghi lại để tham khảo): **23 symbol** (application/workflows/co4e_workflow_service.py, presentation/co4e/agent_list_panel.py, presentation/co4e/skills_list_panel.py, presentation/co4e/co4e_canvas_widget.py).
+- Note bắt đầu bằng `khac tai lieu:` tìm thấy trong dữ liệu thô: **0**.
+
+## Phát hiện quan trọng nhất từ việc đối chiếu với bảng cũ
+
+1. **Đường dẫn `co4e_tab.py` trong bảng cũ sai.** Bảng cũ (`docs/architecture/co4e-split-map.json`) dùng `target_file="presentation/co4e/co4e_tab.py"` cho phần thân lớp `Co4ETab` còn lại, nhưng file đó ở repo hiện tại chỉ là factory `build_co4e_tab()` dài 53 dòng (bọc nguyên `Co4ETab` cũ 1:1, xem docstring của nó) — KHÔNG phải nơi lớp `Co4ETab` thật sự sống. Lớp đó vẫn đang ở `ui/co4e_tab.py`. Bảng này đã tự quy đổi mọi so sánh trước khi kết luận lệch.
+2. **Phạm vi `co4e_run_control_widget.py` đã bị thu hẹp so với bảng cũ.** Bảng cũ coi 'run control' là toàn bộ chuỗi: bảng Runs + logic thực thi run (start/stop/manual-mode/mode toolbar/event routing/popup) + sidebar quick-list các run gần đây. Lần quét 3-agent hiện tại (theo mô tả đích lặp lại trong nhiều ghi chú riêng lẻ) chỉ còn coi `co4e_run_control_widget.py` là **trang Runs/Flow Status**: bảng `runs_table` + các nút hành động trên từng dòng (stop/rename/delete/clear/mở thư mục) + nút quay lại + tiêu đề. Logic thực thi run, toolbar mode/run, và sidebar quick-list quay lại ở lại `ui/co4e_tab.py`. Đây là khác biệt lớn nhất — ảnh hưởng tới 34 dòng bên dưới (đánh dấu ở cột cuối).
+3. **Bảng cũ không nhất quán giữa alias của Agent panel và Skills panel.** `ag_new_btn`/`agent_list`/`ag_edit_btn`/`ag_del_btn` (alias trỏ vào `AgentListPanel` đã tách) được bảng cũ xếp vào `presentation/co4e/agent_list_panel.py`, nhưng `sk_manage_btn`/`skill_list` (alias trỏ vào `SkillsListPanel`, cùng bản chất) lại bị xếp vào `co4e_tab.py`. Bảng này chọn xử lý đồng nhất — coi cả hai cặp alias đều thuộc file panel tương ứng.
+4. **Bảng cũ bỏ sót 2 symbol:** `Co4ETab.status_message` (Signal cấp lớp) và `Co4ETab._agent_panel` (instance `AgentListPanel` do container giữ) không có dòng nào trong bảng cũ dù nằm trong phạm vi đã quét.
+
+## Bảng đầy đủ (sắp theo số dòng)
+
+| symbol | dòng | file đích | lý do | có trong bảng cũ chưa | chỗ nào thấy bảng cũ sai |
+|---|---|---|---|---|---|
+| `_PLAN_GLYPH` | 46-47 | `ui/co4e_tab.py` | module-level dict constant, không phải self.<attr> -- QUYET DINH: glyph dùng bởi _fmt_plan cho bong bóng 'plan' trong CHAT, không phải bảng Runs; bảng cũ xếp nhầm vào co4e_run_control_widget.py | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 45-46) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `_fmt_plan` | 50-59 | `ui/co4e_tab.py` | helper format cho _append_plan (chat), không đụng runs_table; bảng cũ xếp nhầm vào co4e_run_control_widget.py | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 49-58) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `_skill_names` | 62-66 | `ui/co4e_tab.py` | gọi skills_mod.list_skills()/builtin_skills() — có thể chạm đĩa qua core.skills -- QUYET DINH: helper autocomplete cho _ChatInput — thuộc lane co4e_chat_view.py (chưa tồn tại), ngoài phạm vi lane run-control nên giữ nguyên vị trí hiện tại | co | - |
+| `_agent_names` | 69-72 | `ui/co4e_tab.py` | gọi co4e.list_custom_agents() — chạm đĩa qua core.co4e -- QUYET DINH: cùng lý do với _skill_names — autocomplete /agent trong chat | co | - |
+| `_EqualTabBar` | 75-95 | `ui/co4e_tab.py` | helper QTabBar cho sidebar icon-tabs — không liên quan Flow Status -- QUYET DINH: QTabBar tiện ích cho sidebar icon-tabs, không liên quan Runs | co | - |
+| `_EqualTabBar._GAP` | 81 | `ui/co4e_tab.py` | hằng số nội bộ của _EqualTabBar | co | - |
+| `_EqualTabBar.tabSizeHint` | 83-91 | `ui/co4e_tab.py` | - | co | - |
+| `_EqualTabBar.resizeEvent` | 93-95 | `ui/co4e_tab.py` | - | co | - |
+| `_PaletteList` | 98-120 | `ui/co4e_tab.py` | list kéo-thả vào canvas cho Workflows/Agents/Skills palette — không phải Runs -- QUYET DINH: list kéo-thả cho palette Workflows/Agents/Skills, không phải Runs | co | - |
+| `_PaletteList.__init__` | 103-107 | `ui/co4e_tab.py` | - | co | - |
+| `_PaletteList._payload_role` | 105 | `ui/co4e_tab.py` | - | co | - |
+| `_PaletteList.startDrag` | 109-120 | `ui/co4e_tab.py` | - | co | - |
+| `_directive_token` | 123-135 | `ui/co4e_tab.py` | logic thuần regex cho autocomplete /skill /agent trong chat — test được không cần Qt -- QUYET DINH: regex thuần cho autocomplete /skill /agent — lane co4e_chat_view.py (chưa tồn tại), giữ nguyên | co | - |
+| `_ChatInput` | 138-227 | `ui/co4e_tab.py` | ô chat với popup autocomplete — không liên quan Flow Status -- QUYET DINH: ô nhập chat với popup autocomplete — lane co4e_chat_view.py (chưa tồn tại), giữ nguyên | co | - |
+| `_ChatInput.submit` | 142 | `ui/co4e_tab.py` | Signal khai báo ở cấp lớp -- QUYET DINH: Signal của _ChatInput — đi cùng class | chua | - |
+| `_ChatInput.__init__` | 144-152 | `ui/co4e_tab.py` | - | co | - |
+| `_ChatInput._popup` | 146 | `ui/co4e_tab.py` | - | co | - |
+| `_ChatInput._maybe_popup` | 154-179 | `ui/co4e_tab.py` | gọi _skill_names/_agent_names (chạm đĩa gián tiếp) và định vị popup bằng tọa độ màn hình | co | - |
+| `_ChatInput._add_row` | 181-185 | `ui/co4e_tab.py` | - | co | - |
+| `_ChatInput._accept` | 187-200 | `ui/co4e_tab.py` | - | co | - |
+| `_ChatInput.focusOutEvent` | 202-205 | `ui/co4e_tab.py` | - | co | - |
+| `_ChatInput.keyPressEvent` | 207-227 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab` | 230-700 | `ui/co4e_tab.py` | cắt ngang lát — cần agent gộp đối chiếu (thân lớp trải dài quá dòng 700, đây chỉ là phần đầu) -- QUYET DINH: lớp container chính — phần còn lại sau khi các widget con (canvas/node-property/agent/skills/run-control/chat) đã tách | co | - |
+| `Co4ETab.status_message` | 231 | `ui/co4e_tab.py` | Signal khai báo ở cấp lớp -- QUYET DINH: Signal cấp lớp của chính Co4ETab; KHÔNG có trong bảng cũ (thiếu sót ở đó) | chua | BANG CU BO SOT: khong co dong nao cho symbol nay du no ro rang ton tai trong pham vi da quet (367 symbol tho cua bang cu) -- co the do agent quet truoc bo lot. |
+| `Co4ETab.__init__` | 233-305 | `ui/co4e_tab.py` | gộp nhiều việc: khởi state run-per-flow, dựng splitter 3 cột, wiring StepConfigPanel, narrow-guard, rồi mở flow đầu tiên — biên độ rủi ro cao khi tách vì đụng gần hết thuộc tính self chia sẻ toàn tab -- QUYET DINH: constructor container — sẽ đổi để dựng Co4ERunControlWidget thay vì tự vẽ bảng Runs | co | - |
+| `Co4ETab.ctx` | 235 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._wf` | 236 | `ui/co4e_tab.py` | trạng thái chia sẻ toàn tab — workflow đang hiển thị trên canvas, đọc/ghi bởi rất nhiều method (flow tabs, run, sidebar, config) -- QUYET DINH: trạng thái trung tâm toàn tab, container giữ | co | - |
+| `Co4ETab._chat_worker` | 237 | `ui/co4e_tab.py` | AgentWorker của chat — lane co4e_chat_view.py chưa tồn tại, giữ nguyên | co | - |
+| `Co4ETab.manager` | 239 | `ui/co4e_tab.py` | Co4ERunManager dùng chung giữa canvas (mirror trạng thái node) và trang Runs (self.runs_table — định nghĩa ngoài dòng 700, có thể ở co4e_run_control_widget) — điểm nối quan trọng giữa hai lát -- QUYET DINH: Co4ERunManager dùng chung giữa canvas, chat VÀ bảng Runs — quyết định: container SỞ HỮU, co4e_run_control_widget.py nhận qua constructor/callback (dependency injection) thay vì tự tạo. Bảng cũ xếp thẳng vào co4e_run_control_widget.py dù chính ghi chú của nó gọi đây là 'điểm nối' — coi là quá vội | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 238) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._flow_runs` | 244 | `ui/co4e_tab.py` | trạng thái chia sẻ wf_id -> active run id, đọc/ghi bởi _open_flow, _close_flow_tab, _cur_run_id, _reflect_active_run -- QUYET DINH: dict wf_id->run id, ghi bởi _open_flow/_close_flow_tab/_start_canvas_run (đều ở co4e_tab.py) — container giữ, run-control đọc/ghi qua callback. Bảng cũ xếp vào co4e_run_control_widget.py — không khớp nơi ghi chính | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 243) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._run_logs` | 245 | `ui/co4e_tab.py` | map run_id->ChatView (thuộc lane chat), ghi bởi _manual_step/_start_canvas_run ở co4e_tab.py — container giữ | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 244) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._flow_outputs` | 246 | `application/workflows/co4e_workflow_service.py` | đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi lane run-control. Hiện tại vật lý vẫn còn ở ui/co4e_tab.py dòng 246 chờ lane đó dọn | co | - |
+| `Co4ETab._flow_usage` | 249 | `ui/co4e_tab.py` | usage token/cost hiển thị ở header CHAT (Messages), không phải bảng Runs — bảng cũ xếp nhầm vào co4e_run_control_widget.py | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 248) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._project_id` | 250 | `ui/co4e_tab.py` | workspace hiện chọn — dùng chung bởi chat (_out_dir) và nút mở-thư-mục của Runs; container giữ, expose qua callback | co | - |
+| `Co4ETab._project_dir` | 251 | `ui/co4e_tab.py` | cùng lý do với _project_id | co | - |
+| `Co4ETab._manual_active` | 253 | `ui/co4e_tab.py` | trạng thái MODE THỦ CÔNG — thuộc nhóm run-execution, mô tả đích lane này loại trừ mode/run toolbar khỏi co4e_run_control_widget.py. Bảng cũ xếp vào co4e_run_control_widget.py — mâu thuẫn trực tiếp với phạm vi hiện tại | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 252) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_order` | 254 | `ui/co4e_tab.py` | cùng nhóm với _manual_active — xem lý do ở đó | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 253) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_idx` | 255 | `ui/co4e_tab.py` | cùng nhóm với _manual_active — xem lý do ở đó | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 254) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._flows` | 258 | `ui/co4e_tab.py` | trạng thái chia sẻ danh sách flow đang mở (browser-style tabs) — đọc/ghi bởi toàn bộ nhóm _open_flow/_close_flow_tab/_on_flow_tab_changed -- QUYET DINH: danh sách flow-tab kiểu browser, không phải Runs | co | - |
+| `Co4ETab._active_flow_idx` | 259 | `ui/co4e_tab.py` | cùng nhóm trạng thái chia sẻ với _flows -- QUYET DINH: cùng nhóm với _flows | co | - |
+| `Co4ETab._split` | 262 | `ui/co4e_tab.py` | splitter 3 cột của cả tab | co | - |
+| `Co4ETab.config` | 269 | `ui/co4e_tab.py` | container giữ tham chiếu StepConfigPanel (đã tách ở node_property_panel.py, file cấm sửa của lane khác) — cùng khuôn mẫu với _agent_panel/_skills_panel: instance do container tạo/giữ, nội dung panel ở file riêng. Bảng cũ xếp thẳng dòng này vào node_property_panel.py — không nhất quán với cách nó xử lý _agent_panel | co | - |
+| `Co4ETab._config_collapsed` | 275 | `ui/co4e_tab.py` | trạng thái thu/phóng của KHUNG bọc quanh panel (co4e_tab.py), không phải nội dung panel | co | - |
+| `Co4ETab._config_expanded_w` | 276 | `ui/co4e_tab.py` | cùng lý do với _config_collapsed | co | - |
+| `Co4ETab._narrow_guard` | 281 | `ui/co4e_tab.py` | guard bố cục hẹp của cả tab | co | - |
+| `Co4ETab._open_flow` | 308-339 | `ui/co4e_tab.py` | đọc/ghi self._flows, self._active_flow_idx, self.flow_bar — quản lý flow tab kiểu browser, không phải trang Runs -- QUYET DINH: quản lý flow-tab kiểu browser | co | - |
+| `Co4ETab._close_other_flows` | 341-356 | `ui/co4e_tab.py` | đọc/ghi self._flows, self._active_flow_idx, self.flow_bar | co | - |
+| `Co4ETab._show_runs` | 358-368 | `ui/co4e_tab.py` | chuyển center_stack giữa flow editor và trang Runs; gọi bởi self.runs_btn (định nghĩa ngoài dòng 700, thuộc toolbar) và runs_more_btn (sidebar) — không thao tác trực tiếp runs_table nên không chắc thuộc co4e_run_control_widget hay ở lại co4e_tab.py làm điều phối trang -- QUYET DINH: điều phối chuyển trang center_stack giữa flow editor và trang Runs — container sở hữu center_stack; sẽ gọi API show()/hide() hoặc setCurrentWidget trên Co4ERunControlWidget thay vì tự vẽ | co | - |
+| `Co4ETab._on_flow_tab_changed` | 370-386 | `ui/co4e_tab.py` | đọc/ghi self._active_flow_idx, self.center_stack (self.center_stack định nghĩa ngoài dòng 700) | co | - |
+| `Co4ETab._sync_runs_toggle` | 388-395 | `ui/co4e_tab.py` | dùng getattr(self, 'runs_btn', None) vì runs_btn (toolbar, ngoài dòng 700) có thể chưa tồn tại — đồng bộ trạng thái toggle của trang Runs -- QUYET DINH: đồng bộ nút toggle runs_btn ở toolbar (thuộc co4e_tab.py, KHÔNG phải trang Runs) | co | - |
+| `Co4ETab._add_tab_close_button` | 397-407 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._close_flow_tab_button` | 409-413 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._close_flow_tab` | 415-443 | `ui/co4e_tab.py` | đọc/ghi self._flow_runs, self._run_logs, self._flows, self._active_flow_idx, self.run_btn (định nghĩa ngoài dòng 700) — nhiều trạng thái chia sẻ chạm cùng lúc | co | - |
+| `Co4ETab._sync_active_flow_tab_text` | 445-448 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._reflect_active_run` | 450-458 | `ui/co4e_tab.py` | đọc self.manager.all_runs(), ghi self._flow_runs, gọi self.canvas.update_node_status — cầu nối giữa run manager (chia sẻ với trang Runs) và canvas -- QUYET DINH: cầu nối manager -> canvas (update_node_status trên canvas thuộc co4e_tab.py) — đi cùng nhóm thực thi run, không phải bảng Runs | co | - |
+| `Co4ETab._cur_run_id` | 461-474 | `ui/co4e_tab.py` | logic thuần: đọc self._wf, self._flow_runs, self.manager.get() — test được không cần Qt -- QUYET DINH: tra cứu run đang chạy CỦA FLOW HIỆN TẠI, dùng bởi _reflect_active_run (canvas mirror, co4e_tab.py) — không đụng runs_table. Bảng cũ xếp vào co4e_run_control_widget.py — không khớp nơi dùng chính | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 460-473) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._outputs_for` | 476-479 | `application/workflows/co4e_workflow_service.py` | logic thuần dict, test được không cần Qt -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ) cho cặp _flow_outputs/_outputs_for; ngoài phạm vi lane run-control | co | - |
+| `Co4ETab._update_run_btn` | 481-483 | `ui/co4e_tab.py` | thuộc nhóm run toolbar (self.run_btn) — theo mô tả target, co4e_run_control_widget KHÔNG bao gồm mode/run toolbar nên method này không nên vào đó -- QUYET DINH: nút Run của toolbar mode/run — mô tả đích loại trừ nhóm này khỏi co4e_run_control_widget.py; bảng cũ xếp vào đó — mâu thuẫn với phạm vi hiện tại | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 480-482) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._build_sidebar` | 486-599 | `ui/co4e_tab.py` | method dài >80 dòng, gộp nhiều việc không liên quan nhau: dựng section Workflows (list + edit/dup/del/run-bg), section Agents (AgentListPanel wiring), section Skills (SkillsListPanel wiring), section Runs sidebar quick-list, và lắp splitter dọc side_split — nên tách nhỏ thêm theo từng section -- QUYET DINH: dựng toàn bộ sidebar (Workflows/Agents/Skills/Runs quick-list) | co | - |
+| `Co4ETab._sections` | 494 | `ui/co4e_tab.py` | dict trạng thái chia sẻ cho các section sidebar (fold/unfold) — đọc/ghi bởi _section, _fold_section, _sync_section_arrow | co | - |
+| `Co4ETab.sidebar` | 495 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.side_split` | 499 | `ui/co4e_tab.py` | - | co | - |
+| `_build_sidebar._Col` | 504-512 | `ui/co4e_tab.py` | class cục bộ (locals) bên trong _build_sidebar — adapter cho side_split, không phải class module-level -- QUYET DINH: class cục bộ, adapter cho side_split | co | - |
+| `_Col.__init__` | 507-508 | `ui/co4e_tab.py` | - | co | - |
+| `_Col.addWidget` | 510-512 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_new_btn` | 517 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_list` | 528 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_edit_btn` | 535 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_dup_btn` | 536 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_del_btn` | 537 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.wf_runbg_btn` | 544 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._agent_panel` | 556 | `ui/co4e_tab.py` | AgentListPanel — panel đã tách sẵn ở presentation/co4e/agent_list_panel.py (ngoài phạm vi lát này) -- QUYET DINH: container giữ instance AgentListPanel (đã tách sẵn) — KHÔNG có trong bảng cũ (thiếu sót ở đó, ag_new_btn/agent_list/ag_edit_btn/ag_del_btn có dòng nhưng _agent_panel thì không) | chua | BANG CU BO SOT: khong co dong nao cho symbol nay du no ro rang ton tai trong pham vi da quet (367 symbol tho cua bang cu) -- co the do agent quet truoc bo lot. |
+| `Co4ETab.ag_new_btn` | 557 | `presentation/co4e/agent_list_panel.py` | alias trỏ tới self._agent_panel.new_btn — widget thật nằm ở agent_list_panel.py | co | - |
+| `Co4ETab.agent_list` | 559 | `presentation/co4e/agent_list_panel.py` | alias trỏ tới self._agent_panel.list_widget | co | - |
+| `Co4ETab.ag_edit_btn` | 560 | `presentation/co4e/agent_list_panel.py` | alias trỏ tới self._agent_panel.edit_btn | co | - |
+| `Co4ETab.ag_del_btn` | 562 | `presentation/co4e/agent_list_panel.py` | alias trỏ tới self._agent_panel.del_btn | co | - |
+| `Co4ETab._skills_panel` | 571 | `ui/co4e_tab.py` | SkillsListPanel — panel đã tách sẵn ở presentation/co4e/skills_list_panel.py (ngoài phạm vi lát này) -- QUYET DINH: container giữ instance SkillsListPanel (đã tách sẵn) — khớp bảng cũ | co | - |
+| `Co4ETab.sk_manage_btn` | 572 | `presentation/co4e/skills_list_panel.py` | alias trỏ tới self._skills_panel.manage_btn — cùng bản chất với ag_new_btn ở trên. Bảng cũ xếp dòng này (và skill_list) vào co4e_tab.py trong khi ag_* tương ứng lại xếp vào agent_list_panel.py — KHÔNG NHẤT QUÁN giữa 2 cặp alias giống hệt nhau trong cùng bảng cũ; ở đây chọn xử lý đồng nhất với ag_* | co | BANG CU KHONG NHAT QUAN: xep Co4ETab.sk_manage_btn vao ui/co4e_tab.py trong khi alias tuong duong ben Agent (ag_new_btn/agent_list/...) lai xep vao agent_list_panel.py; o day chon dong nhat -> presentation/co4e/skills_list_panel.py. |
+| `Co4ETab.skill_list` | 574 | `presentation/co4e/skills_list_panel.py` | alias trỏ tới self._skills_panel.list_widget — xem ghi chú ở sk_manage_btn | co | BANG CU KHONG NHAT QUAN: xep Co4ETab.skill_list vao ui/co4e_tab.py trong khi alias tuong duong ben Agent (ag_new_btn/agent_list/...) lai xep vao agent_list_panel.py; o day chon dong nhat -> presentation/co4e/skills_list_panel.py. |
+| `Co4ETab.runs_more_btn` | 582 | `ui/co4e_tab.py` | nút icon trong sidebar mở trang Runs (gọi self._show_runs(True)) — điểm vào trang Flow Status nhưng không phải một phần của bảng runs_table -- QUYET DINH: nút icon nằm trong sidebar (dựng bởi _build_sidebar, ở co4e_tab.py) mở trang Runs — không phải một phần của runs_table. Bảng cũ xếp vào co4e_run_control_widget.py vì cùng 'chủ đề Runs', nhưng nơi nó được XÂY lại là sidebar | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 586) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab.runs_side_list` | 590 | `ui/co4e_tab.py` | danh sách rút gọn các run trong sidebar — KHÁC với self.runs_table của trang Flow Status (định nghĩa ngoài dòng 700, có thể ở co4e_run_control_widget); dễ nhầm là cùng một bảng nên tách agent gộp cần đối chiếu -- QUYET DINH: danh sách rút gọn run trong sidebar, KHÁC self.runs_table của trang Flow Status — dựng trong _build_sidebar (co4e_tab.py). Mô tả đích của _build_runs_page nói rõ co4e_run_control_widget.py = bảng runs_table + nút hành động, không bao gồm sidebar quick-list | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 594) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._SIDE_RUNS` | 601 | `ui/co4e_tab.py` | hằng số class — số run hiển thị trong sidebar quick-list, không phải trang runs_table chính -- QUYET DINH: hằng số cho sidebar quick-list — cùng nhóm runs_side_list | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 605) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._refresh_side_runs` | 603-615 | `ui/co4e_tab.py` | đọc self.manager.runs(), ghi self.runs_side_list — sidebar quick-list, khác trang Flow Status runs_table -- QUYET DINH: cùng nhóm runs_side_list | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 607-619) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._on_side_run_clicked` | 617-625 | `ui/co4e_tab.py` | gọi self._show_runs(True) rồi đọc self.runs_table (định nghĩa ngoài dòng 1-700, khả năng ở co4e_run_control_widget) để chọn dòng tương ứng — điểm nối giữa sidebar quick-list và trang Runs, cần agent gộp đối chiếu với file định nghĩa runs_table -- QUYET DINH: handler click của sidebar quick-list; có đọc self.runs_table nên cần API cầu nối sang co4e_run_control_widget.py khi tách, nhưng bản thân handler thuộc sidebar nên ở co4e_tab.py | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 621-629) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._section` | 627-659 | `ui/co4e_tab.py` | helper dựng UI section chung cho sidebar, ghi vào self._sections[key] | co | - |
+| `Co4ETab._fold_section` | 661-673 | `ui/co4e_tab.py` | đọc self._sections | co | - |
+| `Co4ETab._sync_section_arrow` | 675-678 | `ui/co4e_tab.py` | đọc self._sections | co | - |
+| `Co4ETab._icon_btn` | 679-683 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._reload_sidebar` | 685-718 | `ui/co4e_tab.py` | [GOP 2 luot quet trung ky hieu dong 685] cắt ngang lát — cần agent gộp đối chiếu (thân method tiếp tục ngoài dòng 700); gọi co4e.list_workflows() nên chạm đĩa // cắt ngang lát — cần agent gộp đối chiếu (bắt đầu ở dòng 685, trước khoảng được giao 701-1400; phần thấy được chỉ là vòng lặp nạp custom agents + skills vào agent_list/skill_list) -- QUYET DINH: [GỘP 2 lượt quét trùng ký hiệu ở dòng 685] một agent đọc thân đến 700 (cắt ngang lát), agent kia đọc tới 718 (vòng lặp nạp agent/skill) — gộp thành 1 dòng 685-718; nạp lại toàn bộ sidebar, không phải trang Runs | co | - |
+| `Co4ETab._palette_item` | 720-724 | `ui/co4e_tab.py` | staticmethod tạo QListWidgetItem cho palette — không liên quan trang Runs -- QUYET DINH: factory QListWidgetItem cho palette — sidebar, không phải Runs | co | - |
+| `Co4ETab._build_center` | 727-867 | `ui/co4e_tab.py` | method dài >80 dòng, gộp nhiều việc không liên quan: dựng flow tab bar (QTabBar ẩn), gọi _build_runs_page() để nhét vào center_stack, dựng toolbar flow (name/add/save/mode/run/runs toggle), dựng canvas + overlay + splitter dọc với chat. Nên tách nhỏ. Gán self.center_stack — trạng thái chia sẻ dùng ở nhiều nơi (switch giữa trang Runs và flow editor, cả _show_runs ngoài lát này). -- QUYET DINH: dựng flow tab bar + toolbar + canvas/chat splitter; GỌI self._build_runs_page() để nhét vào center_stack — khi tách, chỗ gọi này đổi thành khởi tạo Co4ERunControlWidget(...) rồi add vào center_stack | co | - |
+| `Co4ETab.flow_bar` | 734 | `ui/co4e_tab.py` | QTabBar ẩn dùng làm index ánh xạ flow<->canvas, không phải trang Runs | co | - |
+| `Co4ETab.flow_add_btn` | 760 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.flow_scroll` | 777 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab.center_stack` | 801 | `ui/co4e_tab.py` | trạng thái chia sẻ giữa trang Runs (stack 0) và flow editor (stack 1) — dùng bởi _show_runs (ngoài lát này) để chuyển trang -- QUYET DINH: container sở hữu QStackedWidget chứa [trang Runs, flow editor]; trang Runs (index 0) sẽ LÀ instance Co4ERunControlWidget được add vào đây | co | - |
+| `Co4ETab._build_runs_page` | 869-928 | `presentation/co4e/co4e_run_control_widget.py` | khớp đúng mô tả đích: dựng bảng runs_table + nút back/stop/rename/delete/clear/mở-thư-mục-workspace | co | - |
+| `Co4ETab.runs_back_btn` | 878 | `presentation/co4e/co4e_run_control_widget.py` | - | co | - |
+| `Co4ETab.runs_title` | 883 | `presentation/co4e/co4e_run_control_widget.py` | - | co | - |
+| `Co4ETab.ws_folder_btn` | 888 | `presentation/co4e/co4e_run_control_widget.py` | nút mở thư mục workspace — click gọi self._open_workspace_folder (định nghĩa ngoài lát này, có khả năng touches_disk_or_network=true) | co | - |
+| `Co4ETab.run_stop_btn` | 896 | `presentation/co4e/co4e_run_control_widget.py` | - | co | - |
+| `Co4ETab.run_rename_btn` | 901 | `presentation/co4e/co4e_run_control_widget.py` | - | co | - |
+| `Co4ETab.run_del_btn` | 905 | `presentation/co4e/co4e_run_control_widget.py` | - | co | - |
+| `Co4ETab.run_clear_btn` | 909 | `presentation/co4e/co4e_run_control_widget.py` | click gọi self.manager.clear_finished() — self.manager là trạng thái chia sẻ (run manager) không định nghĩa trong lát này | co | - |
+| `Co4ETab.runs_table` | 917 | `presentation/co4e/co4e_run_control_widget.py` | bảng chính của trang Runs; double-click gọi self._open_run_from_table, context menu gọi self._runs_context_menu (cả hai định nghĩa ngoài lát này) | co | - |
+| `Co4ETab._wrap_config` | 930-960 | `ui/co4e_tab.py` | wrap panel cấu hình step, không thuộc trang Runs -- QUYET DINH: khung bọc/thu-phóng quanh StepConfigPanel — thuộc bố cục của co4e_tab.py, không phải nội dung panel. Bảng cũ xếp cả cụm này vào node_property_panel.py (file cấm sửa của lane khác) — không đúng vai trò 'khung bọc' vs 'nội dung panel' | co | - |
+| `Co4ETab.config_toggle_btn` | 942 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab.config_title` | 947 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab._cfg_vlayout` | 953 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab._cfg_top_spacer` | 957 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab._cfg_bot_spacer` | 958 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab.config_container` | 959 | `ui/co4e_tab.py` | thuộc khung bọc _wrap_config | co | - |
+| `Co4ETab._NARROW` | 967 | `ui/co4e_tab.py` | hằng số class-level, không liên quan trang Runs -- QUYET DINH: hằng số bố cục hẹp của cả tab | co | - |
+| `Co4ETab.showEvent` | 969-971 | `ui/co4e_tab.py` | Qt override, gắn narrow_guard -- QUYET DINH: [ANOMALY — 2 định nghĩa showEvent cùng tên trong 1 class, bảng cũ đã ghi nhận 'kept_separate_anomaly_symbols'] bản đầu (969-971) chỉ gắn narrow_guard, bị bản thứ 2 (1802) ghi đè lúc runtime; giữ TÁCH RIÊNG như bảng cũ | co | - |
+| `Co4ETab._apply_narrow_layout` | 973-983 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._toggle_config` | 985-1028 | `ui/co4e_tab.py` | không thuộc trang Runs; đọc/ghi self._split (splitter 3 cột chia sẻ với _build_center/_wrap_config) | co | - |
+| `Co4ETab._refresh_min_width` | 1030-1035 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._build_canvas_overlay` | 1037-1058 | `presentation/co4e/co4e_canvas_widget.py` | overlay zoom cho canvas — không thuộc trang Runs -- QUYET DINH: overlay zoom/fit gắn LÊN canvas qua self.canvas.add_overlay(); chấp nhận quyết định của bảng cũ — thuộc lane canvas, ngoài phạm vi run-control. Hiện tại canvas vẫn ở ui/co4e_canvas.py (chưa đổi tên), việc dời file này KHÔNG thuộc lane này | co | - |
+| `Co4ETab.zoom_in_btn` | 1050 | `presentation/co4e/co4e_canvas_widget.py` | nút overlay canvas — ngoài phạm vi run-control | co | - |
+| `Co4ETab.zoom_out_btn` | 1051 | `presentation/co4e/co4e_canvas_widget.py` | nút overlay canvas — ngoài phạm vi run-control | co | - |
+| `Co4ETab.fit_btn` | 1052 | `presentation/co4e/co4e_canvas_widget.py` | nút overlay canvas — ngoài phạm vi run-control | co | - |
+| `Co4ETab._build_chat` | 1060-1123 | `ui/co4e_tab.py` | method dài >60 dòng, dựng toàn bộ khung chat (header, stack theo flow, composer, routing toggle, usage total) — không thuộc trang Runs -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._chat_widget` | 1062 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._mhdr` | 1068 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.msgs_icon` | 1070 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.msgs_title` | 1071 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_toggle_btn` | 1072 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_stack` | 1087 | `ui/co4e_tab.py` | một ChatView mỗi flow — trạng thái chia sẻ đọc bởi _apply_workflow, _ensure_flow_log, _active_log -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._flow_logs` | 1088 | `ui/co4e_tab.py` | Dict[str, ChatView] theo wf.id — trạng thái chia sẻ giữa các tab flow -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_input_row` | 1090 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._usage_total_lbl` | 1095 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_input` | 1101 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_send_btn` | 1104 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.co4e_routing_toggle` | 1109 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._co4e_routed_provider` | 1110 | `ui/co4e_tab.py` | override provider định tuyến cho lượt kế tiếp — trạng thái đọc/ghi ở nhiều nơi ngoài lát này (dòng 1849, 1871, 1878) -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._vsplit_sizes` | 1117 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._msgs_collapsed` | 1118 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._toggle_messages` | 1125-1157 | `ui/co4e_tab.py` | expand/collapse khung chat, đọc/ghi self._vsplit — không thuộc trang Runs -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._ensure_flow_log` | 1160-1169 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._active_log` | 1171-1173 | `ui/co4e_tab.py` | khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab.chat_log` | 1175-1179 | `ui/co4e_tab.py` | property, không phải attribute gán trực tiếp — liệt kê vì là symbol công khai -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._plan_bubble` | 1181-1187 | `ui/co4e_tab.py` | property getter/setter, ủy quyền sang self._active_log()._co4e_plan_bubble -- QUYET DINH: khung CHAT — thuộc lane co4e_chat_view.py (chưa tồn tại); giữ nguyên ui/co4e_tab.py cho tới khi lane đó tách, ngoài phạm vi lane run-control. Bảng cũ đã xếp sẵn vào presentation/co4e/co4e_chat_view.py | co | - |
+| `Co4ETab._apply_workflow` | 1190-1204 | `ui/co4e_tab.py` | gán self._wf — trạng thái chia sẻ trung tâm của cả tab (đọc/ghi khắp nơi); gọi self.canvas.load/relayout/fit_view và self._update_run_btn/_refresh_usage_total (ngoài lát này) -- QUYET DINH: gán self._wf trung tâm — container | co | - |
+| `Co4ETab._new_workflow` | 1205-1213 | `ui/co4e_tab.py` | gọi self._open_flow (ngoài lát này) | co | - |
+| `Co4ETab._selected_wf` | 1215-1221 | `ui/co4e_tab.py` | co4e.get_workflow đọc storage — thuần logic sidebar, không thuộc trang Runs | co | - |
+| `Co4ETab._load_selected_workflow` | 1223-1226 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._edit_selected_workflow` | 1228-1233 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._duplicate_selected_workflow` | 1235-1242 | `application/workflows/co4e_workflow_service.py` | co4e.duplicate_workflow ghi storage -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._wf_context_menu` | 1244-1267 | `ui/co4e_tab.py` | menu chuột phải cho danh sách flow đã lưu, không phải trang Runs -- QUYET DINH: menu chuột phải cho danh sách flow đã lưu (sidebar) | co | - |
+| `Co4ETab._rename_workflow` | 1269-1285 | `application/workflows/co4e_workflow_service.py` | co4e.save_workflow ghi storage; đọc/ghi self._wf.name và self.name_edit -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._delete_selected_workflow` | 1287-1293 | `application/workflows/co4e_workflow_service.py` | co4e.delete_workflow ghi storage -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._sync_wf_from_canvas` | 1295-1298 | `ui/co4e_tab.py` | đọc self.canvas.nodes()/edges() và self.name_edit, ghi vào self._wf — trạng thái chia sẻ -- QUYET DINH: khớp bảng cũ | co | - |
+| `Co4ETab._save` | 1300-1305 | `application/workflows/co4e_workflow_service.py` | co4e.save_workflow ghi storage -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._autosave` | 1307-1310 | `application/workflows/co4e_workflow_service.py` | co4e.save_workflow ghi storage -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._on_name_changed` | 1312-1314 | `ui/co4e_tab.py` | gọi self._sync_active_flow_tab_text (ngoài lát này) | co | - |
+| `Co4ETab._add_blank_step` | 1316-1318 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._on_node_selected` | 1321-1327 | `ui/co4e_tab.py` | đọc self.canvas.nodes(), self.config, self._config_collapsed -- QUYET DINH: đọc canvas selection rồi TOGGLE khung bọc _wrap_config (self._config_collapsed) — thuộc container, không phải nội dung StepConfigPanel. Bảng cũ xếp vào node_property_panel.py — không đúng vai trò khung bọc vs nội dung panel | co | - |
+| `Co4ETab._on_config_changed` | 1329-1332 | `ui/co4e_tab.py` | cùng lý do với _on_node_selected | co | - |
+| `Co4ETab._new_agent` | 1335-1336 | `presentation/co4e/agent_list_panel.py` | khớp bảng cũ, ngoài phạm vi run-control | co | - |
+| `Co4ETab._edit_agent` | 1338-1346 | `presentation/co4e/agent_list_panel.py` | khớp bảng cũ, ngoài phạm vi run-control | co | - |
+| `Co4ETab._edit_agent_dialog` | 1348-1354 | `presentation/co4e/agent_list_panel.py` | co4e.save_custom_agent ghi storage; mở dialog Qt -- QUYET DINH: khớp bảng cũ, ngoài phạm vi run-control | co | - |
+| `Co4ETab._delete_agent` | 1356-1363 | `presentation/co4e/agent_list_panel.py` | co4e.delete_custom_agent ghi storage -- QUYET DINH: khớp bảng cũ, ngoài phạm vi run-control | co | - |
+| `Co4ETab._manage_skills` | 1365-1369 | `presentation/co4e/skills_list_panel.py` | mở SkillsDialog (Qt) -- QUYET DINH: khớp bảng cũ, ngoài phạm vi run-control | co | - |
+| `Co4ETab._skill_map` | 1372-1378 | `application/workflows/co4e_workflow_service.py` | logic thuần, không phải trang Runs — thuộc nhóm run/mode bị loại trừ khỏi run_control_widget theo mô tả đích -- QUYET DINH: đã có quyết định của lane workflow-service (bảng cũ); ngoài phạm vi run-control | co | - |
+| `Co4ETab._current_mode` | 1380-1381 | `ui/co4e_tab.py` | thuộc mode/run toolbar — loại trừ khỏi run_control_widget theo mô tả đích -- QUYET DINH: đọc mode_combo của toolbar mode/run — mô tả đích loại trừ nhóm mode/run khỏi co4e_run_control_widget.py; bảng cũ xếp vào đó — mâu thuẫn với phạm vi hiện tại | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1384-1385) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._on_mode_changed` | 1383-1389 | `ui/co4e_tab.py` | reset self._manual_active/_manual_order/_manual_idx — thuộc mode/run toolbar, loại trừ khỏi run_control_widget theo mô tả đích -- QUYET DINH: cùng nhóm mode/run toolbar — xem lý do ở _current_mode | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1387-1393) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._on_run_clicked` | 1391-1400 | `ui/co4e_tab.py` | cắt ngang lát — cần agent gộp đối chiếu (thân method tiếp tục sau dòng 1400). Đây là logic thực thi run — loại trừ khỏi run_control_widget theo mô tả đích; gọi self.manager.stop (trạng thái chia sẻ run manager) -- QUYET DINH: logic bấm nút Run (thực thi) — cùng nhóm bị loại trừ, xem lý do ở _current_mode | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1395-1400) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._start_canvas_run` | 1403-1420 | `ui/co4e_tab.py` | logic khởi chạy run trên canvas (không phải bảng Flow Status); đọc/ghi self._wf, self._flows tiles, self._flow_runs, self._run_logs — trạng thái chia sẻ với _on_manager_event và _manual_step | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1407-1424) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._plan_bubble` | 1413 | `ui/co4e_tab.py` | gán lại None khi bắt đầu run mới; cũng gán ở _manual_run_or_advance (1457) và đọc/ghi trong _append_plan qua log._co4e_plan_bubble — có thể đã khởi tạo lần đầu ở __init__ ngoài phạm vi đọc | co (nhung o dong khac: 1186-1187) | - |
+| `Co4ETab._run_single` | 1422-1427 | `ui/co4e_tab.py` | - | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1426-1431) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._run_from` | 1429-1433 | `ui/co4e_tab.py` | - | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1433-1437) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._downstream` | 1435-1446 | `ui/co4e_tab.py` | đọc self.canvas.edges() — chỉ cần canvas object tồn tại, không cần app hiển thị; logic đồ thị thuần | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1439-1450) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_run_or_advance` | 1449-1462 | `ui/co4e_tab.py` | khởi tạo self._manual_order/_manual_idx/_manual_active — trạng thái mode thủ công, không liên quan bảng Flow Status | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1453-1466) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_order` | 1458 | `ui/co4e_tab.py` | trạng thái mode thủ công, dùng bởi _manual_step; có thể đã khởi tạo ở __init__ ngoài phạm vi đọc | co (nhung o dong khac: 253) | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 253) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_idx` | 1459 | `ui/co4e_tab.py` | trạng thái mode thủ công, dùng bởi _manual_step/_on_manager_event | co (nhung o dong khac: 254) | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 254) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_active` | 1460 | `ui/co4e_tab.py` | trạng thái mode thủ công, đọc bởi _on_manager_event | co (nhung o dong khac: 252) | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 252) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._manual_step` | 1464-1480 | `ui/co4e_tab.py` | ghi self._flow_runs[wf.id] và self._run_logs[run_id] — dict chia sẻ với _start_canvas_run/_on_manager_event | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1468-1484) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._topo_order` | 1482-1487 | `ui/co4e_tab.py` | đọc self.canvas.nodes()/edges() — thuần logic sắp xếp topo | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1486-1491) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._on_manager_event` | 1490-1546 | `ui/co4e_tab.py` | method gộp nhiều việc không liên quan: routing event theo loại (node_status/node_output/node_diff/node_plan/node_tool/run_done/error), cập nhật canvas, ghi self._outputs_for, dọn self._flow_runs/self._run_logs, gọi popup thông báo — nên tách nhỏ thêm dù chưa vượt 80 dòng. KHÔNG thuộc bảng Flow Status (không đụng runs_table trực tiếp), là logic thực thi run nên ở lại co4e_tab.py theo _doc | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1494-1550) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._notify_run_finished` | 1548-1569 | `ui/co4e_tab.py` | tạo QMessageBox không chặn, ghi self._run_popups — popup thông báo chung, không phải phần bảng Flow Status | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1552-1573) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._run_popups` | 1557 | `ui/co4e_tab.py` | danh sách giữ tham chiếu QMessageBox không-chặn để tránh bị GC — khởi tạo có điều kiện (hasattr) ngay trong _notify_run_finished thay vì __init__ | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1560-1561) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._refresh_runs` | 1571-1612 | `presentation/co4e/co4e_run_control_widget.py` | dựng lại bảng self.runs_table từ manager — đúng lõi 'Flow Status'; cũng đụng self._sections và self.flow_bar (tab text 'RUNS N') và gọi self._refresh_side_runs() — trạng thái chia sẻ với sidebar/tab strip ngoài phạm vi widget này, cần API cầu nối khi tách | co | - |
+| `Co4ETab._stop_selected_run` | 1614-1620 | `presentation/co4e/co4e_run_control_widget.py` | nút Stop của bảng Flow Status | co | - |
+| `Co4ETab._delete_selected_run` | 1622-1635 | `presentation/co4e/co4e_run_control_widget.py` | nút Delete; ghi self._flow_runs.pop/self._run_logs.pop — dict chia sẻ với logic thực thi run ở co4e_tab.py | co | - |
+| `Co4ETab._runs_context_menu` | 1637-1651 | `presentation/co4e/co4e_run_control_widget.py` | context menu của runs_table (open run/output/rename/delete); action 'open_run' gọi self._open_run_from_table vốn cần self._open_flow + self.canvas (ở co4e_tab.py) — cần callback cầu nối khi tách | co | - |
+| `Co4ETab.set_project` | 1654-1670 | `ui/co4e_tab.py` | đọc/ghi self._project_id, self._project_dir; gọi load_project (đọc đĩa) và manager.set_output_root/set_current_project; gọi self._refresh_ws_folder_btn() thuộc widget Flow Status — cần API cầu nối khi tách ra co4e_run_control_widget.py | co | - |
+| `Co4ETab._project_id` | 1659 | `ui/co4e_tab.py` | trạng thái workspace hiện tại, dùng bởi manager.set_current_project và các hàm mở thư mục — chia sẻ giữa co4e_tab.py và co4e_run_control_widget.py | co (nhung o dong khac: 249) | - |
+| `Co4ETab._project_dir` | 1660 | `ui/co4e_tab.py` | dùng bởi _flow_output_root — ảnh hưởng trực tiếp tới nút 'mở thư mục workspace' của Flow Status | co (nhung o dong khac: 250) | - |
+| `Co4ETab._flow_output_root` | 1672-1682 | `ui/co4e_tab.py` | helper Path dùng chung bởi cả chat (_out_dir) và nút 'mở thư mục workspace' của Flow Status (_open_workspace_folder/_refresh_ws_folder_btn) — widget Flow Status cần được truyền hàm này qua callback/property thay vì tự tính | co | - |
+| `Co4ETab._refresh_ws_folder_btn` | 1684-1689 | `presentation/co4e/co4e_run_control_widget.py` | cập nhật self.ws_folder_btn (nút mở thư mục workspace) — phụ thuộc self._flow_output_root() ở co4e_tab.py | co | - |
+| `Co4ETab._open_workspace_folder` | 1691-1698 | `presentation/co4e/co4e_run_control_widget.py` | hành động của nút 'mở thư mục workspace'; mkdir + open_location (spawn process) | co | - |
+| `Co4ETab._open_run_output_folder` | 1700-1711 | `presentation/co4e/co4e_run_control_widget.py` | mở thư mục output của 1 run cụ thể — dùng trong context menu bảng Flow Status; mkdir + open_location | co | - |
+| `Co4ETab._rename_selected_run` | 1713-1744 | `presentation/co4e/co4e_run_control_widget.py` | nút Rename của bảng Flow Status; nhưng đồng bộ qua self._flows, self.flow_bar.setTabText, self.name_edit — trạng thái tab/canvas chia sẻ với co4e_tab.py, cần callback cầu nối; co4e.save_workflow ghi đĩa | co | - |
+| `Co4ETab._run_selected_in_background` | 1746-1756 | `ui/co4e_tab.py` | chạy 1 flow được chọn (self._selected_wf(), không rõ nguồn — có thể là danh sách sidebar chứ không phải runs_table); gọi self._refresh_side_runs() — không khớp mô tả 'CHỈ bảng Flow Status' nên giữ ở co4e_tab.py | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1750-1760) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._wf_by_id` | 1758-1766 | `ui/co4e_tab.py` | co4e.get_workflow đọc file workflow đã lưu trên đĩa; helper dùng chung nhiều nơi (rerun, open-from-table) | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1762-1770) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._rerun_run_item` | 1768-1779 | `ui/co4e_tab.py` | docstring nói 'double-click a run in the history' nhưng item.data(Qt.UserRole) trực tiếp gợi ý đây là list sidebar 'side runs', KHÔNG phải bảng Flow Status (khác cách _open_run_from_table truy cập runs_table qua item.row()) — cần người quyết đây thuộc trang nào -- QUYET DINH: gọi self.manager.start(...) tức THỰC THI run (network/AI) — cùng nhóm run-execution bị loại trừ khỏi co4e_run_control_widget.py; bảng cũ xếp vào đó. Nghi vấn về nguồn item (sidebar hay bảng) không đổi kết luận vì lý do loại trừ là do HÀNH VI thực thi chứ không phải nơi click | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1772-1783) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab._open_run_from_table` | 1781-1800 | `ui/co4e_tab.py` | double-click bảng Flow Status nhưng gọi self._open_flow (chuyển tab) và self.canvas.update_node_status trực tiếp — vượt ra ngoài phạm vi 'chỉ bảng runs_table' nên giữ ở co4e_tab.py, cần callback nếu tách runs_table riêng | co | BANG CU SAI/QUA RONG: xep vao presentation/co4e/co4e_run_control_widget.py (dong 1785-1804) nhung pham vi run-control hien tai (mo ta dich cua 3 agent quet) loai tru nhom nay -> quyet dinh o day = ui/co4e_tab.py. |
+| `Co4ETab.showEvent` | 1802-1805 | `ui/co4e_tab.py` | override Qt lifecycle của chính Co4ETab, gọi self._refresh_runs() — phải ở lại widget chính | co | - |
+| `Co4ETab._out_dir` | 1807-1813 | `ui/co4e_tab.py` | mkdir; dùng cho chat/flow deliverables, không liên quan bảng Flow Status | co | - |
+| `Co4ETab._chat_send` | 1816-1842 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._apply_co4e_routing` | 1844-1879 | `ui/co4e_tab.py` | ghi self._co4e_routed_provider; nhánh 'manual' dựng dialog confirm_switch(self,...) nên cần widget sống | co | - |
+| `Co4ETab._co4e_routed_provider` | 1849 | `ui/co4e_tab.py` | dùng bởi _run_chat_turn để chọn provider — reset mỗi lần _apply_co4e_routing chạy | co | - |
+| `Co4ETab._extract_agent_directive` | 1881-1887 | `ui/co4e_tab.py` | thuần regex, test được không cần Qt | co | - |
+| `Co4ETab._resolve_agent` | 1889-1897 | `ui/co4e_tab.py` | co4e.list_custom_agents() đọc dữ liệu agent tuỳ biến đã lưu | co | - |
+| `Co4ETab._run_chat_turn` | 1899-1970 | `ui/co4e_tab.py` | method dài, gộp: dựng prompt, chạy AgentWorker nền gọi provider AI (network), stream sự kiện vào bubble Qt, cập nhật usage — nên tách nhỏ thêm dù chỉ 72 dòng vì nhiều trách nhiệm khác nhau (build prompt / worker job / event routing / usage). Không liên quan bảng Flow Status | co | - |
+| `Co4ETab._chat_worker` | 1953 | `ui/co4e_tab.py` | vị trí xuất hiện đầu tiên theo văn bản là trong hàm lồng 'done'; gán thật sự lúc chạy là dòng 1969 (w = AgentWorker...); có thể đã khởi tạo None ở __init__ ngoài phạm vi đọc | co (nhung o dong khac: 236) | - |
+| `Co4ETab._append_chat` | 1972-1987 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._fmt_usage` | 1990-1997 | `ui/co4e_tab.py` | thuần formatting, không cần Qt | co | - |
+| `Co4ETab._apply_usage` | 1999-2016 | `ui/co4e_tab.py` | ghi self._flow_usage[wf_id] — tổng usage theo flow, chia sẻ với _refresh_usage_total | co | - |
+| `Co4ETab._refresh_usage_total` | 2018-2033 | `ui/co4e_tab.py` | đọc self._flow_usage và self._wf — trạng thái chia sẻ với _apply_usage | co | - |
+| `Co4ETab._append_diff` | 2035-2039 | `ui/co4e_tab.py` | - | co | - |
+| `Co4ETab._append_plan` | 2041-2052 | `ui/co4e_tab.py` | ghi log._co4e_plan_bubble — thuộc tính gắn động lên ChatView, chia sẻ với _run_chat_turn | co | - |
+| `Co4ETab._retranslate` | 2055-2075 | `ui/co4e_tab.py` | gộp retranslate cho CẢ widget chung (wf_new_btn, self._sections) LẪN các nút riêng của Flow Status (runs_back_btn, run_stop_btn, run_rename_btn, run_del_btn, run_clear_btn, runs_table headers, ws_folder_btn) — khi tách co4e_run_control_widget.py cần chia method này làm hai, phần Flow Status nên có retranslate riêng gọi từ đây | co | - |
+| `_html_escape` | 2078-2079 | `ui/co4e_tab.py` | hàm module-level thuần string escape; không thấy nơi gọi trong phạm vi 1401-2084 nên chưa rõ nó phục vụ phần nào — có thể dùng ở phần chat render ngoài phạm vi đọc -- QUYET DINH: escape string thuần cho phần render CHAT — lane co4e_chat_view.py (chưa tồn tại); bảng cũ đã xếp sẵn vào đó, ngoài phạm vi run-control nên giữ nguyên vị trí vật lý hiện tại | co | - |
+| `_qcolor` | 2082-2084 | `presentation/co4e/co4e_run_control_widget.py` | QColor là kiểu giá trị (như QPointF/QRectF), không cần QApplication sống; chỉ thấy dùng trong _refresh_runs (tô màu cột status của bảng Flow Status) trong phạm vi đọc | co | - |
+
+## Chỗ thấy khác tài liệu — cần người quyết
+
+Không có symbol nào trong 215 symbol thô có note bắt đầu bằng `khac tai lieu:` — mục này để trống theo đúng yêu cầu tự kiểm (không có gì cần liệt kê).

docs/architecture/co4e-split-map.md

@@ -0,0 +1,407 @@
+# Bản đồ tách file Co4E (gộp từ 6 agent quét song song)
+
+- Tổng số symbol quét được (thô, tính cả trùng): **367**
+- Tổng số dòng trong bản đồ cuối cùng (sau gộp trùng): **363**
+- Số nhóm ký hiệu bị quét trùng bởi 2 agent (đã gộp làm 1 dòng): 4 (Co4ECanvas.dropEvent, Co4ETab._co4e_routed_provider, Co4ETab._config_expanded_w, Co4ETab._reload_sidebar)
+- Số ký hiệu có 2 định nghĩa thật ở 2 dòng khác nhau, giữ riêng và gắn cờ: 1 (Co4ETab.showEvent)
+- EXPECTED (tools/check_co4e.py) có **27** phần tử; kết quả đối chiếu: OK — cả 27 xuất hiện đúng 1 lần, có target cụ thể
+- Số note bắt đầu bằng `khac tai lieu:`: **0** (không có -> không có mục 'Chỗ thấy khác tài liệu' nào phát sinh từ tiêu chí này)
+
+## Ghi chú về gộp trùng (5 ký hiệu bị 2 agent cùng quét thấy)
+
+### `Co4ETab._config_expanded_w`
+- dòng 275-275, target agent gốc đề xuất = `presentation/co4e/co4e_tab.py` — cùng lý do với _config_collapsed
+- dòng 995-995, target agent gốc đề xuất = `presentation/co4e/co4e_tab.py` — gán trong nhánh collapse của _toggle_config; có thể đã khởi tạo trong __init__ (ngoài phạm vi đọc).
+- **Quyết định gộp**: 1 dòng, target cuối = `presentation/co4e/co4e_tab.py`, dòng 275; 995
+
+### `Co4ETab._reload_sidebar`
+- dòng 689-700, target agent gốc đề xuất = `presentation/co4e/co4e_tab.py` — cắt ngang lát — cần agent gộp đối chiếu (method tiếp tục sau dòng 700); gọi co4e.list_workflows() (đọc đĩa) rồi dựng QListWidgetItem trực tiếp trong cùng hàm — trộn data-fetch và UI, nên tách phần đọc dữ liệu sang co4e_workflow_service.py
+- dòng 689-722, target agent gốc đề xuất = `unsure` — cắt ngang lát — cần agent gộp đối chiếu (bắt đầu trước dòng 701). Gộp refresh cả agent_list và skill_list trong cùng 1 hàm — nên tách thành _refresh_agents_list (agent_list_panel.py) và _refresh_skills_list (skills_list_panel.py) như plan.md yêu cầu; gọi co4e.list_custom_agents() (đĩa) và skills_mod.skill_prefix_for (đĩa).
+- **Quyết định gộp**: 1 dòng, target cuối = `presentation/co4e/co4e_tab.py`, dòng 689-722
+
+### `Co4ETab.showEvent`
+- dòng 973-975, target agent gốc đề xuất = `presentation/co4e/co4e_tab.py` — Qt override, gọi self._narrow_guard.attach() (đối tượng khởi tạo ngoài phạm vi đọc, <701).
+- dòng 1806-1809, target agent gốc đề xuất = `presentation/co4e/co4e_tab.py` — override Qt lifecycle method của chính QWidget container nên phải ở lại co4e_tab.py; gọi self._refresh_runs() (thuộc co4e_run_control_widget.py) — điểm nối giữa container và run-control widget.
+- **Quyết định**: đây là 2 định nghĩa method trùng tên thật sự tồn tại ở 2 vị trí khác nhau trong cùng class `Co4ETab` (khả năng cao là lỗi nguồn — định nghĩa sau đè định nghĩa trước, làm dòng logic ở định nghĩa trước thành dead code). Giữ nguyên 2 dòng riêng biệt trong bản đồ, KHÔNG gộp, và cần người quyết định giữ định nghĩa nào.
+
+### `Co4ETab._co4e_routed_provider`
+- dòng 1114-1114, target agent gốc đề xuất = `presentation/co4e/co4e_chat_view.py` — override provider cho lượt chat kế tiếp — dùng bởi _apply_co4e_routing (ngoài phạm vi đọc, >1400).
+- dòng 1853-1853, target agent gốc đề xuất = `presentation/co4e/co4e_chat_view.py` — gán None lần đầu tại đây (trong _apply_co4e_routing); đọc bằng getattr(self, '_co4e_routed_provider', None) ở _run_chat_turn dòng ~1922 — gợi ý có thể không được init trong __init__. Trạng thái routing theo từng lượt chat, dùng chung giữa chat-view và _start_canvas_run/manager.start.
+- **Quyết định gộp**: 1 dòng, target cuối = `presentation/co4e/co4e_chat_view.py`, dòng 1114; 1853
+
+### `Co4ECanvas.dropEvent`
+- dòng 683-700, target agent gốc đề xuất = `presentation/co4e/co4e_canvas_widget.py` — cắt ngang lát — cần agent gộp đối chiếu (thân try chưa đóng ở dòng 700, còn tiếp; xử lý JSON từ mimeData trong bộ nhớ, không phải file đĩa nên touches_disk_or_network=false)
+- dòng 683-701, target agent gốc đề xuất = `presentation/co4e/co4e_canvas_widget.py` — cắt ngang lát — cần agent gộp đối chiếu. Method dropEvent bắt đầu ở dòng 683 (ngoài khoảng được giao 701-791), chỉ dòng 701 (e.acceptProposedAction()) nằm trong lát này; dòng 702 là dòng trống cuối file. File ui/co4e_canvas.py chỉ có 702 dòng — không có nội dung nào khác trong khoảng 702-791 vì đã hết file. Xử lý drop từ sidebar (kind=='workflow' → add_workflow, ngược lại → add_palette_step) — logic thao tác node/canvas nên khớp nhóm _add_node/_connect_nodes trong bảng plan.md dòng 623 dù plan.md không liệt kê rõ dropEvent.
+- **Quyết định gộp**: 1 dòng, target cuối = `presentation/co4e/co4e_canvas_widget.py`, dòng 683-701
+
+## Bảng đầy đủ
+
+| symbol | dòng | file đích | lý do | có trong bảng cũ chưa | chỗ nào thấy bảng cũ sai |
+|---|---|---|---|---|---|
+| Co4ETab._flow_outputs | 245 | application/workflows/co4e_workflow_service.py | state per-flow outputs — ứng viên chuyển vào state machine thuần Python | chua/khong ro | - |
+| Co4ETab._outputs_for | 475-478 | application/workflows/co4e_workflow_service.py | truy cập dict state per-flow outputs, thuần Python | chua/khong ro | - |
+| Co4ETab._duplicate_selected_workflow | 1239-1246 | application/workflows/co4e_workflow_service.py | tương ứng _duplicate_flow() trong bảng plan.md dòng 616, nhưng tên hàm thực tế khác (_duplicate_selected_workflow). Gộp gọi service (co4e.duplicate_workflow, đĩa) với cập nhật UI (self._reload_sidebar(), self.status_message.emit) — cần tách; phần UI nên ở lại co4e_tab.py. | co | ate_flow() trong bảng plan.md dòng 616, nhưng tên hàm thực tế khác (_duplicate_selected_workflow). Gộp gọi service (co4e.duplicate_workflow, đĩa) |
+| Co4ETab._rename_workflow | 1273-1289 | application/workflows/co4e_workflow_service.py | mở QInputDialog (cần Qt) rồi gọi co4e.save_workflow (đĩa), đồng bộ self._wf.name/self.name_edit nếu flow đang mở là flow bị đổi tên — gộp UI dialog + service + trạng thái chia sẻ self._wf trong 1 hàm, nên tách. | chua/khong ro | - |
+| Co4ETab._delete_selected_workflow | 1291-1297 | application/workflows/co4e_workflow_service.py | tương ứng _delete_flow() trong bảng plan.md dòng 616; gọi co4e.delete_workflow (đĩa). | co | - |
+| Co4ETab._save | 1304-1309 | application/workflows/co4e_workflow_service.py | gộp _sync_wf_from_canvas (đọc canvas UI), lưu đĩa (co4e.save_workflow), và cập nhật UI (_reload_sidebar, status_message) — cần tách phần service khỏi phần UI khi chuyển sang co4e_workflow_service.py. | chua/khong ro | - |
+| Co4ETab._autosave | 1311-1314 | application/workflows/co4e_workflow_service.py | gọi self._sync_wf_from_canvas() (cần canvas) rồi co4e.get_workflow/save_workflow (đĩa). | chua/khong ro | - |
+| Co4ETab._skill_map | 1376-1382 | application/workflows/co4e_workflow_service.py | chuẩn bị nội dung skill (skills_mod.skill_prefix_for, đọc đĩa) để đưa vào lúc chạy flow/chat — không có trong bảng plan.md, tự xếp theo chức năng (dùng lúc run/build system prompt, không phải UI danh sách skill). | co | ọc đĩa) để đưa vào lúc chạy flow/chat — không có trong bảng plan.md, tự xếp theo chức năng (dùng lúc run/build system prompt, không phải UI danh sá |
+| Co4ETab.ag_new_btn | 550 | presentation/co4e/agent_list_panel.py | hiện định nghĩa trực tiếp trong Co4ETab._build_sidebar — ứng viên chuyển sang agent_list_panel.py tương tự cách skills đã tách | chua/khong ro | - |
+| Co4ETab.agent_list | 558 | presentation/co4e/agent_list_panel.py | cùng lý do với ag_new_btn | chua/khong ro | - |
+| Co4ETab.ag_edit_btn | 562 | presentation/co4e/agent_list_panel.py | cùng lý do với ag_new_btn | chua/khong ro | - |
+| Co4ETab.ag_del_btn | 563 | presentation/co4e/agent_list_panel.py | cùng lý do với ag_new_btn | chua/khong ro | - |
+| Co4ETab._new_agent | 1339-1340 | presentation/co4e/agent_list_panel.py | tương ứng _create_agent() trong bảng plan.md dòng 620 (tên hàm thực tế là _new_agent). | co | - |
+| Co4ETab._edit_agent | 1342-1350 | presentation/co4e/agent_list_panel.py | khớp _edit_agent() dòng 620 plan.md; gọi co4e.list_custom_agents() (đĩa). | co | - |
+| Co4ETab._edit_agent_dialog | 1352-1358 | presentation/co4e/agent_list_panel.py | mở Co4EAgentDialog rồi co4e.save_custom_agent (đĩa) và self._reload_sidebar() — trạng thái chia sẻ, liên quan tới cắt ngang lát ở _reload_sidebar. | chua/khong ro | - |
+| Co4ETab._delete_agent | 1360-1367 | presentation/co4e/agent_list_panel.py | khớp _delete_agent() dòng 620 plan.md; gọi co4e.delete_custom_agent (đĩa). | co | - |
+| _status_color | 43-50 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem | 59-210 | presentation/co4e/co4e_canvas_widget.py | class nội bộ gắn chặt với Co4ECanvas qua self.canvas backreference — nên đi cùng file với Co4ECanvas | chua/khong ro | - |
+| _NodeItem.__init__ | 62-72 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.node | 64 | presentation/co4e/co4e_canvas_widget.py | giữ tham chiếu domain Node — dữ liệu chia sẻ với core/co4e.py | chua/khong ro | - |
+| _NodeItem.canvas | 65 | presentation/co4e/co4e_canvas_widget.py | backreference tới Co4ECanvas cha — mọi event của _NodeItem đều gọi ngược lên canvas (add_step_below, begin_connect, delete_node, các signal) — điểm khớp nối chặt nhất trong file | chua/khong ro | - |
+| _NodeItem.status | 66 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem._porting | 67 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.boundingRect | 74-76 | presentation/co4e/co4e_canvas_widget.py | trả QRectF như kiểu giá trị, logic thuần | chua/khong ro | - |
+| _NodeItem._card_rect | 78-79 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.paint | 81-139 | presentation/co4e/co4e_canvas_widget.py | vẽ toàn bộ card: nền, header stripe, label, badge role, preview instructions/sub-agents, footer model/skills, 2 port — gộp nhiều việc nhưng vẫn dưới 80 dòng nên chưa bắt buộc tách thêm | chua/khong ro | - |
+| _NodeItem._in_out_port | 141-143 | presentation/co4e/co4e_canvas_widget.py | hình học thuần dùng QPointF như kiểu giá trị | chua/khong ro | - |
+| _NodeItem.itemChange | 145-156 | presentation/co4e/co4e_canvas_widget.py | ghi self.node.x/y rồi gọi self.canvas._reposition_edges() và emit self.canvas.graph_changed/node_selected — chạm trạng thái chia sẻ của canvas cha | chua/khong ro | - |
+| _NodeItem.hoverMoveEvent | 158-161 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.mousePressEvent | 163-174 | presentation/co4e/co4e_canvas_widget.py | đọc/ghi self.canvas._connect_from, gọi canvas._finish_connect/begin_port_drag — trạng thái connect-mode chia sẻ với Co4ECanvas | chua/khong ro | - |
+| _NodeItem.mouseMoveEvent | 176-181 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.mouseReleaseEvent | 183-189 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.mouseDoubleClickEvent | 191-193 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _NodeItem.contextMenuEvent | 195-207 | presentation/co4e/co4e_canvas_widget.py | gọi canvas.add_step_below/begin_connect/delete_node — trạng thái/hành vi thuộc canvas cha | chua/khong ro | - |
+| _NodeItem.center | 209-210 | presentation/co4e/co4e_canvas_widget.py | trả QPointF như kiểu giá trị | chua/khong ro | - |
+| _EdgeItem | 213-286 | presentation/co4e/co4e_canvas_widget.py | class nội bộ gắn chặt với Co4ECanvas qua self.canvas backreference | chua/khong ro | - |
+| _EdgeItem.__init__ | 214-225 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.edge | 216 | presentation/co4e/co4e_canvas_widget.py | tham chiếu domain Edge — chia sẻ với core/co4e.py | chua/khong ro | - |
+| _EdgeItem.canvas | 217 | presentation/co4e/co4e_canvas_widget.py | backreference tới Co4ECanvas — contextMenuEvent gọi canvas.delete_edge | chua/khong ro | - |
+| _EdgeItem._dst | 218 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem._hover | 224 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem._apply_pen | 227-235 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.update_path | 237-239 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.boundingRect | 241-242 | presentation/co4e/co4e_canvas_widget.py | gọi super().boundingRect() phụ thuộc trạng thái path sống của item | chua/khong ro | - |
+| _EdgeItem.shape | 244-249 | presentation/co4e/co4e_canvas_widget.py | dùng QPainterPathStroker trên self.path() sống của item | chua/khong ro | - |
+| _EdgeItem.hoverEnterEvent | 251-255 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.hoverLeaveEvent | 257-261 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.paint | 263-279 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _EdgeItem.contextMenuEvent | 281-286 | presentation/co4e/co4e_canvas_widget.py | gọi self.canvas.delete_edge(self.edge) | chua/khong ro | - |
+| Co4ECanvas | 289-700 | presentation/co4e/co4e_canvas_widget.py | cắt ngang lát — class tiếp tục sau dòng 700 (dropEvent chưa kết thúc, có thể còn method khác chưa đọc) — cần agent gộp đối chiếu với phần đọc dòng 701+ | chua/khong ro | - |
+| Co4ECanvas.node_selected | 290 | presentation/co4e/co4e_canvas_widget.py | Signal được node_property_panel.py (và co4e_tab.py) nối vào để nạp node được chọn — điểm chia sẻ giữa canvas và property panel | chua/khong ro | - |
+| Co4ECanvas.node_activated | 291 | presentation/co4e/co4e_canvas_widget.py | Signal double-click, có thể được co4e_tab.py nối để mở panel chỉnh sửa — cần kiểm nơi consume | chua/khong ro | - |
+| Co4ECanvas.graph_changed | 292 | presentation/co4e/co4e_canvas_widget.py | Signal báo graph đổi (autosave) — nhiều khả năng được co4e_tab.py/co4e_workflow_service.py nối để lưu flow, trạng thái chia sẻ xuyên lớp application | chua/khong ro | - |
+| Co4ECanvas.__init__ | 296-315 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._scene | 299 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._nodes | 305 | presentation/co4e/co4e_canvas_widget.py | dict id->_NodeItem — trạng thái trung tâm được đọc/ghi bởi gần như mọi method của Co4ECanvas (add/delete/relayout/zoom/status/route edges) | chua/khong ro | - |
+| Co4ECanvas._edges | 306 | presentation/co4e/co4e_canvas_widget.py | list _EdgeItem — trạng thái trung tâm tương tự self._nodes | chua/khong ro | - |
+| Co4ECanvas._connect_from | 307 | presentation/co4e/co4e_canvas_widget.py | trạng thái connect-mode, cũng được _NodeItem.mousePressEvent đọc/ghi qua self.canvas | chua/khong ro | - |
+| Co4ECanvas._zoom | 308 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._panning | 309 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._pan_start | 310 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._overlay | 311 | presentation/co4e/co4e_canvas_widget.py | widget zoom/fit overlay được co4e_tab.py hoặc co4e_canvas_widget.py truyền vào qua add_overlay() | chua/khong ro | - |
+| Co4ECanvas._port_src | 313 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._port_src_pt | 314 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._temp_edge | 315 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.add_overlay | 318-323 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._place_overlay | 325-330 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.resizeEvent | 332-334 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.scrollContentsBy | 336-341 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.showEvent | 343-345 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.load | 348-362 | presentation/co4e/co4e_canvas_widget.py | reset toàn bộ self._nodes/self._edges/self._connect_from/self._port_src/self._temp_edge — điểm nạp lại state từ flow, được co4e_tab.py hoặc co4e_workflow_service.py gọi khi mở flow | chua/khong ro | - |
+| Co4ECanvas.nodes | 364-365 | presentation/co4e/co4e_canvas_widget.py | chỉ đọc .node từ self._nodes, không gọi API Qt trực tiếp | chua/khong ro | - |
+| Co4ECanvas.edges | 367-368 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.add_node | 371-382 | presentation/co4e/co4e_canvas_widget.py | ghi self._nodes, scene.addItem, emit graph_changed/node_selected — trạng thái chia sẻ với property panel qua node_selected | chua/khong ro | - |
+| Co4ECanvas.add_step_below | 384-390 | presentation/co4e/co4e_canvas_widget.py | orchestration thuần, ủy quyền cho add_node (bản thân không gọi trực tiếp API Qt) | chua/khong ro | - |
+| Co4ECanvas._chain_tail | 392-396 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.add_palette_step | 398-400 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.begin_connect | 402-403 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._finish_connect | 405-409 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.begin_port_drag | 412-419 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.update_port_drag | 421-424 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.finish_port_drag | 426-435 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._node_at | 437-441 | presentation/co4e/co4e_canvas_widget.py | dùng self._scene.items(scene_pt) — cần scene đang sống | chua/khong ro | - |
+| Co4ECanvas._make_edge | 443-451 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._add_edge_item | 453-456 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.delete_edge | 458-463 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.delete_node | 465-475 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.delete_selected | 477-481 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._zoom_by | 484-495 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.zoom_in | 497-498 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.zoom_out | 500-501 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.reset_zoom | 503-505 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.wheelEvent | 507-519 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.mousePressEvent | 522-529 | presentation/co4e/co4e_canvas_widget.py | trùng tên với _NodeItem.mousePressEvent nhưng là override của Co4ECanvas (pan chuột giữa) — đừng nhầm khi gộp map | chua/khong ro | - |
+| Co4ECanvas.mouseMoveEvent | 531-540 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.mouseReleaseEvent | 542-548 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.fit_view | 550-558 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.relayout | 560-578 | presentation/co4e/co4e_canvas_widget.py | phần tính waves/cols (compute_waves, defaultdict) là logic thuần, phần item.setPos() cần scene sống — có thể tách hàm tính toạ độ ra khỏi phần apply nếu muốn test thuần Python | chua/khong ro | - |
+| Co4ECanvas.relayout_if_vertical | 580-589 | presentation/co4e/co4e_canvas_widget.py | bản thân chỉ ra quyết định thuần dựa trên node.x, việc chạm Qt nằm trong relayout() được gọi | chua/khong ro | - |
+| Co4ECanvas.add_workflow | 591-610 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.update_node_status | 612-616 | presentation/co4e/co4e_canvas_widget.py | được co4e_run_control_widget.py gọi khi step chạy/xong/lỗi — điểm nối giữa canvas và run control | chua/khong ro | - |
+| Co4ECanvas.reset_statuses | 618-621 | presentation/co4e/co4e_canvas_widget.py | được co4e_run_control_widget.py gọi khi bắt đầu run mới | chua/khong ro | - |
+| Co4ECanvas.refresh_node | 623-626 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas._node_rects | 628-638 | presentation/co4e/co4e_canvas_widget.py | dựng QRectF như kiểu giá trị từ item.pos() — logic hình học thuần | chua/khong ro | - |
+| Co4ECanvas._reposition_edges | 640-649 | presentation/co4e/co4e_canvas_widget.py | gọi e.update_path (setPath) trên item sống, dùng hàm định tuyến _route từ canvas_geometry.py | chua/khong ro | - |
+| Co4ECanvas.keyPressEvent | 652-669 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.dragEnterEvent | 671-675 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.dragMoveEvent | 677-681 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ECanvas.dropEvent | 683-701 | presentation/co4e/co4e_canvas_widget.py | [GỘP 2 lượt quét trùng ký hiệu] (dòng 683-700, target gốc=presentation/co4e/co4e_canvas_widget.py) cắt ngang lát — cần agent gộp đối chiếu (thân try chưa đóng ở dòng 700, còn tiếp; xử lý JSON từ mimeData trong bộ nhớ, không phải file đĩa nên touches_disk_or_network=false) \|\| (dòng 683-701, target gốc=presentation/co4e/co4e_canvas_widget.py) cắt ngang lát — cần agent gộp đối chiếu. Method dropEvent bắt đầu ở dòng 683 (ngoài khoảng được giao 701-791), chỉ dòng 701 (e.acceptProposedAction()) nằm trong lát này; dòng 702 là dòng trống cuối file. File ui/co4e_canvas.py chỉ có 702 dòng — không có nội dung nào khác trong khoảng 702-791 vì đã hết file. Xử lý drop từ sidebar (kind=='workflow' → add_workflow, ngược lại → add_palette_step) — logic thao tác node/canvas nên khớp nhóm _add_node/_connect_nodes trong bảng plan.md dòng 623 dù plan.md không liệt kê rõ dropEvent. | co | nnect_nodes trong bảng plan.md dòng 623 dù plan.md không liệt kê rõ dropEvent. |
+| Co4ETab.canvas | 856 | presentation/co4e/co4e_canvas_widget.py | TRẠNG THÁI CHIA SẺ lớn nhất trong file — self.canvas được đọc/ghi ở gần như mọi nhóm chức năng khác (sync_wf_from_canvas, apply_workflow, node selection, run, add_blank_step...). | chua/khong ro | - |
+| Co4ETab._build_canvas_overlay | 1041-1062 | presentation/co4e/co4e_canvas_widget.py | dựng nút zoom/fit gắn vào self.canvas.add_overlay(bar); các slot gọi thẳng self.canvas.zoom_in/zoom_out/fit_view (thuộc nhóm 3.2.2.21-22 trong plan.md → co4e_canvas_widget.py). Có thể tranh cãi nên giữ ở co4e_tab.py (được gọi từ _build_center) — ghi lại để người soát quyết. | co | - |
+| Co4ETab.zoom_in_btn | 1054 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.zoom_out_btn | 1055 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.fit_btn | 1056 | presentation/co4e/co4e_canvas_widget.py | (không có ghi chú) | chua/khong ro | - |
+| _skill_names | 61-65 | presentation/co4e/co4e_chat_view.py | gọi skills_mod.list_skills()/builtin_skills() (đọc đĩa); dùng cho autocomplete /skill: trong _ChatInput — cũng liên quan skills_list_panel.py vì cùng nguồn dữ liệu | chua/khong ro | - |
+| _agent_names | 68-71 | presentation/co4e/co4e_chat_view.py | gọi co4e.list_custom_agents() (đọc đĩa); dùng cho autocomplete /agent: trong _ChatInput — cũng liên quan agent_list_panel.py vì cùng nguồn dữ liệu | chua/khong ro | - |
+| _directive_token | 122-134 | presentation/co4e/co4e_chat_view.py | logic regex thuần Python, test được không cần Qt | chua/khong ro | - |
+| _ChatInput | 137-226 | presentation/co4e/co4e_chat_view.py | khai báo 'submit = Signal()' ở dòng 141 là thuộc tính lớp (không phải self.) | chua/khong ro | - |
+| _ChatInput.__init__ | 143-151 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| _ChatInput._popup | 145 | presentation/co4e/co4e_chat_view.py | QListWidget popup autocomplete | chua/khong ro | - |
+| _ChatInput._maybe_popup | 153-178 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| _ChatInput._add_row | 180-184 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| _ChatInput._accept | 186-199 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| _ChatInput.focusOutEvent | 201-204 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| _ChatInput.keyPressEvent | 206-226 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._chat_worker | 236 | presentation/co4e/co4e_chat_view.py | AgentWorker của chat, hiện giữ trên Co4ETab | chua/khong ro | - |
+| Co4ETab._build_chat | 1064-1127 | presentation/co4e/co4e_chat_view.py | dài ~63 dòng, gộp: header 'Messages' + toggle, chat_stack (QStackedWidget chứa 1 ChatView/flow), input row + usage label + composer + routing toggle. Tạo self._flow_logs (Dict[str, ChatView]) — TRẠNG THÁI CHIA SẺ dùng bởi _ensure_flow_log/_active_log/chat_log/_apply_workflow (self._wf) — điểm dễ vỡ nhất khi tách file chat ra khỏi co4e_tab.py. | chua/khong ro | - |
+| Co4ETab._chat_widget | 1066 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._mhdr | 1072 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.msgs_icon | 1074 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.msgs_title | 1075 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.chat_toggle_btn | 1076 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.chat_stack | 1091 | presentation/co4e/co4e_chat_view.py | chuyển self.center_stack tương tự — dùng chung với self.center_stack (co4e_tab.py). | chua/khong ro | - |
+| Co4ETab._flow_logs | 1092 | presentation/co4e/co4e_chat_view.py | Dict[str, ChatView] keyed theo workflow id — TRẠNG THÁI CHIA SẺ chính của toàn bộ logic chat theo-flow; đọc/ghi bởi _ensure_flow_log, _active_log, chat_log, _apply_workflow, và các hàm chat khác ngoài phạm vi đọc (>1400). | chua/khong ro | - |
+| Co4ETab.chat_input_row | 1094 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._usage_total_lbl | 1099 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.chat_input | 1105 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.chat_send_btn | 1108 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.co4e_routing_toggle | 1113 | presentation/co4e/co4e_chat_view.py | RoutingToggle(self.ctx, 'co4e') — self.ctx là trạng thái chia sẻ của cả Co4ETab (khởi tạo ngoài phạm vi đọc). | chua/khong ro | - |
+| Co4ETab._co4e_routed_provider | 1114; 1853 | presentation/co4e/co4e_chat_view.py | [GỘP 2 lượt quét trùng ký hiệu] (dòng 1114-1114, target gốc=presentation/co4e/co4e_chat_view.py) override provider cho lượt chat kế tiếp — dùng bởi _apply_co4e_routing (ngoài phạm vi đọc, >1400). \|\| (dòng 1853-1853, target gốc=presentation/co4e/co4e_chat_view.py) gán None lần đầu tại đây (trong _apply_co4e_routing); đọc bằng getattr(self, '_co4e_routed_provider', None) ở _run_chat_turn dòng ~1922 — gợi ý có thể không được init trong __init__. Trạng thái routing theo từng lượt chat, dùng chung giữa chat-view và _start_canvas_run/manager.start. | chua/khong ro | [GỘP 2 lượt quét trùng ký hiệu] (dòng 1114-1114, target gốc=presentation/co4e/co4e_chat_view.py) overr |
+| Co4ETab._vsplit_sizes | 1121 | presentation/co4e/co4e_chat_view.py | dùng bởi _toggle_messages để restore kích thước splitter — chia sẻ với self._vsplit (co4e_tab.py). | chua/khong ro | - |
+| Co4ETab._msgs_collapsed | 1122 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._toggle_messages | 1129-1161 | presentation/co4e/co4e_chat_view.py | thao tác self._vsplit (tạo ở co4e_tab.py/_build_center) — trạng thái chia sẻ giữa co4e_chat_view.py và co4e_tab.py. | chua/khong ro | - |
+| Co4ETab._ensure_flow_log | 1164-1173 | presentation/co4e/co4e_chat_view.py | đọc/ghi self._flow_logs — trạng thái chia sẻ chính của chat theo-flow. | chua/khong ro | - |
+| Co4ETab._active_log | 1175-1177 | presentation/co4e/co4e_chat_view.py | đọc self._wf — trạng thái chia sẻ với toàn bộ Co4ETab (canvas, sidebar, save/autosave, run control). | chua/khong ro | - |
+| Co4ETab.chat_log | 1180-1183 | presentation/co4e/co4e_chat_view.py | @property, chỉ đọc, uỷ nhiệm cho _active_log(). | chua/khong ro | - |
+| Co4ETab._plan_bubble | 1186-1187 | presentation/co4e/co4e_chat_view.py | @property getter, đọc self._active_log()._co4e_plan_bubble (thuộc tính gắn thêm vào từng instance ChatView). | chua/khong ro | - |
+| Co4ETab._plan_bubble (setter) | 1189-1191 | presentation/co4e/co4e_chat_view.py | @_plan_bubble.setter, ghi self._active_log()._co4e_plan_bubble. | chua/khong ro | - |
+| Co4ETab._chat_send | 1820-1846 | presentation/co4e/co4e_chat_view.py | self.chat_input.clear(), self._append_chat — thao tác widget; điều phối /agent /skill directive rồi gọi self._run_chat_turn (network qua provider, không trực tiếp trong hàm này) | chua/khong ro | - |
+| Co4ETab._apply_co4e_routing | 1848-1883 | presentation/co4e/co4e_chat_view.py | gọi confirm_switch (dialog Qt) khi mode=='manual' và self._append_chat khi có switch — cần widget sống. Gán self._co4e_routed_provider (xem attribute riêng). | chua/khong ro | - |
+| Co4ETab._extract_agent_directive | 1885-1891 | presentation/co4e/co4e_chat_view.py | regex thuần Python | chua/khong ro | - |
+| Co4ETab._resolve_agent | 1893-1901 | presentation/co4e/co4e_chat_view.py | tra cứu BUILTIN_AGENTS và co4e.list_custom_agents() (bộ nhớ/đĩa tùy triển khai list_custom_agents, không rõ trong khoảng đọc) — cross-reference với agent_list_panel.py (nguồn danh sách custom agent) | chua/khong ro | - |
+| Co4ETab._run_chat_turn | 1903-1974 | presentation/co4e/co4e_chat_view.py | 72 dòng, gộp: chuẩn bị prompt, tạo bubble stream, định nghĩa 4 closures nội bộ (job/on_event/done/failed) và khởi worker nền — nên tách các closures ra thành hàm riêng nếu dễ đọc hơn. Closure job() gọi run_cowork(provider,...) — network/AI call thật sự. Đọc/ghi self._chat_worker, self._co4e_routed_provider, self.chat_send_btn, self._wf; set log._co4e_plan_bubble=None (thuộc log là ChatView, không phải self). | chua/khong ro | - |
+| Co4ETab._run_chat_turn.job | 1917-1946 | presentation/co4e/co4e_chat_view.py | closure nội bộ của _run_chat_turn, chạy trong AgentWorker (thread nền); gọi run_cowork(provider,...) — network/AI call thật; dùng usage_tracker (đọc/ghi trạng thái tích lũy usage) | chua/khong ro | - |
+| Co4ETab._run_chat_turn.on_event | 1948-1954 | presentation/co4e/co4e_chat_view.py | closure nội bộ, cập nhật assistant.set_markdown và log.scroll_to_bottom (widget) | chua/khong ro | - |
+| Co4ETab._run_chat_turn.done | 1956-1962 | presentation/co4e/co4e_chat_view.py | closure nội bộ, gán self._chat_worker = None, thao tác widget assistant/log | chua/khong ro | - |
+| Co4ETab._run_chat_turn.failed | 1964-1967 | presentation/co4e/co4e_chat_view.py | closure nội bộ, gán self._chat_worker = None, gọi self._append_chat lỗi | chua/khong ro | - |
+| Co4ETab._append_chat | 1976-1991 | presentation/co4e/co4e_chat_view.py | nhận tham số log tùy chọn, mặc định self.chat_log — dùng bởi rất nhiều method ở cả run-control (qua tham số log truyền vào) và chat-view; điểm nối giữa hai nhóm. | chua/khong ro | - |
+| Co4ETab._fmt_usage | 1994-2001 | presentation/co4e/co4e_chat_view.py | format chuỗi thuần, đọc self.ctx.config.data — không chạm widget | chua/khong ro | - |
+| Co4ETab._apply_usage | 2003-2020 | presentation/co4e/co4e_chat_view.py | bub.add_usage(...) thao tác widget bubble; ghi self._flow_usage[wf_id] — trạng thái tổng usage theo flow, dùng chung với _refresh_usage_total | chua/khong ro | - |
+| Co4ETab._refresh_usage_total | 2022-2037 | presentation/co4e/co4e_chat_view.py | self._usage_total_lbl.setText — đọc self._wf, self._flow_usage | chua/khong ro | - |
+| Co4ETab._append_diff | 2039-2043 | presentation/co4e/co4e_chat_view.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._append_plan | 2045-2056 | presentation/co4e/co4e_chat_view.py | đọc/ghi log._co4e_plan_bubble (thuộc tính động trên đối tượng log/ChatView, không phải self) | chua/khong ro | - |
+| _html_escape | 2082-2083 | presentation/co4e/co4e_chat_view.py | hàm module-level (ngoài class Co4ETab), escape HTML thuần, dùng cho hiển thị chat | chua/khong ro | - |
+| _PLAN_GLYPH | 45-46 | presentation/co4e/co4e_run_control_widget.py | module-level dict glyph trạng thái dùng bởi _fmt_plan | chua/khong ro | - |
+| _fmt_plan | 49-58 | presentation/co4e/co4e_run_control_widget.py | helper thuần Python dùng bởi _render_plan() | chua/khong ro | - |
+| Co4ETab.manager | 238 | presentation/co4e/co4e_run_control_widget.py | Co4ERunManager — lõi run control, trạng thái chia sẻ với canvas (node status) và chat view (run_logs) | chua/khong ro | - |
+| Co4ETab._flow_runs | 243 | presentation/co4e/co4e_run_control_widget.py | map wf_id->run id, chia sẻ với _open_flow/_close_flow_tab (co4e_tab.py) và canvas | chua/khong ro | - |
+| Co4ETab._run_logs | 244 | presentation/co4e/co4e_run_control_widget.py | map run_id->ChatView, chia sẻ với co4e_chat_view.py | chua/khong ro | - |
+| Co4ETab._flow_usage | 248 | presentation/co4e/co4e_run_control_widget.py | usage token/cost theo flow, hiển thị ở Messages header | chua/khong ro | - |
+| Co4ETab._manual_active | 252 | presentation/co4e/co4e_run_control_widget.py | chia sẻ với _close_flow_tab (co4e_tab.py) — set lại self.run_btn khi đóng tab | chua/khong ro | - |
+| Co4ETab._manual_order | 253 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._manual_idx | 254 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._cur_run_id | 460-473 | presentation/co4e/co4e_run_control_widget.py | logic thuần Python, không gọi Qt trực tiếp | chua/khong ro | - |
+| Co4ETab._update_run_btn | 480-482 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.runs_more_btn | 586 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.runs_side_list | 594 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._SIDE_RUNS | 605 | presentation/co4e/co4e_run_control_widget.py | class-level constant, không phải self. | chua/khong ro | - |
+| Co4ETab._refresh_side_runs | 607-619 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._on_side_run_clicked | 621-629 | presentation/co4e/co4e_run_control_widget.py | chạm self.runs_table (định nghĩa ngoài khoảng đọc — thuộc trang Flow Status) | chua/khong ro | - |
+| Co4ETab.mode_combo | 828 | presentation/co4e/co4e_run_control_widget.py | combo chọn run mode auto/plan/manual — thuộc nhóm _set_run_mode() trong plan.md dù được dựng bên trong _build_center (co4e_tab.py); ranh giới tách file ở đây dễ vỡ. | co | - |
+| Co4ETab.run_btn | 833 | presentation/co4e/co4e_run_control_widget.py | nút Run — tương tự mode_combo, dựng trong _build_center nhưng thuộc nhóm run control; cũng bị _update_run_btn (<701), _on_run_clicked, _on_mode_changed đọc/ghi text. | chua/khong ro | - |
+| Co4ETab.runs_btn | 840 | presentation/co4e/co4e_run_control_widget.py | toggle chuyển sang trang Runs (self.center_stack) — chia sẻ state center_stack với co4e_tab.py. | chua/khong ro | - |
+| Co4ETab._build_runs_page | 873-932 | presentation/co4e/co4e_run_control_widget.py | dựng trang bảng Runs (theo dõi mọi run của mọi flow) — dùng self.manager (Co4ERunManager, sẽ thay bằng co4e_workflow_service) — trạng thái chia sẻ. | chua/khong ro | - |
+| Co4ETab.runs_back_btn | 882 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.runs_title | 887 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.ws_folder_btn | 892 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.run_stop_btn | 900 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.run_rename_btn | 905 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.run_del_btn | 909 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.run_clear_btn | 913 | presentation/co4e/co4e_run_control_widget.py | clicked gọi self.manager.clear_finished() — trạng thái chia sẻ self.manager. | chua/khong ro | - |
+| Co4ETab.runs_table | 921 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._current_mode | 1384-1385 | presentation/co4e/co4e_run_control_widget.py | đọc self.mode_combo — khớp nhóm _set_run_mode() dòng 624 plan.md. | co | - |
+| Co4ETab._on_mode_changed | 1387-1393 | presentation/co4e/co4e_run_control_widget.py | reset self._manual_active/_manual_order/_manual_idx (trạng thái chia sẻ với luồng manual step _manual_step/_manual_run_or_advance, ngoài phạm vi đọc >1400) và gọi self._cur_run_id() (chia sẻ với self.manager). | chua/khong ro | - |
+| Co4ETab._on_run_clicked | 1395-1400 | presentation/co4e/co4e_run_control_widget.py | cắt ngang lát — cần agent gộp đối chiếu (tiếp tục sau dòng 1400). Dùng self.manager.stop() và self._cur_run_id() — trạng thái chia sẻ với co4e_workflow_service tương lai. Khớp nhóm _run_flow()/_stop_flow() dòng 618 plan.md (dù đó là bản service, đây là UI handler nút Run). | co | - |
+| Co4ETab.<method truoc dong 1401, ten chua xac dinh - co the la _on_run_clicked> | 1401-1405 | presentation/co4e/co4e_run_control_widget.py | cắt ngang lát — cần agent gộp đối chiếu. Định nghĩa (def ...) nằm ở lát trước dòng 1401 nên tên chính xác không xác định được; đoạn thấy được chỉ dispatch theo self._current_mode() sang _manual_run_or_advance() hoặc _start_canvas_run() — thuộc nhóm Run/mode. | chua/khong ro | (def ...) nằm ở lát trước dòng 1401 nên tên chính xác không xác định được; đoạn thấy được chỉ dispatch theo self._current_mode() sang _manual_run_or |
+| Co4ETab._start_canvas_run | 1407-1424 | presentation/co4e/co4e_run_control_widget.py | gọi self.manager.start(...) — spawn chạy flow (dẫn tới gọi provider AI ở tầng khác); đọc/ghi self._wf, self._flow_runs, self._flow_runs[wf_id], self._run_logs, self.chat_log — trạng thái chia sẻ giữa run-control và chat-view. self.manager (Co4ERunManager) nên đổi sang application/workflows/co4e_workflow_service.py theo mapping. | chua/khong ro | - |
+| Co4ETab._run_single | 1426-1431 | presentation/co4e/co4e_run_control_widget.py | wrapper mỏng gọi _start_canvas_run; đọc self._wf.id | chua/khong ro | - |
+| Co4ETab._run_from | 1433-1437 | presentation/co4e/co4e_run_control_widget.py | wrapper mỏng gọi _start_canvas_run với self._downstream(node_id) | chua/khong ro | - |
+| Co4ETab._downstream | 1439-1450 | presentation/co4e/co4e_run_control_widget.py | thuật toán BFS thuần Python, chỉ đọc self.canvas.edges() làm input — test được với danh sách edge giả lập, không cần canvas thật | chua/khong ro | - |
+| Co4ETab._manual_run_or_advance | 1453-1466 | presentation/co4e/co4e_run_control_widget.py | gọi self.canvas.reset_statuses() và self._append_chat (self._append_chat thuộc nhóm chat-view) — cắt ngang giữa run-control và chat-view. Đọc/ghi self._manual_active, self._manual_order, self._manual_idx, self._wf, self._outputs_for(...), self._plan_bubble — trạng thái run thuần túy chia sẻ với _manual_step. | chua/khong ro | - |
+| Co4ETab._manual_step | 1468-1484 | presentation/co4e/co4e_run_control_widget.py | gọi self.manager.start(...) (network/AI qua provider) và self.run_btn.setText, self._append_chat (chat-view); đọc/ghi self._manual_idx, self._manual_order, self._wf, self._flow_runs, self._run_logs, self.chat_log — trạng thái chia sẻ rộng giữa run-control và chat-view. | chua/khong ro | - |
+| Co4ETab._topo_order | 1486-1491 | presentation/co4e/co4e_run_control_widget.py | đọc self.canvas.nodes()/edges() làm dữ liệu đầu vào, logic tính toán thuần túy (co4e.compute_waves) — test được với dữ liệu giả | chua/khong ro | - |
+| Co4ETab._on_manager_event | 1494-1550 | presentation/co4e/co4e_run_control_widget.py | method dài (57 dòng), gộp nhiều việc không liên quan: định tuyến sự kiện chạy theo từng flow (routing run_id -> log), cập nhật trạng thái node trên canvas, hiển thị bubble chat (assistant/diff/plan/tool-failed — thuộc co4e_chat_view.py), xử lý hoàn tất run (run_done/run_error), hiển thị popup thông báo, cập nhật status bar. Nên tách phần hiển thị chat (self._append_chat/_append_diff/_append_plan) sang co4e_chat_view.py, giữ phần routing/flow-completion ở co4e_run_control_widget.py. Đọc/ghi self._flow_runs, self._run_logs, self.chat_log, self.canvas, self._wf, self._outputs_for(...), self._manual_active, self._manual_idx — trạng thái chia sẻ rất rộng, điểm dễ vỡ nhất khi tách file. | chua/khong ro | - |
+| Co4ETab._notify_run_finished | 1552-1573 | presentation/co4e/co4e_run_control_widget.py | tạo QMessageBox không chặn; khởi tạo lazy self._run_popups (xem attribute riêng) | chua/khong ro | - |
+| Co4ETab._run_popups | 1560-1561 | presentation/co4e/co4e_run_control_widget.py | khởi tạo lazy (list rỗng) trong _notify_run_finished qua hasattr guard — không init trong __init__; giữ ref các QMessageBox non-blocking khỏi bị GC | chua/khong ro | - |
+| Co4ETab._refresh_runs | 1575-1616 | presentation/co4e/co4e_run_control_widget.py | render bảng runs_table + gọi self._refresh_side_runs() (sidebar) + cập nhật self.flow_bar.setTabText và self._sections['co4e.runs_tab'] — self._sections và self.flow_bar là trạng thái chia sẻ với co4e_tab.py (container/sidebar). | chua/khong ro | - |
+| Co4ETab._stop_selected_run | 1618-1624 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._delete_selected_run | 1626-1639 | presentation/co4e/co4e_run_control_widget.py | đọc/ghi self._flow_runs, self._run_logs — trạng thái chia sẻ với _on_manager_event/_start_canvas_run | chua/khong ro | - |
+| Co4ETab._runs_context_menu | 1641-1655 | presentation/co4e/co4e_run_control_widget.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._open_run_output_folder | 1704-1715 | presentation/co4e/co4e_run_control_widget.py | path.mkdir + open_location (spawn process); dùng bởi _runs_context_menu 'Open output' | chua/khong ro | - |
+| Co4ETab._rename_selected_run | 1717-1748 | presentation/co4e/co4e_run_control_widget.py | gọi co4e.save_workflow(wf) (ghi đĩa); đọc/ghi self._flows (list flow của sidebar/tab-bar), self.flow_bar, self.name_edit, self._wf — chạm nhiều trạng thái chia sẻ với co4e_tab.py container (tab bar + name edit thuộc header, không rõ nằm ở panel nào) — rủi ro vỡ cao khi tách. | chua/khong ro | - |
+| Co4ETab._run_selected_in_background | 1750-1760 | presentation/co4e/co4e_run_control_widget.py | gọi self.manager.start(...) (network/AI) và self._refresh_side_runs() (widget) | chua/khong ro | - |
+| Co4ETab._wf_by_id | 1762-1770 | presentation/co4e/co4e_run_control_widget.py | gọi co4e.get_workflow(wf_id) (đọc đĩa) và self._sync_wf_from_canvas() (không nằm trong khoảng đọc) — đọc self._wf; dùng chung bởi _rerun_run_item/_open_run_from_table (Runs tab) và có thể cả co4e_tab.py container | chua/khong ro | - |
+| Co4ETab._rerun_run_item | 1772-1783 | presentation/co4e/co4e_run_control_widget.py | gọi self.manager.start(...) (network/AI) | chua/khong ro | - |
+| Co4ETab._open_run_from_table | 1785-1804 | presentation/co4e/co4e_run_control_widget.py | gọi self._open_flow(wf) (không nằm trong khoảng đọc, theo plan.md thuộc co4e_tab.py) và self.canvas.update_node_status — nối Runs tab với việc mở flow trên canvas, điểm khớp nối giữa run-control và container/canvas. | co | - |
+| _qcolor | 2086-2088 | presentation/co4e/co4e_run_control_widget.py | hàm module-level (ngoài class Co4ETab), tạo QColor từ hex string — dùng kiểu giá trị QColor, không cần QApplication sống; dùng trong _refresh_runs để tô màu status | chua/khong ro | - |
+| _EqualTabBar | 74-94 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| _EqualTabBar._GAP | 80 | presentation/co4e/co4e_tab.py | class-level constant, không phải self. | chua/khong ro | - |
+| _EqualTabBar.tabSizeHint | 82-90 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| _EqualTabBar.resizeEvent | 92-94 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab | 229-700 | presentation/co4e/co4e_tab.py | Lớp kéo dài quá dòng 700 (cắt ngang lát) — chỉ ghi nhận phần 229-700; 'status_message = Signal(str)' dòng 230 là thuộc tính lớp, không phải self. | chua/khong ro | - |
+| Co4ETab.__init__ | 232-304 | presentation/co4e/co4e_tab.py | method 73 dòng, gộp: khởi state run/flow, dựng splitter 3 cột (sidebar/center/config), wiring canvas & config panel, gọi _reload_sidebar (đọc đĩa qua co4e.list_workflows) và _open_flow; chạm rất nhiều thuộc tính chia sẻ: self._wf, self._flows, self.manager, self._flow_runs, self._run_logs, self._flow_outputs, self._flow_usage, self.config, self.canvas (gán ở _build_center ngoài khoảng đọc này) | chua/khong ro | - |
+| Co4ETab.ctx | 234 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._wf | 235 | presentation/co4e/co4e_tab.py | trạng thái chia sẻ — đọc/ghi bởi canvas, run control, chat view | chua/khong ro | - |
+| Co4ETab._flows | 257 | presentation/co4e/co4e_tab.py | danh sách flow đang mở dạng tab — trạng thái chia sẻ nhạy cảm (nêu rõ trong hướng dẫn đề bài) | chua/khong ro | - |
+| Co4ETab._active_flow_idx | 258 | presentation/co4e/co4e_tab.py | chỉ số tab đang active — chia sẻ giữa _open_flow, _on_flow_tab_changed, _reflect_active_run | chua/khong ro | - |
+| Co4ETab._split | 261 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._config_collapsed | 274 | presentation/co4e/co4e_tab.py | trạng thái cho _toggle_config (định nghĩa dòng 989, ngoài khoảng đọc); plan.md xếp _toggle_config ở co4e_tab.py container | co | - |
+| Co4ETab._config_expanded_w | 275; 995 | presentation/co4e/co4e_tab.py | [GỘP 2 lượt quét trùng ký hiệu] (dòng 275-275, target gốc=presentation/co4e/co4e_tab.py) cùng lý do với _config_collapsed \|\| (dòng 995-995, target gốc=presentation/co4e/co4e_tab.py) gán trong nhánh collapse của _toggle_config; có thể đã khởi tạo trong __init__ (ngoài phạm vi đọc). | chua/khong ro | [GỘP 2 lượt quét trùng ký hiệu] (dòng 275-275, target gốc=presentation/co4e/co4e_tab.py) cùng lý do vớ |
+| Co4ETab._narrow_guard | 280 | presentation/co4e/co4e_tab.py | gắn với _apply_narrow_layout (dòng 977, ngoài khoảng đọc) | chua/khong ro | - |
+| Co4ETab._open_flow | 307-338 | presentation/co4e/co4e_tab.py | khớp plan.md: _open_flow() -> co4e_tab.py, gọi canvas; chạm self._flows, self.flow_bar (định nghĩa ngoài khoảng đọc), self.canvas | co | - |
+| Co4ETab._close_other_flows | 340-355 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._show_runs | 357-367 | presentation/co4e/co4e_tab.py | chuyển đổi center_stack giữa flow editor và Runs table — liên quan Flow Status (run control) | chua/khong ro | - |
+| Co4ETab._on_flow_tab_changed | 369-385 | presentation/co4e/co4e_tab.py | chạm self.center_stack (định nghĩa ngoài khoảng đọc, ở _build_center) | chua/khong ro | - |
+| Co4ETab._sync_runs_toggle | 387-394 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._add_tab_close_button | 396-406 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._close_flow_tab_button | 408-412 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._close_flow_tab | 414-442 | presentation/co4e/co4e_tab.py | chạm self._flow_runs/_run_logs/_manual_active/self.run_btn (chia sẻ với run control widget) | chua/khong ro | - |
+| Co4ETab._sync_active_flow_tab_text | 444-447 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._build_sidebar | 485-603 | presentation/co4e/co4e_tab.py | >80 dòng (119 dòng) — gộp dựng 4 section (Workflows/Agents/Skills/Runs) + wiring nhiều nút bấm; nên tách theo section: Workflows giữ ở container, Agents nên chuyển agent_list_panel.py, Skills đã tách (chỉ còn wiring), Runs nên chuyển co4e_run_control_widget.py | chua/khong ro | - |
+| Co4ETab._sections | 493 | presentation/co4e/co4e_tab.py | trạng thái chia sẻ (nêu rõ trong hướng dẫn đề bài) — dùng bởi _fold_section, _sync_section_arrow | chua/khong ro | - |
+| Co4ETab.sidebar | 494 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.side_split | 498 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| _Col | 503-511 | presentation/co4e/co4e_tab.py | adapter nội bộ định nghĩa bên trong _build_sidebar, chỉ dùng tại chỗ | chua/khong ro | - |
+| _Col.__init__ | 506-507 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| _Col.addWidget | 509-511 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_new_btn | 516 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_list | 527 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_edit_btn | 534 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_dup_btn | 535 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_del_btn | 536 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.wf_runbg_btn | 543 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._skills_panel | 575 | presentation/co4e/co4e_tab.py | instantiate SkillsListPanel đã tách; Co4ETab giữ wiring theo comment trong code (dòng 571-574) | chua/khong ro | - |
+| Co4ETab.sk_manage_btn | 576 | presentation/co4e/co4e_tab.py | cùng lý do với _skills_panel | chua/khong ro | - |
+| Co4ETab.skill_list | 578 | presentation/co4e/co4e_tab.py | cùng lý do với _skills_panel | chua/khong ro | - |
+| Co4ETab._section | 631-663 | presentation/co4e/co4e_tab.py | chạm self._sections (chia sẻ) — helper dựng section sidebar dùng chung | chua/khong ro | - |
+| Co4ETab._fold_section | 665-677 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._sync_section_arrow | 679-681 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._icon_btn | 683-687 | presentation/co4e/co4e_tab.py | helper dùng chung tạo nút icon, dùng bởi cả section Workflows và Agents | chua/khong ro | - |
+| Co4ETab._reload_sidebar | 689-722 | presentation/co4e/co4e_tab.py | [GỘP 2 lượt quét trùng ký hiệu] (dòng 689-700, target gốc=presentation/co4e/co4e_tab.py) cắt ngang lát — cần agent gộp đối chiếu (method tiếp tục sau dòng 700); gọi co4e.list_workflows() (đọc đĩa) rồi dựng QListWidgetItem trực tiếp trong cùng hàm — trộn data-fetch và UI, nên tách phần đọc dữ liệu sang co4e_workflow_service.py \|\| (dòng 689-722, target gốc=unsure) cắt ngang lát — cần agent gộp đối chiếu (bắt đầu trước dòng 701). Gộp refresh cả agent_list và skill_list trong cùng 1 hàm — nên tách thành _refresh_agents_list (agent_list_panel.py) và _refresh_skills_list (skills_list_panel.py) như plan.md yêu cầu; gọi co4e.list_custom_agents() (đĩa) và skills_mod.skill_prefix_for (đĩa). | co | [GỘP 2 lượt quét trùng ký hiệu] (dòng 689-700, target gốc=presentation/co4e/co4e_tab.py) cắt ngang lát |
+| Co4ETab._build_center | 731-871 | presentation/co4e/co4e_tab.py | dài ~140 dòng, làm nhiều việc không liên quan: dựng flow tab bar (ẩn, không hiển thị cho user), dựng runs-page stack, toolbar flow (name_edit/save/save_tpl/mode_combo/run_btn/runs_btn), tạo canvas, gọi _build_canvas_overlay, tạo chat widget, splitter dọc self._vsplit. Nên tách nhỏ. Đọc self._wf.name (dòng 814) và tạo self.center_stack — TRẠNG THÁI CHIA SẺ dùng bởi _show_runs/_apply_workflow (ngoài phạm vi đọc). Khớp phần '_build_canvas()' trong bảng plan.md dòng 615. | co | - |
+| Co4ETab.flow_bar | 738 | presentation/co4e/co4e_tab.py | QTabBar bị ẩn (setVisible False dòng 802), chỉ dùng làm index nội bộ ánh xạ flow↔canvas — trạng thái chia sẻ với _on_flow_tab_changed/_close_flow_tab (định nghĩa <701, ngoài phạm vi đọc). | chua/khong ro | - |
+| Co4ETab.flow_add_btn | 764 | presentation/co4e/co4e_tab.py | ẩn (setVisible False), không hiển thị cho user hiện tại. | chua/khong ro | - |
+| Co4ETab.flow_scroll | 781 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.center_stack | 805 | presentation/co4e/co4e_tab.py | TRẠNG THÁI CHIA SẺ — chuyển đổi giữa trang Runs (co4e_run_control_widget) và trang flow editor; dùng bởi _show_runs (ngoài phạm vi đọc) và _apply_workflow. | chua/khong ro | - |
+| Co4ETab.name_edit | 814 | presentation/co4e/co4e_tab.py | khởi tạo từ self._wf.name — trạng thái chia sẻ; cũng bị _on_name_changed/_new_workflow đọc/ghi. | chua/khong ro | - |
+| Co4ETab.add_step_btn | 819 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.save_btn | 822 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.save_tpl_btn | 826 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._vsplit | 863 | presentation/co4e/co4e_tab.py | splitter dọc canvas/chat — dùng chung với _toggle_messages (co4e_chat_view.py thao tác self._vsplit.setSizes) — trạng thái chia sẻ giữa co4e_tab.py và co4e_chat_view.py. | chua/khong ro | - |
+| Co4ETab._NARROW | 971 | presentation/co4e/co4e_tab.py | hằng class-level (không phải self.), ngưỡng chiều rộng dùng bởi _apply_narrow_layout. | chua/khong ro | - |
+| Co4ETab.showEvent | 973-975 | presentation/co4e/co4e_tab.py | Qt override, gọi self._narrow_guard.attach() (đối tượng khởi tạo ngoài phạm vi đọc, <701). [ANOMALY: cùng tên method định nghĩa 2 lần ở 2 dòng khác nhau trong cùng class -- có khả năng là lỗi nguồn (định nghĩa sau đè định nghĩa trước), không phải do quét trùng; giữ 2 dòng riêng, cần người quyết định định nghĩa nào còn hiệu lực] | chua/khong ro | ợng khởi tạo ngoài phạm vi đọc, <701). [ANOMALY: cùng tên method định nghĩa 2 lần ở 2 dòng khác nhau trong cùng class -- có khả |
+| Co4ETab._apply_narrow_layout | 977-987 | presentation/co4e/co4e_tab.py | so self._config_collapsed rồi gọi self._toggle_config() — trạng thái chia sẻ với node_property_panel wrap logic. | chua/khong ro | - |
+| Co4ETab._toggle_config | 989-1032 | presentation/co4e/co4e_tab.py | dài 44 dòng, gộp: ẩn/hiện self.config (widget thuộc node_property_panel.py), đổi icon, tính lại self._split.setSizes, gọi _refresh_min_width — thao tác trực tiếp self.config/self.config_container (node_property_panel.py) và self._split (co4e_tab.py) cùng lúc — ranh giới tách file dễ vỡ nhất ở đoạn này. Ghi self._config_expanded_w. | chua/khong ro | - |
+| Co4ETab._refresh_min_width | 1034-1039 | presentation/co4e/co4e_tab.py | thao tác trực tiếp self._split (QSplitter) và self.config_container — chia sẻ với _build_center/_wrap_config. | chua/khong ro | - |
+| Co4ETab._apply_workflow | 1194-1207 | presentation/co4e/co4e_tab.py | hàm điều phối trung tâm khi mở 1 flow: gán self._wf (TRẠNG THÁI CHIA SẺ dùng khắp mọi nhóm chức năng — canvas, chat_stack/_flow_logs, config panel, run button, usage total). Đây là điểm nối chính giữa các file sau khi tách — không nên tách nhỏ hơn nếu không rất cẩn thận. | chua/khong ro | - |
+| Co4ETab._new_workflow | 1209-1217 | presentation/co4e/co4e_tab.py | gọi self._open_flow(...) — khớp dòng plan.md '_open_flow() -> co4e_tab.py → gọi canvas'. | co | - |
+| Co4ETab._selected_wf | 1219-1225 | presentation/co4e/co4e_tab.py | đọc self.wf_list (sidebar, dựng ở _build_sidebar <701) rồi gọi co4e.get_workflow (đĩa). | chua/khong ro | - |
+| Co4ETab._load_selected_workflow | 1227-1230 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._edit_selected_workflow | 1232-1237 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._wf_context_menu | 1248-1271 | presentation/co4e/co4e_tab.py | dựng QMenu cho sidebar flows, điều phối gọi _edit_selected_workflow/_rename_workflow/_duplicate_selected_workflow/_run_selected_in_background/_delete_selected_workflow (một số nằm ngoài phạm vi đọc, dòng >1400). | chua/khong ro | - |
+| Co4ETab._sync_wf_from_canvas | 1299-1302 | presentation/co4e/co4e_tab.py | đọc self.canvas.nodes()/edges() và ghi self._wf.nodes/edges/name — cầu nối giữa co4e_canvas_widget.py và trạng thái self._wf chia sẻ; cân nhắc đặt cùng canvas nếu muốn canvas tự chịu trách nhiệm export dữ liệu. | chua/khong ro | - |
+| Co4ETab._on_name_changed | 1316-1318 | presentation/co4e/co4e_tab.py | ghi self._wf.name (trạng thái chia sẻ) rồi gọi self._sync_active_flow_tab_text() (định nghĩa dòng 444, ngoài phạm vi đọc). | chua/khong ro | - |
+| Co4ETab._add_blank_step | 1320-1322 | presentation/co4e/co4e_tab.py | nút 'Add' trên toolbar uỷ nhiệm sang self.canvas.add_palette_step — liên quan nhóm _add_node() trong plan.md (co4e_canvas_widget.py) nhưng bản thân handler chỉ là cầu nối từ toolbar. | co | - |
+| Co4ETab.set_project | 1658-1674 | presentation/co4e/co4e_tab.py | gọi load_project(project_id) (đọc đĩa) và self.manager.set_output_root/set_current_project (self.manager nên là co4e_workflow_service). Gán self._project_id, self._project_dir — không chắc là lần gán đầu tiên (có thể đã init ở __init__ ngoài khoảng đọc). Không khớp rõ nhóm nào trong danh sách đích cho trước — xếp tạm vào co4e_tab.py vì đây là API binding cấp container gọi từ ngoài. | chua/khong ro | ể đã init ở __init__ ngoài khoảng đọc). Không khớp rõ nhóm nào trong danh sách đích cho trước — xếp tạm vào co4e_tab.py vì đây là |
+| Co4ETab._flow_output_root | 1676-1686 | presentation/co4e/co4e_tab.py | helper dùng chung bởi cả chat (_out_dir) và run-control (_open_workspace_folder, _open_run_output_folder) — trạng thái/logic cắt ngang nhiều nhóm; đọc self._project_dir, self.ctx.config | chua/khong ro | - |
+| Co4ETab._refresh_ws_folder_btn | 1688-1693 | presentation/co4e/co4e_tab.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._open_workspace_folder | 1695-1702 | presentation/co4e/co4e_tab.py | root.mkdir + open_location (mở file explorer hệ điều hành — spawn process) | chua/khong ro | - |
+| Co4ETab.showEvent | 1806-1809 | presentation/co4e/co4e_tab.py | override Qt lifecycle method của chính QWidget container nên phải ở lại co4e_tab.py; gọi self._refresh_runs() (thuộc co4e_run_control_widget.py) — điểm nối giữa container và run-control widget. [ANOMALY: cùng tên method định nghĩa 2 lần ở 2 dòng khác nhau trong cùng class -- có khả năng là lỗi nguồn (định nghĩa sau đè định nghĩa trước), không phải do quét trùng; giữ 2 dòng riêng, cần người quyết định định nghĩa nào còn hiệu lực] | chua/khong ro | giữa container và run-control widget. [ANOMALY: cùng tên method định nghĩa 2 lần ở 2 dòng khác nhau trong cùng class -- có khả |
+| Co4ETab._out_dir | 1811-1817 | presentation/co4e/co4e_tab.py | d.mkdir(parents=True, exist_ok=True) — ghi đĩa; dùng chung bởi _run_chat_turn (chat) và tiềm năng bởi run-control; đọc self._wf.name, self._flow_output_root() | chua/khong ro | - |
+| Co4ETab._retranslate | 2059-2079 | presentation/co4e/co4e_tab.py | cập nhật text i18n cho rất nhiều widget thuộc nhiều nhóm khác nhau (sidebar buttons, runs_table, run control buttons) và gọi self._reload_sidebar()/self._refresh_runs() — thuộc container vì bao trùm toàn tab, dù có thể tách nhỏ theo từng panel sau này. | chua/khong ro | - |
+| _SectionHeader | 30-52 | presentation/co4e/node_property_panel.py | Widget nội bộ (header có thể click, thu/mở section) chỉ dùng bởi StepConfigPanel; không có trong bảng plan.md/function_list.md, xếp cùng chỗ với StepConfigPanel vì mô tả node_property_panel.py là 'Bọc StepConfigPanel' | co | section) chỉ dùng bởi StepConfigPanel; không có trong bảng plan.md/function_list.md, xếp cùng chỗ với StepConfigPanel vì mô tả node_property_panel |
+| _SectionHeader.clicked | 36 | presentation/co4e/node_property_panel.py | Signal Qt khai báo ở cấp class, không phải self.<tên> gán trong __init__ | chua/khong ro | - |
+| _SectionHeader.mousePressEvent | 38-41 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| _SectionHeader.showEvent | 43-52 | presentation/co4e/node_property_panel.py | recompute fontMetrics khi label thực sự hiển thị — cần widget đang sống, không test được nếu không có QApplication | chua/khong ro | - |
+| _add_section | 55-130 | presentation/co4e/node_property_panel.py | Hàm dựng UI khối section thu gọn/mở rộng (header + body animate) dùng riêng cho StepConfigPanel; chứa 2 closure nội bộ _on_finished và _toggle. Không có trong bảng cũ. | co | closure nội bộ _on_finished và _toggle. Không có trong bảng cũ. |
+| _add_section._on_finished | 103-112 | presentation/co4e/node_property_panel.py | closure lồng bên trong _add_section, không phải hàm top-level — chỉ tồn tại khi _add_section chạy | chua/khong ro | - |
+| _add_section._toggle | 114-127 | presentation/co4e/node_property_panel.py | closure lồng bên trong _add_section, gắn vào header.clicked | chua/khong ro | - |
+| StepConfigPanel | 133-528 | presentation/co4e/node_property_panel.py | cắt ngang lát — cần agent gộp đối chiếu (lớp còn tiếp tục sau dòng 528, chỉ đọc được 1-528). Bảng plan.md/function_list.md không liệt kê StepConfigPanel trực tiếp (chỉ có _build_config_panel() -> co4e_tab.py container); xếp theo mô tả node_property_panel.py 'Bọc StepConfigPanel, nối chọn node sang panel thuộc tính' trong danh sách đích được giao cho task này — người quyết cuối nên xác nhận lại. | co | - |
+| StepConfigPanel.changed | 134 | presentation/co4e/node_property_panel.py | Signal Qt: bất kỳ field nào đổi -> canvas repaint node + autosave; đây là điểm nối trạng thái chia sẻ với canvas/co4e_workflow_service, cần giữ tên/signature khi tách file | chua/khong ro | - |
+| StepConfigPanel.run_node | 135 | presentation/co4e/node_property_panel.py | Signal Qt 'chạy step này' — nối sang co4e_run_control_widget.py hoặc co4e_workflow_service.py | chua/khong ro | - |
+| StepConfigPanel.run_from | 136 | presentation/co4e/node_property_panel.py | Signal Qt 'chạy từ bước này' — nối sang co4e_run_control_widget.py | chua/khong ro | - |
+| StepConfigPanel.delete_node | 137 | presentation/co4e/node_property_panel.py | Signal Qt xoá step — nối sang co4e_canvas_widget.py để xoá node trên canvas | chua/khong ro | - |
+| StepConfigPanel.__init__ | 139-313 | presentation/co4e/node_property_panel.py | >80 dòng (174 dòng) — gộp nhiều việc không liên quan: dựng section Cơ bản, section Model&Quyền, section Skills&Tệp, section Sub-agents (ẩn/hiện theo is_parallel), và dựng hàng nút footer Run/Run-from/Delete, cộng thêm cơ chế 'outer.addStretch(1)' vá lỗi layout. Nên tách thành các hàm _build_basic_section(), _build_model_section(), _build_skills_section(), _build_subagent_section(), _build_footer() riêng khi tách file. | chua/khong ro | - |
+| StepConfigPanel.ctx | 141 | presentation/co4e/node_property_panel.py | context được truyền từ ngoài vào, dùng cho _ai_draft/_load_models (gọi AI provider) — trạng thái chia sẻ với co4e_tab.py | chua/khong ro | - |
+| StepConfigPanel._step | 142 | presentation/co4e/node_property_panel.py | Step đang chỉnh sửa — trạng thái chia sẻ giữa load_step()/_on_edit()/mọi hành động subagent+attachment; do canvas gán vào qua load_step() | chua/khong ro | - |
+| StepConfigPanel._node_id | 143 | presentation/co4e/node_property_panel.py | id node đang chọn — dùng để emit run_node/run_from/delete_node; là cầu nối canvas <-> property panel | chua/khong ro | - |
+| StepConfigPanel._loading | 144 | presentation/co4e/node_property_panel.py | cờ chặn _on_edit() chạy lại trong lúc load_step() đang set giá trị field | chua/khong ro | - |
+| StepConfigPanel.label_edit | 159 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.role_edit | 163 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.icon_edit | 170 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.instructions_edit | 175 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.gen_btn | 178 | presentation/co4e/node_property_panel.py | nút 'AI draft' — enable chỉ khi có ctx | chua/khong ro | - |
+| StepConfigPanel.context_edit | 192 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.model_combo | 201 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.load_models_btn | 204 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.perm_combo | 214 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.verify_chk | 221 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.rounds_spin | 223 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.skills_list | 236 | presentation/co4e/node_property_panel.py | checklist skill của registry, gán checked theo step.skills | chua/khong ro | - |
+| StepConfigPanel.attach_list | 242 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.attach_add_btn | 244 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.attach_del_btn | 247 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel._parallel_card | 263 | presentation/co4e/node_property_panel.py | card cả section Sub-agents; load_step() ẩn/hiện toàn bộ card này theo step.is_parallel | chua/khong ro | - |
+| StepConfigPanel.sub_list | 264 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.sub_add_btn | 267 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.config | 268 | presentation/co4e/node_property_panel.py | StepConfigPanel + wiring changed/run_node/run_from/delete_node (dòng 268-273) — khớp vai trò mô tả cho node_property_panel.py | chua/khong ro | - |
+| StepConfigPanel.sub_del_btn | 270 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel.run_btn | 283 | presentation/co4e/node_property_panel.py | click emit run_node(self._node_id) | chua/khong ro | - |
+| StepConfigPanel.run_from_btn | 287 | presentation/co4e/node_property_panel.py | click emit run_from(self._node_id) | chua/khong ro | - |
+| StepConfigPanel.del_btn | 290 | presentation/co4e/node_property_panel.py | click emit delete_node(self._node_id) | chua/khong ro | - |
+| StepConfigPanel.load_step | 316-354 | presentation/co4e/node_property_panel.py | Điểm nối chính giữa canvas (khi chọn node) và panel thuộc tính — nhận (node_id, step, skill_names) từ ngoài rồi ghi self._step/self._node_id; đây là API mà co4e_canvas_widget.py hoặc co4e_tab.py sẽ gọi khi chọn node | chua/khong ro | - |
+| StepConfigPanel.clear_step | 356-359 | presentation/co4e/node_property_panel.py | gọi khi bỏ chọn node — reset self._step/self._node_id | chua/khong ro | - |
+| StepConfigPanel._on_edit | 362-378 | presentation/co4e/node_property_panel.py | ghi ngược giá trị field UI vào self._step rồi emit changed() — canvas repaint + autosave phụ thuộc signal này, đổi tên/behavior ở đây ảnh hưởng cả canvas lẫn service lưu flow | chua/khong ro | - |
+| StepConfigPanel._available_agent_names | 380-390 | presentation/co4e/node_property_panel.py | staticmethod; gọi core.co4e.list_custom_agents() đọc file JSON trong AGENTS_DIR trên đĩa — logic thuần Python nhưng có I/O, có thể tách ra application layer nếu cần test không đụng đĩa | chua/khong ro | - |
+| StepConfigPanel._add_subagent | 392-408 | presentation/co4e/node_property_panel.py | dùng QInputDialog để chọn/nhập tên agent song song | chua/khong ro | - |
+| StepConfigPanel._edit_subagent | 410-428 | presentation/co4e/node_property_panel.py | double-click 1 dòng sub-agent để chọn lại agent khác | chua/khong ro | - |
+| StepConfigPanel._del_subagent | 430-437 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel._add_attachment | 439-453 | presentation/co4e/node_property_panel.py | QFileDialog chỉ chọn đường dẫn hiển thị tên file, không tự đọc nội dung ở đây (nội dung được đọc lúc chạy step, ở nơi khác) | chua/khong ro | - |
+| StepConfigPanel._del_attachment | 455-462 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| StepConfigPanel._ai_draft | 464-498 | presentation/co4e/node_property_panel.py | gọi generate_agent_prompt(ctx.build_active_provider(), ...) qua AgentWorker — gọi network tới AI provider, chạy nền rồi cập nhật UI ở callback done(); nếu tách sang service, phần gọi AI nên chuyển xuống application layer, phần còn lại (QInputDialog + set text) ở lại đây | chua/khong ro | - |
+| StepConfigPanel._draft_worker | 497 | presentation/co4e/node_property_panel.py | giữ tham chiếu AgentWorker (QThread-like) để không bị GC giữa lúc job async đang chạy | chua/khong ro | - |
+| StepConfigPanel._load_models | 500-528 | presentation/co4e/node_property_panel.py | gọi preview_ai.fetch_live_models(ctx) qua AgentWorker — network call tới provider để lấy danh sách model; cắt ngang lát — cần agent gộp đối chiếu vì dòng cuối trùng đúng biên đọc được giao (528), chưa chắc thân method đã hết ở đây | chua/khong ro | - |
+| StepConfigPanel._model_worker | 525 | presentation/co4e/node_property_panel.py | giữ tham chiếu AgentWorker của _load_models để không bị GC | chua/khong ro | - |
+| Co4ETab._wrap_config | 934-964 | presentation/co4e/node_property_panel.py | bọc self.config (StepConfigPanel) với header expand/collapse — khớp mô tả node_property_panel.py trong prompt. | chua/khong ro | - |
+| Co4ETab.config_toggle_btn | 946 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.config_title | 951 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab._cfg_vlayout | 957 | presentation/co4e/node_property_panel.py | dùng lại trong _toggle_config (co4e_tab.py) — trạng thái chia sẻ. | chua/khong ro | - |
+| Co4ETab._cfg_top_spacer | 961 | presentation/co4e/node_property_panel.py | QSpacerItem — kiểu giá trị layout, không cần QApplication đang sống. | chua/khong ro | - |
+| Co4ETab._cfg_bot_spacer | 962 | presentation/co4e/node_property_panel.py | (không có ghi chú) | chua/khong ro | - |
+| Co4ETab.config_container | 963 | presentation/co4e/node_property_panel.py | dùng lại bởi _toggle_config (co4e_tab.py) — trạng thái chia sẻ giữa node_property_panel.py và co4e_tab.py. | chua/khong ro | - |
+| Co4ETab._on_node_selected | 1325-1331 | presentation/co4e/node_property_panel.py | khớp mô tả 'nối chọn node sang panel thuộc tính' trong prompt. Đọc self.canvas.nodes() và self.config, toggle self._config_collapsed (trạng thái chia sẻ với _toggle_config ở co4e_tab.py). | chua/khong ro | - |
+| Co4ETab._on_config_changed | 1333-1336 | presentation/co4e/node_property_panel.py | gọi self.canvas.refresh_node cho từng node rồi self._autosave() — cầu nối property panel ↔ canvas ↔ service lưu đĩa. | chua/khong ro | - |
+| Co4ETab._manage_skills | 1369-1373 | presentation/co4e/skills_list_panel.py | mở SkillsDialog rồi self._reload_sidebar() — không có tên tương ứng trực tiếp trong bảng plan.md, tự xếp theo mô tả skills_list_panel.py. | co | - |
+| _PaletteList | 97-119 | unsure | list kéo-thả dùng chung cho wf_list và agent_list, phát payload CO4E_MIME hiểu bởi canvas — không rõ nên đặt ở co4e_tab.py (nơi dùng) hay co4e_canvas_widget.py (định nghĩa giao thức CO4E_MIME) | chua/khong ro | - |
+| _PaletteList.__init__ | 102-106 | unsure | cùng lý do với class _PaletteList | chua/khong ro | - |
+| _PaletteList._payload_role | 104 | unsure | cùng lý do với class _PaletteList | chua/khong ro | - |
+| _PaletteList.startDrag | 108-119 | unsure | cùng lý do với class _PaletteList; dùng CO4E_MIME từ co4e_canvas | chua/khong ro | - |
+| Co4ETab._project_id | 249 | unsure | project Workspace đang chọn, ảnh hưởng đường dẫn output flow — không chắc thuộc container hay run control | chua/khong ro | - |
+| Co4ETab._project_dir | 250 | unsure | cùng lý do với _project_id | chua/khong ro | - |
+| Co4ETab._reflect_active_run | 449-457 | unsure | cầu nối giữa self.manager (run control) và self.canvas (canvas widget) — không chắc nên đặt file nào | chua/khong ro | - |
+| Co4ETab._palette_item | 724-728 | unsure | staticmethod helper dùng chung để tạo QListWidgetItem cho cả agent_list, skill_list, và cả node palette sequential/parallel (thấy dùng ở dòng 701-704) — không rõ nên đặt ở agent_list_panel.py, skills_list_panel.py hay co4e_canvas_widget.py. | chua/khong ro | - |
+
+## Chỗ thấy khác tài liệu — cần người quyết
+
+Không có symbol nào có note bắt đầu bằng `khac tai lieu:` trong dữ liệu 367 symbol đầu vào. Mục này để trống theo đúng dữ liệu quét được — không tự bịa thêm mục.

docs/architecture/dormant-code.md

@@ -0,0 +1,39 @@
+# Danh Mục & Kế Hoạch Cô Lập Mã Nguồn Dormant / Dead Code (Dormant Code Catalog)
+
+* **Tài liệu**: `docs/architecture/dormant-code.md`
+* **Thuộc EPIC**: `R01: Architecture Foundation & Characterization`
+* **Team phụ trách**: 🔵 **Team Duy (Tech Lead)**
+
+---
+
+## 1. Mục Đích & Nguyên Tắc Quản Trị
+
+Trong quá trình phát triển nhanh, một số module, hàm hoặc script đã trở thành mã nguồn không hoạt động (**dormant**), mã nguồn thử nghiệm cũ (**legacy prototypes**), hoặc mã nguồn không còn được sử dụng (**dead code**).
+
+> [!IMPORTANT]
+> ### 🛡️ NGUYÊN TẮC CÔ LẬP MÃ NGUỒN CŨ:
+> 1. **Tuyệt đối không import vào các tầng mới**: Các tầng `domain/`, `application/`, `infrastructure/` mới được xây dựng **cấm tuyệt đối import bất kỳ module dormant nào**.
+> 2. **Không xóa vội vàng khi chưa có test bảo vệ**: Giữ nguyên mã nguồn cũ trong giai đoạn tái cấu trúc R01–R08; chỉ dọn dẹp hoặc xóa sau khi bộ kiểm thử khói E2E (EPIC R10) chạy pass 100%.
+> 3. **Phân loại rõ ràng trạng thái**: Mỗi module dormant phải được gắn nhãn (DEPRECATED / ISOLATED / PENDING_DELETION).
+
+---
+
+## 2. Bảng Danh Mục Mã Nguồn Dormant / Dead Code Đã Rà Soát
+
+| STT | File / Module / Ký Hiệu | Trạng Thái Hiện Tại | Lý Do Phân Loại & Phân Tích Kỹ Thuật | Kế Hoạch Xử Lý & Thời Điểm Gỡ Bỏ |
+| :---: | :--- | :---: | :--- | :--- |
+| **1** | `requirements (cloud copy).txt` | `PENDING_DELETION` | File sao chép dự phòng tạm thời trong quá khứ, không được tham chiếu bởi bất kỳ quy trình setup nào. | Gỡ bỏ trong EPIC R10 (Packaging & Clean-up). |
+| **2** | `preview-desktop` | `ISOLATED` | Script shell rỗng/phác thảo cho môi trường dev container cũ. | Cô lập, không liên kết vào build workflow. |
+| **3** | `scripts/bootstrap_gitea_repo.py` | `ISOLATED` | Script tiện ích bootstrap kho lưu trữ Gitea nội bộ; không thuộc runtime ứng dụng chính. | Di chuyển vào `docs/gitea/` làm tài liệu tham khảo ops. |
+| **4** | Hàm routing sao chép tại `ui/chat_panel.py#L638` | `DEPRECATED` | Đoạn code logic chọn model lặp lại từ `core/routing/` nằm trực tiếp trong UI widget. | Thay thế hoàn toàn bằng `RoutingApplicationService` trong EPIC R03. |
+| **5** | Biến toàn cục `state.py::active_project_id` | `DEPRECATED` | Biến global mutable gây race condition khi chạy background task song song. | Thay thế bằng `WorkspaceSession` trong EPIC R06. |
+| **6** | Các hàm xử lý UI đồng bộ trong `core/tools.py` | `DEPRECATED` | `core/tools.py` chứa mã monolithic vừa xử lý file vừa gọi dialog xác thực trực tiếp. | Phân rã thành `file_tools.py`, `command_tools.py` và `ToolPolicyGateway` trong EPIC R05. |
+
+---
+
+## 3. Quy Trình Cô Lập & Kiểm Soát
+
+1. **Kiểm tra tự động qua AST Guard**:
+   - Bộ script `scripts/check_imports.py` tự động quét để đảm bảo không có bất kỳ import mới nào trỏ tới các thành phần đã đánh dấu deprecated.
+2. **Kế hoạch dọn dẹp cuối cùng (Release Phase - 31/08/2026)**:
+   - Sau khi hoàn thành EPIC R10 và pass toàn bộ bài test E2E (`tests/e2e/test_smoke.py`), các file đánh dấu `PENDING_DELETION` sẽ được gỡ bỏ khỏi nhánh `main`.

docs/architecture/security-policy.md

@@ -0,0 +1,159 @@
+# Mô hình chính sách an toàn — CoworkLocal
+
+R09-T01 · Team Gamma · viết 22/08/2026
+
+Tài liệu này mô tả **hệ thống đang chạy**, không phải hệ thống mong muốn. Mọi
+khẳng định đều chỉ tới file và dòng cụ thể để đối chiếu được.
+
+---
+
+## 1. Câu hỏi quan trọng nhất: đây có phải rào chắn an ninh không
+
+**Không.** `core/agent_security.py` nói thẳng ngay ở đầu file:
+
+> *"this is a business productivity tool, not a hard security boundary"*
+
+Điều đó quyết định mọi thứ còn lại. Cụ thể: **mọi tầng dùng AI đều mở khi
+hỏng** (`allowed=True` khi không gọi được validator, `core/agent_security.py:150`).
+Mạng chập chờn hay gateway trục trặc thì agent vẫn chạy, không bị khoá cứng.
+
+Đánh đổi có chủ đích: chọn *dùng được* thay vì *chặn tuyệt đối*. Ai đọc tài
+liệu này để đánh giá rủi ro cần hiểu đúng điều đó — đây là lớp giảm tai nạn,
+không phải lớp chống kẻ tấn công có chủ đích.
+
+---
+
+## 2. Hai loại quy tắc, đừng lẫn
+
+| | Quy tắc xác định | Quy tắc do AI phán |
+|---|---|---|
+| Cách hoạt động | So khớp mẫu cố định | Hỏi một model |
+| Kết quả | Luôn giống nhau | Có thể khác nhau giữa hai lần |
+| Khi hỏng | Vẫn chạy | **Mở** (cho qua) |
+| Tắt được không | Không — luôn bật | Có, từng tầng một |
+| Ở đâu | Bộ phân loại mẫu chặn + sandbox | 3 tầng validate |
+
+Câu ở `core/agent_security.py:250` nói rõ ranh giới:
+
+> *"always-on block-pattern classifier + sandbox still apply regardless"*
+
+Nghĩa là **tắt hết ba tầng AI thì vẫn còn hai lớp xác định**. Đây là điểm dễ
+hiểu nhầm nhất khi đọc màn Cài đặt: mấy công tắc ở đó **chỉ tắt phần AI**.
+
+---
+
+## 3. Ba tầng AI
+
+Bật/tắt độc lập trong `agent_security` của `config.json`.
+
+| Tầng | Kiểm cái gì | Khoá cấu hình | Khi nào chạy |
+|---|---|---|---|
+| Prompt | Yêu cầu của chính người dùng | `validate_prompt` | Trước khi agent làm gì |
+| Attachment | Văn bản trích ra từ tệp đính kèm | `validate_attachments` | Trước khi vào ngữ cảnh model |
+| Command | `run_command` / `install_package` | `validate_commands` | Trước khi thực thi |
+
+Cả ba đọc chung một bộ luật: file cục bộ `core/security_rules.py` cộng thêm
+tài liệu quản trị viên đặt trên OneDrive (nếu có cấu hình). Riêng agent Code
+dùng bộ luật khác — `RULEforCode.md` thay vì `RULEBASE.md`.
+
+Công tắc tổng `agent_security.enabled` tắt cả ba.
+
+---
+
+## 4. Chuyện gì xảy ra khi bị chặn
+
+Theo đúng thứ tự trong `core/agent_security.py:266-273`:
+
+1. Hiện thông báo trong khung chat — người dùng thấy ngay, kèm lý do
+2. Ghi `audit_log.record("security_block", …)` — vào nhật ký kiểm toán
+3. `notify_admin(...)` — gửi email quản trị viên
+4. Ném `SecurityBlocked` — dừng lượt chạy
+
+Ba bước đầu **không được phép ném lỗi**. `audit_log.record()` có ghi rõ trong
+docstring: *"never raises — audit logging must never break a chat turn"*. Ghi
+nhật ký hỏng không được kéo theo cả phiên làm việc.
+
+---
+
+## 5. Hỏi người dùng: trạng thái thứ ba
+
+Ngoài cho/chặn còn một trạng thái nữa mà hệ thống hiện tại **có nhưng chưa gọi
+tên**: hỏi người dùng.
+
+`ui/chat_panel.py:1312` kiểm `ctx.project_confirm_commands()` rồi bật
+`PermissionDialog`. Đó là một quyết định chính sách thật, nhưng nằm rải ở tầng
+giao diện chứ không phải một kết quả chính thức.
+
+`domain/security/tool_policy.py` (đề xuất, chờ Team Hoa xác nhận) gộp lại
+thành ba trạng thái:
+
+| | Nghĩa |
+|---|---|
+| `ALLOW` | Chạy |
+| `DENY` | Không chạy, có lý do |
+| `ASK` | Hỏi người dùng đã |
+
+**`ASK` không phải là `allowed`.** Coi ASK như ALLOW nghĩa là tool chạy trước
+khi có ai đồng ý — bẫy dễ mắc nhất, đã có test riêng chặn.
+
+Cổng chính sách **không tự bật hộp thoại**. Nó chỉ trả lời; hỏi ai và hỏi thế
+nào là việc của tầng giao diện. Nhờ vậy Co4E chạy nền mới dùng chung cổng được
+với Cowork chạy tương tác — Co4E không hỏi được thì đổi `ASK` thành `DENY`.
+
+---
+
+## 6. Bí mật
+
+Từ 21/08 (R02-T05), API key **không còn nằm trong `config.json`**:
+
+* Lưu trong kho của hệ điều hành qua `KeyringAdapter` — Windows Credential
+  Manager, macOS Keychain, Linux Secret Service
+* `provider_conf()` đọc từ kho rồi ghép vào dict trả về, nên chỗ gọi không
+  đổi (đường A, `GammaTeam_decisions.md`)
+* File cũ tự chuyển ở lần mở đầu tiên, có sao lưu trước khi chuyển
+
+Máy không có kho bí mật (Linux headless, CI) thì **không chuyển** — thà để
+khoá trong file còn hơn xoá đi rồi người dùng mất khoá.
+
+Kiểm bằng `python scripts/audit_security.py`, chạy tự động trong CI.
+
+---
+
+## 7. Sandbox
+
+`core/sandbox_manager.py` chạy lệnh trong môi trường hạn chế. Luôn bật, không
+tắt được, không phụ thuộc công tắc AI nào.
+
+Năng lực khác nhau theo hệ điều hành — ma trận đầy đủ sẽ nằm ở
+`infrastructure/sandbox/sandbox_capabilities.py` (R09-T06, Hiệp phụ trách).
+Chỗ này cập nhật khi task đó xong.
+
+---
+
+## 8. Những chỗ đã biết là yếu
+
+Ghi ra để người sau khỏi tưởng đã kín:
+
+1. **Mở khi hỏng.** Gateway chết là ba tầng AI cho qua hết. Có chủ đích, nhưng
+   nghĩa là không chống được kẻ tấn công biết cách làm validator ngừng trả lời.
+2. **Bí mật vẫn đi trong bộ nhớ.** Đường A ghép khoá vào dict `provider_conf()`
+   trả về, nên khoá vẫn có thể lọt vào log gỡ lỗi hay ảnh chụp màn hình. Đường
+   B (bỏ hẳn khỏi dict) đã ghi vào nợ kỹ thuật.
+3. **Bộ luật lấy từ OneDrive không ký số.** Ai sửa được tài liệu đó là sửa được
+   luật.
+4. **`ASK` chưa được nối vào Co4E.** Co4E chạy nền, chưa có đường hỏi người
+   dùng — hiện phải chọn giữa cho qua hết hoặc chặn hết.
+
+---
+
+## Đối chiếu nhanh
+
+| Nội dung | Nguồn |
+|---|---|
+| Ba tầng AI, mở khi hỏng | `core/agent_security.py:1-25` |
+| Phân loại mẫu + sandbox luôn bật | `core/agent_security.py:250` |
+| Thứ tự khi bị chặn | `core/agent_security.py:266-273` |
+| Nhật ký không được ném lỗi | `core/audit_log.py:46` |
+| Hỏi người dùng | `ui/chat_panel.py:1312` |
+| Ba trạng thái chính sách | `domain/security/tool_policy.py` |
+| Bí mật | `infrastructure/secrets/keyring_adapter.py` |

docs/function_list.md

@@ -0,0 +1,473 @@
+# 📋 COWORK-LOCAL BamBOO — Danh Sách Chức Năng Chi Tiết Theo Navigation Bar
+
+---
+
+## 🔹 1. 📊 DASHBOARD (Bảng Điều Khiển)
+
+### 1.1 Token Usage & Cost — Thống Kê Token & Chi Phí
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 1.1.1 | `_refresh_cards()` | Làm mới các thẻ thống kê (Total, Input, Output, Cache tokens + Cost) |
+| 1.1.2 | `_refresh_chart()` | Vẽ biểu đồ spline theo chu kỳ (week/month/year) và metric (cost/tokens) |
+| 1.1.3 | `_chart_prev()` / `_chart_next()` | Chuyển đến chu kỳ trước/sau trên biểu đồ |
+| 1.1.4 | `_on_gran_changed()` | Thay đổi đơn vị thời gian (week/month/year) |
+| 1.1.5 | `_refresh_budget()` | Cập nhật ngân sách (budget card — còn lại / đã dùng / cảnh báo >85%) |
+| 1.1.6 | `_apply_budget()` | Lưu giá trị budget mới |
+| 1.1.7 | `_refresh_habits()` | Hiển thị thói quen sử dụng (task tốn nhiều token nhất, trung bình/prompt, ngày/giờ bận nhất) |
+| 1.1.8 | `_ai_analyze()` | ✨ AI phân tích thói quen dùng token và gợi ý tiết kiệm |
+| 1.1.9 | `_apply_saving_strategy()` | Áp dụng chiến lược tiết kiệm AI (tự nén context, nén sớm hơn) |
+| 1.1.10 | Currency Picker | Chọn đơn vị tiền tệ hiển thị (USD, VND, JPY, …) |
+
+---
+
+## 🔹 2. 📅 SCHEDULE TASK (Lên Lịch Nhiệm Vụ)
+
+### 2.1 Kanban Board
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 2.1.1 | `_build_kanban()` | Xây dựng board Kanban với 7 cột: Backlog, Scheduled, Running, Waiting Input, Done, Failed, Paused |
+| 2.1.2 | `_render_kanban()` | Render các thẻ task vào từng cột |
+| 2.1.3 | `_on_task_dropped(task_id, new_status)` | Kéo thả task giữa các cột (thay đổi status) |
+| 2.1.4 | `_on_card_double_click()` | Mở Task Editor khi double-click |
+| 2.1.5 | `_on_card_right_click()` | Menu ngữ cảnh: Run now, Edit, Duplicate, Pause, Delete, View logs, Create-next-from-output |
+| 2.1.6 | `_bulk_delete_menu()` | Xóa hàng loạt (chọn nhiều thẻ → right-click → Delete N selected) |
+| 2.1.7 | `_run_now(task_id)` | Chạy task ngay lập tức |
+| 2.1.8 | `_duplicate_task(task_id)` | Sao chép task |
+| 2.1.9 | `_pause_task(task_id)` | Tạm dừng task |
+| 2.1.10 | `_delete_task(task_id)` | Xóa task |
+| 2.1.11 | `_view_logs(task_id)` | Xem log của task |
+| 2.1.12 | `_search_tasks()` | Tìm kiếm task theo tên |
+| 2.1.13 | `_filter_by_type()` | Lọc task theo loại (cowork/co4e/code/…) |
+
+### 2.2 Calendar View
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 2.2.1 | `_build_calendar()` | Xây dựng chế độ xem lịch |
+| 2.2.2 | `_shift(direction)` | Chuyển tháng/tuần trước/sau |
+| 2.2.3 | `add_task_on_date(date)` | Thêm task vào ngày cụ thể |
+| 2.2.4 | `edit_task(task_id)` | Sửa task từ lịch |
+
+### 2.3 Add / AI Create Task
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 2.3.1 | `_open_add_dialog()` | Mở dialog thêm task thủ công |
+| 2.3.2 | `_ai_create_task()` | Mở dialog AI tạo task tự động |
+| 2.3.3 | `_ai_pick_files()` | Chọn file đính kèm cho AI planner |
+| 2.3.4 | `_generate()` | AI tạo kế hoạch tasks từ mô tả |
+| 2.3.5 | `_on_planned(result)` | Hiển thị preview các task AI đề xuất |
+| 2.3.6 | `_confirm()` | Xác nhận và tạo các task từ AI plan |
+
+### 2.4 AI Import Tasks
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 2.4.1 | `_ai_import()` | AI nhập task từ file/link |
+| 2.4.2 | `_ai_pick_import_files()` | Chọn file để import |
+| 2.4.3 | `_generate_import()` | AI phân tích file và tạo tasks |
+| 2.4.4 | `_on_import_planned()` | Hiển thị preview import |
+
+---
+
+## 🔹 3. 🏠 WORKSPACE (Không Gian Làm Việc)
+
+### 3.1 Projects — Quản Lý Dự Án (Tab 0)
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.1.1 | `_create()` | Tạo dự án mới |
+| 3.1.2 | `_delete()` | Xóa dự án (có xác nhận) |
+| 3.1.3 | `_save()` | Lưu thông tin dự án (name, description, instructions, folder) |
+| 3.1.4 | `_pick_folder()` | Chọn workspace folder cho dự án |
+| 3.1.5 | `_open_workspace()` | Mở folder workspace trong file explorer |
+| 3.1.6 | `_select_project_row(project_id)` | Chọn dự án trong danh sách |
+| 3.1.7 | `_refresh_sandbox_toggle()` | Bật/tắt sandbox cho dự án |
+| 3.1.8 | `refresh()` | Làm mới danh sách dự án |
+
+### 3.2 Workspace Pane — Mỗi Dự Án Mở (Tab 1..N)
+
+#### 3.2.1 🤖 COWORK — Chat Với AI Agent
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.1.1 | `new_session()` | Tạo phiên chat mới |
+| 3.2.1.2 | `send_message()` | Gửi tin nhắn đến AI agent |
+| 3.2.1.3 | `_build_job()` | Xây dựng job cho AgentWorker (gọi `run_cowork`) |
+| 3.2.1.4 | `_cleanup_turn(ctx, ok)` | Dọn dẹp sau khi turn kết thúc (promote files, xóa sandbox) |
+| 3.2.1.5 | `_promote_turn_outputs()` | Di chuyển file đầu ra từ sandbox lên session output |
+| 3.2.1.6 | `_refresh_outputs_from_disk()` | Làm mới danh sách output files |
+| 3.2.1.7 | `_pick_output_folder()` | Chọn thư mục output |
+| 3.2.1.8 | `_open_skills_manager()` | Mở Skill Manager |
+| 3.2.1.9 | `refresh_header()` | Làm mới header (project name, model info) |
+| 3.2.1.10 | `refresh_agents()` | Làm mới danh sách agents trong combo |
+| 3.2.1.11 | `admin_agent_prompt()` | Lấy prompt từ agent preset đã chọn |
+| 3.2.1.12 | `build_provider()` | Xây dựng provider từ cấu hình agent/model |
+| 3.2.1.13 | `workspace_dir()` | Trả về workspace directory hiện tại |
+| 3.2.1.14 | `_start_watching(dir)` | Giám sát folder output (file watcher) |
+| 3.2.1.15 | `_on_file_changed()` | Xử lý khi file output thay đổi |
+
+**ChatPanel (Class cha của CoworkTab):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.1.16 | `_submit_message()` | Gửi tin nhắn (kiểm tra queue, parallel limit) |
+| 3.2.1.17 | `_on_turn_started()` | Khi turn bắt đầu (show thinking indicator) |
+| 3.2.1.18 | `_on_turn_finished()` | Khi turn kết thúc (update UI, queue next) |
+| 3.2.1.19 | `_on_event(ev)` | Xử lý streaming events (text delta, tool calls, plan) |
+| 3.2.1.20 | `_compress_messages()` | Nén tin nhắn cũ để giảm token |
+| 3.2.1.21 | `_on_agent_changed()` | Khi thay đổi agent trong combo |
+| 3.2.1.22 | `_apply_routing()` | Áp dụng model routing (Auto/Manual/Off) |
+| 3.2.1.23 | `_note_agent_switch()` | Ghi chú khi agent thay đổi giữa các turn |
+| 3.2.1.24 | `_ensure_conversation()` | Đảm bảo conversation tab tồn tại |
+| 3.2.1.25 | `load_conversation()` | Load hội thoại từ disk |
+| 3.2.1.26 | `running_session_ids()` | Trả về danh sách session đang chạy |
+| 3.2.1.27 | `active_workers()` | Trả về danh sách worker đang hoạt động |
+| 3.2.1.28 | `_save_conversation()` | Tự động lưu hội thoại |
+
+**Composer (Composer input box):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.1.29 | `send()` | Gửi tin nhắn |
+| 3.2.1.30 | `attach_files()` | Đính kèm file |
+| 3.2.1.31 | `attach_links()` | Đính kèm link URL |
+| 3.2.1.32 | `has_any_queue()` | Kiểm tra queue có tin nhắn chờ |
+| 3.2.1.33 | `_parse_directives()` | Phân tích directives inline (`/agent:name`, `/skill:name`) |
+| 3.2.1.34 | `_show_autocomplete()` | Hiển thị gợi ý tự động |
+
+#### 3.2.2 ⚡ CO4E — Node-Graph Workflow Studio
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.1 | `_build_sidebar()` | Xây dựng sidebar (Workflows / Agents / Skills tabs) |
+| 3.2.2.2 | `_build_canvas()` | Xây dựng canvas node-graph |
+| 3.2.2.3 | `_build_config_panel()` | Xây dựng config panel bên phải |
+| 3.2.2.4 | `_toggle_config()` | Thu/mở config panel |
+| 3.2.2.5 | `_build_canvas_overlay()` | Zoom +/− và Fit buttons trên canvas |
+
+**Workflows (Sidebar):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.6 | `_refresh_flows_list()` | Làm mới danh sách flows |
+| 3.2.2.7 | `_create_flow()` | Tạo flow mới |
+| 3.2.2.8 | `_delete_flow()` | Xóa flow |
+| 3.2.2.9 | `_duplicate_flow()` | Sao chép flow |
+| 3.2.2.10 | `_import_flow()` | Import flow từ file |
+| 3.2.2.11 | `_export_flow()` | Export flow ra file |
+| 3.2.2.12 | `_run_flow()` | Chạy flow (foreground/background) |
+| 3.2.2.13 | `_stop_flow()` | Dừng flow đang chạy |
+| 3.2.2.14 | `_open_flow()` | Mở flow trên canvas |
+
+**Agents (Sidebar):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.15 | `_refresh_agents_list()` | Làm mới danh sách agents |
+| 3.2.2.16 | `_create_agent()` | Tạo agent mới (dialog) |
+| 3.2.2.17 | `_edit_agent()` | Sửa agent |
+| 3.2.2.18 | `_delete_agent()` | Xóa agent |
+| 3.2.2.19 | `_toggle_agent_enabled()` | Bật/tắt agent |
+
+**Skills (Sidebar):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.20 | `_refresh_skills_list()` | Làm mới danh sách skills |
+
+**Canvas (Node-Graph):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.21 | `zoom_in()` / `zoom_out()` | Zoom canvas |
+| 3.2.2.22 | `fit_view()` | Auto-fit canvas |
+| 3.2.2.23 | `_add_node()` | Thêm node lên canvas |
+| 3.2.2.24 | `_delete_node()` | Xóa node |
+| 3.2.2.25 | `_connect_nodes()` | Kết nối 2 nodes |
+| 3.2.2.26 | `_drag_node()` | Kéo thả node |
+| 3.2.2.27 | `_select_node()` | Chọn node (→ config panel) |
+| 3.2.2.28 | `_activate_node()` | Double-click node |
+
+**Run Modes:**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.29 | `_set_run_mode("auto")` | Auto mode: agent tự plan rồi execute |
+| 3.2.2.30 | `_set_run_mode("plan")` | Plan mode: chỉ tạo kế hoạch |
+| 3.2.2.31 | `_set_run_mode("manual")` | Manual mode: từng bước, bấm "Next step" |
+| 3.2.2.32 | `_run_step()` | Chạy bước tiếp theo (manual mode) |
+| 3.2.2.33 | `_on_step_finished()` | Xử lý khi bước hoàn thành |
+| 3.2.2.34 | `_render_plan()` | Render plan checklist |
+
+**Chat/Output (Bottom):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.2.35 | `_get_flow_chat(flow_id)` | Lấy ChatView cho flow (tạo mới nếu chưa có) |
+| 3.2.2.36 | `_on_chat_event()` | Xử lý event từ chat |
+
+#### 3.2.3 📁 FOLDER — File Explorer
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.3.1 | `set_root(path)` | Đặt thư mục gốc |
+| 3.2.3.2 | `_build_tree_view()` | Xây dựng cây thư mục (QFileSystemModel) |
+| 3.2.3.3 | `_open_file(path)` | Mở file được chọn |
+| 3.2.3.4 | `_view_source()` | Xem source code (syntax highlighting) |
+| 3.2.3.5 | `_view_html_preview()` | Preview HTML (WebEngine/rich text) |
+| 3.2.3.6 | `_view_office_doc()` | Xem Office doc (docx/pdf/xlsx/…) |
+| 3.2.3.7 | `_view_image()` | Hiển thị ảnh inline |
+| 3.2.3.8 | `_edit_file()` | Chỉnh sửa file (code editor) |
+| 3.2.3.9 | `_save_file()` | Lưu file |
+| 3.2.3.10 | `_preview_toggle()` | Chuyển đổi Preview ⇄ Edit |
+| 3.2.3.11 | `_create_new_file()` | Tạo file mới |
+| 3.2.3.12 | `_create_new_folder()` | Tạo folder mới |
+| 3.2.3.13 | `_rename_item()` | Đổi tên file/folder |
+| 3.2.3.14 | `_delete_item()` | Xóa file/folder |
+| 3.2.3.15 | `_copy_item()` | Sao chép file/folder |
+| 3.2.3.16 | `_paste_item()` | Dán file/folder |
+| 3.2.3.17 | `refresh_ai_models()` | Làm mới danh sách AI models cho AI Edit |
+
+**AI Edit (Chỉnh Sửa File Bằng AI):**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.3.18 | `_ai_send()` | Gửi yêu cầu AI edit |
+| 3.2.3.19 | `_ai_apply()` | Áp dụng thay đổi AI |
+| 3.2.3.20 | `_ai_discard()` | Hủy thay đổi AI |
+| 3.2.3.21 | `_reset_ai_conversation()` | Xóa hội thoại AI edit |
+| 3.2.3.22 | `_ai_apply_routing()` | Áp dụng routing cho AI edit |
+
+#### 3.2.4 🧠 GRAPH RAG — Knowledge Graph
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.4.1 | `_build_graph()` | Xây dựng knowledge graph từ code/documents |
+| 3.2.4.2 | `_render_d3_graph()` | Render graph bằng D3.js (WebEngine) |
+| 3.2.4.3 | `_render_native_graph()` | Render graph bằng QGraphicsView (fallback) |
+| 3.2.4.4 | `_auto_rotate()` | Tự xoay graph khi idle |
+| 3.2.4.5 | `_on_node_click()` | Xử lý click node (mở folder) |
+| 3.2.4.6 | `_open_node_path()` | Mở folder chứa node |
+| 3.2.4.7 | `_refresh_graph()` | Tự cập nhật graph khi có output mới |
+| 3.2.4.8 | `_search_graph()` | Tìm kiếm trong graph |
+| 3.2.4.9 | `_filter_by_kind()` | Lọc node theo loại |
+| 3.2.4.10 | `_zoom_graph()` | Zoom graph |
+
+**Graph-RAG Q&A:**
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 3.2.4.11 | `_ask_question()` | Hỏi AI về graph |
+| 3.2.4.12 | `_on_ask_event()` | Xử lý streaming answer |
+| 3.2.4.13 | `_on_ask_done()` | Khi AI trả lời xong |
+| 3.2.4.14 | `_candidate_file_paths()` | Lấy danh sách file để extract |
+| 3.2.4.15 | `_extract_tmp_dir()` | Tạo thư mục tạm cho extraction |
+| 3.2.4.16 | `_clear_extracts()` | Xóa dữ liệu extract tạm |
+
+---
+
+## 🔹 4. 📊 MONITORING (Giám Sát)
+
+### 4.1 Overview — Tổng Quan
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.1.1 | `_refresh_overview()` | Làm mới tất cả cards overview |
+| 4.1.2 | `_refresh_usage_cards()` | Token Usage & Cost cards (Total, Input, Output, Cache) |
+| 4.1.3 | `_refresh_resource_usage()` | Resource usage (CPU, RAM, Disk) |
+| 4.1.4 | `_refresh_recent_activity()` | Hoạt động gần đây |
+| 4.1.5 | `_refresh_sandbox_details()` | Chi tiết sandbox (PID, uptime, limits) |
+| 4.1.6 | `_refresh_permissions()` | Hiển thị permissions hiện tại |
+| 4.1.7 | `_refresh_audit_log()` | Audit log gần đây |
+| 4.1.8 | `_refresh_budget()` | Budget card (còn lại / đã dùng) |
+| 4.1.9 | `_apply_budget()` | Lưu budget mới |
+
+### 4.2 Security Events — Sự Kiện Bảo Mật
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.2.1 | `_refresh_security_events()` | Làm mới bảng security events (audit log `kind="security_block"`) |
+| 4.2.2 | `_filter_security_events()` | Lọc sự kiện bảo mật |
+| 4.2.3 | `_sort_events()` | Sắp xếp bảng events |
+
+### 4.3 MCP Call History — Lịch Sử Gọi MCP
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.3.1 | `_refresh_mcp_calls()` | Làm mới bảng MCP calls (audit log `kind="mcp_call"`) |
+| 4.3.2 | `_filter_mcp_calls()` | Lọc MCP calls |
+
+### 4.4 Action Logs — Nhật Ký Hành Động
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.4.1 | `_refresh_action_logs()` | Làm mới bảng action logs (toàn bộ audit log) |
+| 4.4.2 | `_filter_action_logs()` | Lọc action logs |
+| 4.4.3 | `_sort_action_logs()` | Sắp xếp action logs |
+
+### 4.5 Agent Status — Trạng Thái Agent
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.5.1 | `_refresh_agent_status()` | Làm mới trạng thái các agent (Cowork, Co4E, Schedule, GraphRAG) |
+
+### 4.6 Security Settings — Cài Đặt Bảo Mật
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 4.6.1 | `_toggle_sandbox()` | Bật/tắt sandbox |
+| 4.6.2 | `_toggle_network_block()` | Chặn kết nối mạng |
+| 4.6.3 | `_set_resource_limits()` | Đặt giới hạn tài nguyên (CPU/RAM/Disk) |
+| 4.6.4 | `_toggle_command_confirm()` | Xác nhận trước khi chạy lệnh |
+| 4.6.5 | `_manage_permissions()` | Quản lý quyền truy cập |
+
+---
+
+## 🔹 5. ⚙️ SETTINGS (Cài Đặt)
+
+### 5.1 AI Provider — Nhà Cung Cấp AI
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 5.1.1 | `_on_provider_changed()` | Khi thay đổi provider |
+| 5.1.2 | `_load_models(provider)` | Load danh sách models của provider |
+| 5.1.3 | `_test_connection(provider)` | Kiểm tra kết nối provider |
+| 5.1.4 | `_stash_provider_fields()` | Lưu tạm các trường cấu hình provider |
+| 5.1.5 | `_apply_provider_fields()` | Áp dụng các trường cấu hình provider |
+| 5.1.6 | Model List Widget | Hiển thị danh sách models (enable/disable, chọn default) |
+
+### 5.2 Connectors (MCP) — Kết Nối
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 5.2.1 | `_add_mcp_server()` | Thêm MCP server mới |
+| 5.2.2 | `_edit_mcp_server()` | Sửa MCP server |
+| 5.2.3 | `_delete_mcp_server()` | Xóa MCP server |
+| 5.2.4 | `_test_mcp_connection()` | Kiểm tra kết nối MCP |
+| 5.2.5 | MS365 Connector | Kết nối Microsoft 365 (tự động khi đăng nhập) |
+| 5.2.6 | CAD/CAE Connectors | Kết nối CAD/CAE tools |
+
+### 5.3 Parameters — Tham Số
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 5.3.1 | `attach_tokens` | Giới hạn token cho attachments |
+| 5.3.2 | `attach_files` | Giới hạn số file attachments |
+| 5.3.3 | `struct_nodes` | Giới hạn nodes cho GraphRAG |
+| 5.3.4 | `struct_edges` | Giới hạn edges cho GraphRAG |
+
+### 5.4 Model Routing — Định Tuyến Model
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 5.4.1 | `routing_mode` | Chế độ routing (Off/Auto/Manual) |
+| 5.4.2 | `routing_policy` | Chính sách routing |
+| 5.4.3 | `routing_min_gain` | Threshold tối thiểu để chuyển model |
+| 5.4.4 | `routing_timeout` | Timeout xác nhận routing |
+| 5.4.5 | `routing_interval` | Khoảng thời gian đánh giá lại |
+| 5.4.6 | `routing_concurrency` | Số lượng request đồng thời per provider |
+| 5.4.7 | `routing_judge` | Model dùng để đánh giá routing |
+
+### 5.5 General — Chung
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 5.5.1 | Language Picker | Chọn ngôn ngữ (EN/VI/JP) |
+| 5.5.2 | `tray_chk` | Minimize to tray thay vì đóng |
+| 5.5.3 | `notify_chk` | Thông báo khi task hoàn thành |
+| 5.5.4 | `_save()` | Lưu tất cả cài đặt |
+
+---
+
+## 🔹 6. 📜 HISTORY SIDEBAR (Thanh Lịch Sử Bên Trái)
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 6.0.1 | `refresh()` | Làm mới danh sách hội thoại |
+| 6.0.2 | `set_view_state(session_id, running_ids)` | Đánh dấu hội thoại hiện tại + đang chạy |
+| 6.0.3 | `set_project_filter(project_id)` | Lọc theo dự án |
+| 6.0.4 | `_open_chat()` | Mở hội thoại khi click |
+| 6.0.5 | `_context_menu()` | Menu chuột phải (Pin/Unpin, Rename, Delete) |
+| 6.0.6 | `_bulk_delete_menu()` | Menu xóa hàng loạt |
+| 6.0.7 | `_confirm_and_delete_selected()` | Xác nhận và xóa các hội thoại đã chọn |
+| 6.0.8 | `new_chat(kind)` | Tạo hội thoại mới |
+| 6.0.9 | `collapse_requested()` | Thu nhỏ sidebar |
+| 6.0.10 | `expand_requested()` | Mở rộng sidebar |
+
+---
+
+## 🔹 7. 🧩 CÁC CHỨC NĂNG TOÀN CẦU (Global)
+
+### 7.1 MainWindow (app.py)
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 7.1.1 | `_build_topbar()` | Xây dựng thanh trên cùng (User name, Settings, Language) |
+| 7.1.2 | `_build_nav_rail()` | Xây dựng thanh điều hướng bên trái |
+| 7.1.3 | `_toggle_nav()` | Thu/mở nav rail (icon-only ↔ full) |
+| 7.1.4 | `_apply_nav_labels()` | Áp dụng labels cho nav items |
+| 7.1.5 | `_ensure_page(row)` | Xây dựng page lười (lazy loading) |
+| 7.1.6 | `_refresh_history()` | Làm mới history của tất cả panes |
+| 7.1.7 | `_on_scheduled_task_done()` | Thông báo khi scheduled task hoàn thành |
+| 7.1.8 | `_notify_task()` | Thông báo khi task hoàn thành |
+| 7.1.9 | `_on_projects_changed()` | Khi danh sách dự án thay đổi |
+| 7.1.10 | `_on_pane_turn_finished()` | Khi turn trong pane hoàn thành |
+| 7.1.11 | `_open_settings()` | Mở dialog cài đặt |
+| 7.1.12 | `_fit_to_screen()` | Tự động fit cửa sổ theo màn hình |
+| 7.1.13 | Toast notifications | Hiển thị thông báo toast |
+| 7.1.14 | System Tray | Minimize to tray, tray notifications |
+
+### 7.2 Skills Manager
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 7.2.1 | `_open_skills_manager()` | Mở Skill Manager |
+| 7.2.2 | `seed_library_skills()` | Gieo skills mặc định |
+| 7.2.3 | `prune_seeded_builtins()` | Dọn dẹp skills built-in |
+
+### 7.3 Welcome Dialog
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 7.3.1 | `maybe_show_welcome()` | Hiển thị dialog chào mừng lần đầu |
+
+### 7.4 i18n (Đa Ngôn Ngữ)
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 7.4.1 | `tr(key)` | Dịch chuỗi theo ngôn ngữ hiện tại |
+| 7.4.2 | `set_language(lang)` | Đặt ngôn ngữ |
+| 7.4.3 | `get_language()` | Lấy ngôn ngữ hiện tại |
+| 7.4.4 | `on_language_changed(callback)` | Đăng ký callback khi ngôn ngữ thay đổi |
+
+### 7.5 Task Scheduler (Nền)
+
+| # | Tên Hàm / Chức Năng | Mô Tả |
+|---|---------------------|--------|
+| 7.5.1 | `task_finished` signal | Khi scheduled task hoàn thành |
+| 7.5.2 | `history_ready` signal | Khi session của task sẵn sàng |
+| 7.5.3 | `running_session_ids()` | Lấy danh sách session đang chạy |
+
+---
+
+## 📌 TỔNG KẾT
+
+| Navigation Item | Số Hàm/Chức Năng |
+|----------------|:-:|
+| 📊 Dashboard | ~10 |
+| 📅 Schedule Task | ~25 |
+| 🏠 Workspace → Projects | ~8 |
+| 🏠 Workspace → Cowork | ~34 |
+| 🏠 Workspace → Co4E | ~36 |
+| 🏠 Workspace → Folder | ~22 |
+| 🏠 Workspace → Graph RAG | ~16 |
+| 📊 Monitoring | ~20 |
+| ⚙️ Settings | ~25 |
+| 📜 History Sidebar | ~10 |
+| 🌐 Global Functions | ~15 |
+| **TỔNG CỘNG** | **~221** |
+
+> **Lưu ý:** Đây là danh sách các hàm/chức năng ở cấp UI và business logic chính. Các hàm core (providers, MCP, worker, security…) nằm ở tầng dưới và được gọi bởi các hàm UI ở trên.

docs/project-context-mcp-team-guide.md

@@ -0,0 +1,58 @@
+# Project Context MCP — hướng dẫn làm song song
+
+Mục tiêu: hoàn thiện ba tool trên **cùng một server** `project_context`. Không tạo server, registry,
+policy hay error envelope mới. Shared skeleton đã khóa sẵn thứ tự an toàn:
+
+```text
+validate input → policy ALLOW → resolve provider → gọi upstream → validate output
+```
+
+## Chia việc
+
+| Người | Tool | Chỉ sửa | Branch đề xuất |
+|---|---|---|---|
+| Member A | `get_project_issue_context` | `tools/issue_context.py`, `providers/issue.py`, test riêng | `feat/mcp-issue-context` |
+| Member B | `search_project_knowledge` | `tools/knowledge_search.py`, `providers/knowledge.py`, test riêng | `feat/mcp-knowledge-search` |
+| Member C | `get_project_change_context` | `tools/change_context.py`, `providers/change.py`, test riêng | `feat/mcp-change-context` |
+
+Trước khi gửi task, thay `Member A/B/C` bằng username thật trên ba issue. Mỗi người **không sửa**
+`foundation.py`, `registry.py`, `runtime.py`, `server.py` hoặc file của người khác. Nếu shared contract
+cần đổi, mở một PR nhỏ riêng và để cả ba người rebase sau khi PR đó merge.
+
+## Bắt đầu trong 5 phút
+
+1. Chạy `python --version` và xác nhận Python 3.11+ như baseline trong `requirements.txt`.
+2. Tạo branch từ commit template chứa tài liệu này sau khi PR template merge.
+3. Đọc input/output model trong module tool được giao; không thêm field riêng của Gitea/Jira/Redmine.
+4. Implement provider read-only trong module `providers/<tool>.py`; credential chỉ lấy sau policy ALLOW.
+5. Thêm test happy, invalid, not-found, timeout, DENIED với `resolver.calls == 0`, output sai schema,
+   truncation/cursor và source mở được có `revision`.
+6. Chạy:
+
+   ```bash
+   python -m pytest tests/test_project_context_mcp_template.py tests/test_project_context_<tool>.py -q
+   ```
+
+   Lệnh trên chạy trực tiếp từ root repo `cowork_local`; `tests/conftest.py` đã thiết lập import path.
+
+## Definition of Done của từng người
+
+- Tool trả đúng schema, có `project_id` và source gồm `system`, `url`, `revision`, `retrieved_at`.
+- Provider-neutral: đổi Gitea sang GitHub/Jira/Redmine không đổi schema hay tool name.
+- Sai project bị `DENIED` trước khi resolve credential và trước mọi upstream call.
+- Không log/return token; lỗi ngoài dự kiến không lộ exception; read không có side effect.
+- Output lớn có `truncated`, `returned`, `remaining`, `next_cursor`; không cắt im lặng.
+- Test riêng pass, test shared pass, PR chỉ chạm đúng vùng sở hữu trong bảng trên.
+
+## Chạy server sau khi provider đã cấu hình
+
+```bash
+COWORK_MCP_ACTOR_ID=<actor> \
+COWORK_MCP_ORG_UNIT=<org> \
+COWORK_MCP_CUSTOMER=<customer> \
+COWORK_MCP_PROJECT=<project> \
+python -m cowork_local.mcp_servers.project_context_server
+```
+
+Không commit giá trị môi trường hoặc credential. Cowork kết nối bằng stdio với command Python và
+args `-m cowork_local.mcp_servers.project_context_server`.

docs/rag-qa.html

@@ -0,0 +1,540 @@
+<!doctype html>
+<html lang="vi">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Tìm hiểu RAG — Hỏi &amp; Đáp</title>
+<style>
+:root{
+  --navy:#1B3C87; --blue:#0A4EA3; --acc:#1565C0; --acc2:#4A90D9;
+  --bg:#fff; --sf:#F7F9FC; --card:#fff; --bd:#E3E8EF; --bds:#CBD5E1;
+  --tx:#2B3542; --mut:#5A6675; --fnt:#8A94A3;
+  --ok:#1B7A3D; --okbg:#E8F5EC; --warn:#B26A00; --warnbg:#FDF3E3;
+  --bad:#C0392B; --badbg:#FCEDEC; --r:10px;
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--tx);
+  font:15px/1.6 "Segoe UI Variable Text","Segoe UI",system-ui,sans-serif}
+.bar{background:var(--navy);color:#fff;padding:12px 28px;font-weight:700;font-size:16px;
+  display:flex;justify-content:space-between;align-items:center;position:sticky;top:0;z-index:9}
+.bar .sub{font-weight:400;opacity:.85;font-size:13px}
+.wrap{max-width:1060px;margin:0 auto;padding:28px 28px 80px}
+h1{color:var(--blue);font-size:30px;margin:14px 0 6px;letter-spacing:-.02em}
+h2{color:var(--blue);font-size:20px;margin:40px 0 4px;padding-top:18px;
+  border-top:2px solid var(--bd)}
+.lead{color:var(--mut);margin:0 0 8px}
+.qa{border:1px solid var(--bd);border-radius:var(--r);margin:14px 0;background:var(--card);
+  box-shadow:0 1px 2px rgba(16,32,64,.04)}
+.q{padding:13px 18px;font-weight:700;color:var(--blue);font-size:15.5px;
+  display:flex;gap:10px;align-items:flex-start}
+.q .n{background:var(--acc);color:#fff;border-radius:5px;min-width:26px;height:22px;
+  display:inline-flex;align-items:center;justify-content:center;font-size:12px;flex:none}
+.a{padding:0 18px 15px 54px;color:var(--tx)}
+.a p{margin:0 0 8px}
+.a ul{margin:6px 0;padding-left:20px}.a li{margin:3px 0}
+b{color:var(--blue)}
+code{font:13px "Cascadia Code",Consolas,monospace;background:var(--sf);
+  border:1px solid var(--bd);border-radius:4px;padding:1px 5px;color:#0F3D6E}
+.note{border-left:4px solid var(--acc);background:#EAF2FC;border-radius:6px;
+  padding:10px 14px;margin:10px 0}
+.note.ok{border-left-color:var(--ok);background:var(--okbg)}
+.note.warn{border-left-color:var(--warn);background:var(--warnbg)}
+.note.bad{border-left-color:var(--bad);background:var(--badbg)}
+figure{margin:12px 0;padding:14px;background:var(--sf);border:1px solid var(--bd);
+  border-radius:var(--r)}
+figure svg{display:block;width:100%;height:auto}
+figcaption{color:var(--fnt);font-size:12.5px;margin-top:8px;text-align:center}
+table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14px}
+th,td{text-align:left;padding:7px 11px;border-bottom:1px solid var(--bd);vertical-align:top}
+th{color:var(--mut);font-size:12px;text-transform:uppercase;letter-spacing:.05em}
+.toc{background:var(--sf);border:1px solid var(--bd);border-radius:var(--r);padding:14px 20px}
+.toc ol{margin:6px 0;padding-left:20px;columns:2;column-gap:32px;font-size:14px}
+.toc a{color:var(--tx);text-decoration:none}.toc a:hover{color:var(--acc)}
+@media(max-width:820px){.toc ol{columns:1}.a{padding-left:18px}}
+</style>
+</head>
+<body>
+<div class="bar"><span>Tìm hiểu RAG — Hỏi &amp; Đáp</span>
+<span class="sub">Chuẩn bị cho phần Q&amp;A sau buổi trình bày</span></div>
+<div class="wrap">
+
+<h1>Những câu hay được hỏi nhất</h1>
+<p class="lead">20 câu, xếp từ dễ tới khó. Năm câu cuối là về chính dự án Cowork-Local —
+nhóm câu này gần như chắc chắn sẽ có người hỏi.</p>
+
+<div class="toc"><b>Nội dung</b>
+<ol>
+<li><a href="#q1">RAG là gì, nói gọn trong một câu?</a></li>
+<li><a href="#q2">RAG khác fine-tuning thế nào?</a></li>
+<li><a href="#q3">RAG có xoá hết bịa đặt không?</a></li>
+<li><a href="#q4">Vector là gì mà so sánh được nghĩa?</a></li>
+<li><a href="#q5">Chia đoạn bao nhiêu chữ là đúng?</a></li>
+<li><a href="#q6">Overlap để làm gì?</a></li>
+<li><a href="#q7">top-K nên đặt bao nhiêu?</a></li>
+<li><a href="#q8">Chọn mô hình embedding thế nào? Tiếng Việt thì sao?</a></li>
+<li><a href="#q9">Bắt buộc phải có Vector DB không?</a></li>
+<li><a href="#q10">Chỉ tìm theo vector đã đủ chưa?</a></li>
+<li><a href="#q11">Câu hỏi cần nối nhiều tài liệu thì sao?</a></li>
+<li><a href="#q12">Context window đã 1 triệu token, còn cần RAG?</a></li>
+<li><a href="#q13">Chi phí thực tế bao nhiêu?</a></li>
+<li><a href="#q14">RAG làm chậm bao nhiêu?</a></li>
+<li><a href="#q15">Tài liệu sửa thì cập nhật thế nào?</a></li>
+<li><a href="#q16">Đo chất lượng RAG bằng gì?</a></li>
+<li><a href="#q17">Phân quyền tài liệu xử lý ra sao?</a></li>
+<li><a href="#q18">Cowork-Local đã có RAG chưa?</a></li>
+<li><a href="#q19">GraphRAG của dự án có phải GraphRAG của Microsoft?</a></li>
+<li><a href="#q20">Muốn nâng lên RAG đầy đủ cần làm gì?</a></li>
+</ol></div>
+
+<h2>Nhóm 1 — Khái niệm</h2>
+
+<div class="qa" id="q1"><div class="q"><span class="n">1</span>
+RAG là gì, nói gọn trong một câu?</div>
+<div class="a">
+<p><b>Tìm tài liệu liên quan trước, rồi đưa cho LLM đọc và trả lời dựa trên đó</b> — thay vì
+để LLM trả lời bằng trí nhớ có sẵn.</p>
+<p>Ví von: thay vì bắt thí sinh làm bài từ trí nhớ, ta cho <i>thi mở sách</i> — nhưng có
+thủ thư lật sẵn đúng trang cần đọc.</p>
+</div></div>
+
+<div class="qa" id="q2"><div class="q"><span class="n">2</span>
+RAG khác fine-tuning thế nào? Khi nào dùng cái nào?</div>
+<div class="a">
+<figure>
+<svg viewBox="0 0 720 190" role="img" aria-label="So sánh RAG và fine-tuning">
+<rect x="8" y="14" width="340" height="162" rx="8" fill="#EAF2FC" stroke="#1565C0"/>
+<text x="26" y="40" font-size="15" font-weight="700" fill="#0A4EA3">RAG — đưa thêm tài liệu</text>
+<rect x="26" y="56" width="86" height="34" rx="5" fill="#fff" stroke="#4A90D9"/>
+<text x="69" y="77" font-size="12" text-anchor="middle" fill="#2B3542">Câu hỏi</text>
+<path d="M116 73 h22" stroke="#5A6675" stroke-width="1.6" marker-end="url(#ar)"/>
+<rect x="142" y="56" width="94" height="34" rx="5" fill="#fff" stroke="#4A90D9"/>
+<text x="189" y="72" font-size="11" text-anchor="middle" fill="#2B3542">Tìm tài liệu</text>
+<text x="189" y="84" font-size="10" text-anchor="middle" fill="#5A6675">top-K đoạn</text>
+<path d="M240 73 h22" stroke="#5A6675" stroke-width="1.6" marker-end="url(#ar)"/>
+<rect x="266" y="56" width="66" height="34" rx="5" fill="#1565C0"/>
+<text x="299" y="77" font-size="12" text-anchor="middle" fill="#fff">LLM</text>
+<text x="26" y="116" font-size="12" fill="#2B3542">✔ Cập nhật tức thì — chỉ re-index</text>
+<text x="26" y="136" font-size="12" fill="#2B3542">✔ Trích được nguồn</text>
+<text x="26" y="156" font-size="12" fill="#2B3542">✔ Rẻ, không cần GPU train</text>
+<rect x="372" y="14" width="340" height="162" rx="8" fill="#FDF3E3" stroke="#B26A00"/>
+<text x="390" y="40" font-size="15" font-weight="700" fill="#8A5000">Fine-tune — dạy lại mô hình</text>
+<rect x="390" y="56" width="96" height="34" rx="5" fill="#fff" stroke="#D9A24A"/>
+<text x="438" y="72" font-size="11" text-anchor="middle" fill="#2B3542">Dữ liệu mẫu</text>
+<text x="438" y="84" font-size="10" text-anchor="middle" fill="#5A6675">hàng nghìn cặp</text>
+<path d="M490 73 h22" stroke="#5A6675" stroke-width="1.6" marker-end="url(#ar)"/>
+<rect x="516" y="56" width="80" height="34" rx="5" fill="#fff" stroke="#D9A24A"/>
+<text x="556" y="77" font-size="12" text-anchor="middle" fill="#2B3542">Huấn luyện</text>
+<path d="M600 73 h22" stroke="#5A6675" stroke-width="1.6" marker-end="url(#ar)"/>
+<rect x="626" y="56" width="70" height="34" rx="5" fill="#B26A00"/>
+<text x="661" y="77" font-size="12" text-anchor="middle" fill="#fff">Model mới</text>
+<text x="390" y="116" font-size="12" fill="#2B3542">✔ Dạy được <i>văn phong</i>, định dạng</text>
+<text x="390" y="136" font-size="12" fill="#2B3542">✔ Dạy được kỹ năng chuyên ngành</text>
+<text x="390" y="156" font-size="12" fill="#2B3542">✘ Kiến thức mới → phải train lại</text>
+<defs><marker id="ar" markerWidth="7" markerHeight="7" refX="6" refY="3.5" orient="auto">
+<path d="M0 0 L7 3.5 L0 7 z" fill="#5A6675"/></marker></defs>
+</svg>
+<figcaption>RAG thêm <i>kiến thức</i>. Fine-tune thay đổi <i>hành vi</i>.</figcaption>
+</figure>
+<p><b>Quy tắc chọn:</b> câu trả lời phụ thuộc <i>nội dung tài liệu</i> → RAG.
+Phụ thuộc <i>cách nói / định dạng / kỹ năng</i> → fine-tune. Cần cả hai thì làm cả hai.</p>
+<div class="note">Đa số bài toán doanh nghiệp là loại thứ nhất, nên RAG hầu như luôn là
+bước làm trước.</div>
+</div></div>
+
+<div class="qa" id="q3"><div class="q"><span class="n">3</span>
+RAG có xoá hết bịa đặt (hallucination) không?</div>
+<div class="a">
+<p><b>Không. Chỉ giảm mạnh.</b> Đây là câu dễ bị hỏi vặn nhất, nên trả lời thẳng.</p>
+<p>RAG vẫn sai được ở bốn chỗ:</p>
+<ul>
+<li><b>Tra sai đoạn</b> — lấy nhầm tài liệu, LLM trả lời trung thực trên tài liệu sai.</li>
+<li><b>Không có trong kho</b> — LLM vẫn cố trả lời thay vì nói "không tìm thấy".</li>
+<li><b>Đọc đúng nhưng suy diễn thêm</b> — thêm chi tiết không có trong đoạn trích.</li>
+<li><b>Tài liệu gốc đã sai</b> — RAG không kiểm chứng nội dung.</li>
+</ul>
+<div class="note warn">Cách khắc phục thực dụng: bắt LLM <b>trích dẫn đoạn nguồn</b> cho từng ý,
+và cho phép trả lời <b>"không tìm thấy trong tài liệu"</b>. Slide "Ưu điểm" nên nói
+<i>giảm</i> hallucination, không nói <i>hết</i>.</div>
+</div></div>
+
+<div class="qa" id="q4"><div class="q"><span class="n">4</span>
+Vector là gì mà so sánh được "nghĩa giống nhau"?</div>
+<div class="a">
+<figure>
+<svg viewBox="0 0 720 210" role="img" aria-label="Không gian vector, các câu gần nghĩa nằm gần nhau">
+<rect x="40" y="14" width="640" height="164" rx="8" fill="#fff" stroke="var(--bds)"/>
+<line x1="70" y1="160" x2="660" y2="160" stroke="#CBD5E1"/>
+<line x1="70" y1="160" x2="70" y2="30" stroke="#CBD5E1"/>
+<circle cx="180" cy="70" r="6" fill="#1565C0"/><text x="192" y="74" font-size="12">"Xe hơi"</text>
+<circle cx="214" cy="88" r="6" fill="#1565C0"/><text x="226" y="92" font-size="12">"Ô tô"</text>
+<circle cx="196" cy="52" r="6" fill="#1565C0"/><text x="208" y="56" font-size="12">"Xe bốn bánh"</text>
+<ellipse cx="200" cy="70" rx="86" ry="46" fill="none" stroke="#1565C0"
+  stroke-dasharray="4 3" opacity=".6"/>
+<circle cx="520" cy="120" r="6" fill="#B26A00"/><text x="532" y="124" font-size="12">"Nấu phở"</text>
+<circle cx="556" cy="98" r="6" fill="#B26A00"/><text x="568" y="102" font-size="12">"Công thức bún"</text>
+<ellipse cx="540" cy="110" rx="70" ry="38" fill="none" stroke="#B26A00"
+  stroke-dasharray="4 3" opacity=".6"/>
+<circle cx="300" cy="118" r="7" fill="#C0392B"/>
+<text x="252" y="140" font-size="12" fill="#C0392B">câu hỏi của user</text>
+<line x1="300" y1="118" x2="214" y2="88" stroke="#C0392B" stroke-width="1.4"/>
+<text x="236" y="112" font-size="10.5" fill="#C0392B">gần → lấy</text>
+<line x1="300" y1="118" x2="520" y2="120" stroke="#CBD5E1" stroke-width="1.2"
+  stroke-dasharray="3 3"/>
+<text x="386" y="134" font-size="10.5" fill="#8A94A3">xa → bỏ qua</text>
+</svg>
+<figcaption>Mỗi đoạn chữ thành một điểm trong không gian nhiều chiều.
+Gần nhau = gần nghĩa.</figcaption>
+</figure>
+<p>Mô hình embedding biến một đoạn chữ thành dãy số (768 – 4096 chiều). Nó được huấn luyện
+sao cho <b>hai đoạn cùng nghĩa cho ra hai điểm gần nhau</b>, kể cả khi không trùng một chữ nào.</p>
+<p>Máy đo "gần" bằng <b>cosine similarity</b> — góc giữa hai vector. Nhờ vậy hỏi "xe hơi"
+vẫn tìm ra tài liệu viết "ô tô".</p>
+<div class="note">Đây chính là điểm RAG hơn tìm kiếm từ khoá: từ khoá cần <i>trùng chữ</i>,
+vector chỉ cần <i>trùng nghĩa</i>.</div>
+</div></div>
+
+<h2>Nhóm 2 — Tham số kỹ thuật</h2>
+
+<div class="qa" id="q5"><div class="q"><span class="n">5</span>
+Chia đoạn bao nhiêu chữ là đúng?</div>
+<div class="a">
+<p><b>Không có con số đúng chung</b> — phụ thuộc loại tài liệu. Nhưng có nguyên tắc:</p>
+<table>
+<tr><th>Loại tài liệu</th><th>Cỡ đoạn gợi ý</th><th>Vì sao</th></tr>
+<tr><td>FAQ, hỏi đáp ngắn</td><td>100 – 300 chữ</td><td>Mỗi mục vốn đã độc lập</td></tr>
+<tr><td>Chính sách, quy trình</td><td>300 – 600 chữ</td><td>Giữ trọn một điều khoản</td></tr>
+<tr><td>Sách, báo cáo dài</td><td>500 – 1000 chữ</td><td>Cần đủ ngữ cảnh xung quanh</td></tr>
+<tr><td>Mã nguồn</td><td>theo hàm / lớp</td><td>Cắt giữa hàm là hỏng nghĩa</td></tr>
+</table>
+<div class="note warn"><b>Đoạn quá nhỏ</b> → mất ngữ cảnh, tra ra mảnh vụn vô nghĩa.
+<b>Đoạn quá lớn</b> → một đoạn chứa nhiều chủ đề, vector bị "trung bình hoá" nên tra kém chính xác,
+lại tốn token.</div>
+<p>Thực tế nên <b>cắt theo cấu trúc trước</b> (theo mục, theo điều, theo hàm) rồi mới giới hạn
+độ dài — cắt cứng theo số chữ là phương án cuối.</p>
+</div></div>
+
+<div class="qa" id="q6"><div class="q"><span class="n">6</span>
+Overlap 10–20% để làm gì?</div>
+<div class="a">
+<figure>
+<svg viewBox="0 0 720 150" role="img" aria-label="Chia đoạn có phần chồng lấn">
+<text x="20" y="26" font-size="12.5" font-weight="700" fill="#C0392B">Không overlap — câu bị cắt đôi</text>
+<rect x="20" y="36" width="200" height="30" rx="4" fill="#EAF2FC" stroke="#4A90D9"/>
+<rect x="222" y="36" width="200" height="30" rx="4" fill="#EAF2FC" stroke="#4A90D9"/>
+<rect x="424" y="36" width="200" height="30" rx="4" fill="#EAF2FC" stroke="#4A90D9"/>
+<text x="120" y="55" font-size="11" text-anchor="middle">đoạn 1</text>
+<text x="322" y="55" font-size="11" text-anchor="middle">đoạn 2</text>
+<text x="524" y="55" font-size="11" text-anchor="middle">đoạn 3</text>
+<line x1="221" y1="30" x2="221" y2="72" stroke="#C0392B" stroke-width="2"/>
+<text x="228" y="82" font-size="10.5" fill="#C0392B">"Mức phụ cấp là | 2 triệu/tháng" — mất vế sau</text>
+<text x="20" y="110" font-size="12.5" font-weight="700" fill="#1B7A3D">Có overlap — câu nào cũng trọn ở ít nhất 1 đoạn</text>
+<rect x="20" y="118" width="210" height="26" rx="4" fill="#E8F5EC" stroke="#1B7A3D"/>
+<rect x="196" y="118" width="210" height="26" rx="4" fill="#E8F5EC" stroke="#1B7A3D"
+  opacity=".75"/>
+<rect x="372" y="118" width="210" height="26" rx="4" fill="#E8F5EC" stroke="#1B7A3D"
+  opacity=".55"/>
+<rect x="196" y="118" width="34" height="26" fill="#1B7A3D" opacity=".2"/>
+<rect x="372" y="118" width="34" height="26" fill="#1B7A3D" opacity=".2"/>
+<text x="600" y="136" font-size="10.5" fill="#1B7A3D">phần tô đậm = chồng lấn</text>
+</svg>
+<figcaption>Overlap là bảo hiểm cho những câu nằm vắt ngang ranh giới đoạn.</figcaption>
+</figure>
+<p>Cắt cứng theo số chữ sẽ có lúc cắt <b>giữa một câu hoặc giữa một ý</b>. Đoạn nào cũng
+lặp lại một phần đoạn trước thì thông tin ở ranh giới luôn còn nguyên vẹn ở ít nhất một đoạn.</p>
+<p>Giá phải trả: kho phình thêm đúng bằng tỉ lệ overlap. 20% overlap → nhiều hơn ~20% vector.</p>
+</div></div>
+
+<div class="qa" id="q7"><div class="q"><span class="n">7</span>
+top-K nên đặt bao nhiêu?</div>
+<div class="a">
+<p>Thường <b>3 – 10</b>. Cách chọn:</p>
+<ul>
+<li><b>K nhỏ (3–5)</b> — câu hỏi tra cứu một dữ kiện. Ít nhiễu, rẻ, nhanh.</li>
+<li><b>K lớn (8–15)</b> — câu hỏi tổng hợp, cần gom nhiều nguồn.</li>
+</ul>
+<div class="note warn">K càng lớn <b>không</b> đồng nghĩa càng chính xác. Đoạn thứ 15 thường
+đã lạc đề, và nó <i>làm loãng</i> ngữ cảnh khiến LLM trả lời kém đi — hiện tượng
+"lạc giữa đống tài liệu".</div>
+<p>Thực dụng hơn: đặt <b>ngưỡng điểm tương đồng</b> thay vì K cố định — lấy mọi đoạn trên
+ngưỡng, không có đoạn nào đạt thì trả lời "không tìm thấy".</p>
+</div></div>
+
+<div class="qa" id="q8"><div class="q"><span class="n">8</span>
+Chọn mô hình embedding thế nào? Tiếng Việt có ổn không?</div>
+<div class="a">
+<p>Ba tiêu chí: <b>hỗ trợ tiếng Việt</b>, <b>số chiều</b>, <b>chạy nội bộ hay gọi API</b>.</p>
+<table>
+<tr><th>Nhóm</th><th>Ví dụ</th><th>Ghi chú</th></tr>
+<tr><td>API thương mại</td><td>OpenAI <code>text-embedding-3</code>, Cohere</td>
+<td>Chất lượng tốt, nhưng <b>tài liệu phải gửi ra ngoài</b></td></tr>
+<tr><td>Đa ngữ, chạy nội bộ</td><td>multilingual-e5, BGE-M3</td>
+<td>Tiếng Việt khá tốt, chạy được trên máy công ty</td></tr>
+<tr><td>Chuyên tiếng Việt</td><td>PhoBERT và các bản fine-tune</td>
+<td>Cần đánh giá lại trên chính dữ liệu của mình</td></tr>
+</table>
+<div class="note bad"><b>Lưu ý bắt buộc:</b> đổi mô hình embedding thì
+<b>phải index lại toàn bộ kho</b>. Vector của mô hình này không so sánh được với vector của
+mô hình khác. Nên chọn kỹ ngay từ đầu.</div>
+<p>Với dữ liệu nội bộ nhạy cảm, nhóm "chạy nội bộ" thường là lựa chọn duy nhất khả thi.</p>
+</div></div>
+
+<div class="qa" id="q9"><div class="q"><span class="n">9</span>
+Bắt buộc phải có Vector DB riêng không?</div>
+<div class="a">
+<p><b>Không.</b> Chọn theo quy mô:</p>
+<table>
+<tr><th>Quy mô</th><th>Giải pháp</th><th>Ghi chú</th></tr>
+<tr><td>&lt; 100k vector</td><td>FAISS, Chroma, hoặc file numpy</td>
+<td>Không cần dựng thêm dịch vụ</td></tr>
+<tr><td>Đã có PostgreSQL</td><td><code>pgvector</code></td>
+<td>Dùng luôn DB sẵn có — thường là lựa chọn tốt nhất</td></tr>
+<tr><td>Triệu vector trở lên</td><td>Milvus, Qdrant, Weaviate</td>
+<td>Cần index ANN chuyên dụng</td></tr>
+<tr><td>Không muốn tự vận hành</td><td>Pinecone</td>
+<td>Dịch vụ đám mây, dữ liệu ra ngoài</td></tr>
+</table>
+<p>Ví dụ trong slide — 100 file PDF ra 20.000 vector — <b>hoàn toàn không cần</b> Vector DB
+chuyên dụng. FAISS trên một máy là đủ và nhanh.</p>
+</div></div>
+
+<h2>Nhóm 3 — Chất lượng truy hồi</h2>
+
+<div class="qa" id="q10"><div class="q"><span class="n">10</span>
+Chỉ tìm theo vector đã đủ chưa?</div>
+<div class="a">
+<figure>
+<svg viewBox="0 0 720 168" role="img" aria-label="Hybrid search và rerank">
+<rect x="14" y="52" width="98" height="42" rx="6" fill="#fff" stroke="#4A90D9"/>
+<text x="63" y="70" font-size="12" text-anchor="middle">Câu hỏi</text>
+<text x="63" y="85" font-size="10" text-anchor="middle" fill="#5A6675">của user</text>
+<path d="M116 73 h26" stroke="#5A6675" stroke-width="1.6" marker-end="url(#a2)"/>
+<rect x="146" y="20" width="128" height="42" rx="6" fill="#EAF2FC" stroke="#1565C0"/>
+<text x="210" y="38" font-size="12" text-anchor="middle" fill="#0A4EA3">Tìm theo vector</text>
+<text x="210" y="52" font-size="10" text-anchor="middle" fill="#5A6675">bắt được ý nghĩa</text>
+<rect x="146" y="84" width="128" height="42" rx="6" fill="#FDF3E3" stroke="#B26A00"/>
+<text x="210" y="102" font-size="12" text-anchor="middle" fill="#8A5000">Tìm theo từ khoá</text>
+<text x="210" y="116" font-size="10" text-anchor="middle" fill="#5A6675">bắt mã, tên riêng</text>
+<path d="M278 41 h20 v32" stroke="#5A6675" stroke-width="1.6" fill="none"/>
+<path d="M278 105 h20 v-32" stroke="#5A6675" stroke-width="1.6" fill="none"
+  marker-end="url(#a2)"/>
+<rect x="318" y="52" width="104" height="42" rx="6" fill="#fff" stroke="#4A90D9"/>
+<text x="370" y="70" font-size="12" text-anchor="middle">Gộp kết quả</text>
+<text x="370" y="85" font-size="10" text-anchor="middle" fill="#5A6675">~30 đoạn</text>
+<path d="M426 73 h26" stroke="#5A6675" stroke-width="1.6" marker-end="url(#a2)"/>
+<rect x="456" y="52" width="110" height="42" rx="6" fill="#1565C0"/>
+<text x="511" y="70" font-size="12" text-anchor="middle" fill="#fff">Rerank</text>
+<text x="511" y="85" font-size="10" text-anchor="middle" fill="#D6E7F8">chấm lại điểm</text>
+<path d="M570 73 h26" stroke="#5A6675" stroke-width="1.6" marker-end="url(#a2)"/>
+<rect x="600" y="52" width="104" height="42" rx="6" fill="#E8F5EC" stroke="#1B7A3D"/>
+<text x="652" y="70" font-size="12" text-anchor="middle" fill="#14612F">Top 5 tinh</text>
+<text x="652" y="85" font-size="10" text-anchor="middle" fill="#5A6675">đưa cho LLM</text>
+<defs><marker id="a2" markerWidth="7" markerHeight="7" refX="6" refY="3.5" orient="auto">
+<path d="M0 0 L7 3.5 L0 7 z" fill="#5A6675"/></marker></defs>
+</svg>
+<figcaption>Hai cách tìm bù khuyết cho nhau, rồi lọc lại một lần nữa.</figcaption>
+</figure>
+<p><b>Chưa đủ.</b> Vector giỏi bắt ý nghĩa nhưng <b>dở với mã số, tên riêng, ký hiệu</b> —
+hỏi "điều 7.5.3" hay "mã lỗi FN0101" thì tìm từ khoá lại chính xác hơn hẳn.</p>
+<p>Hai cải tiến gần như luôn đáng làm:</p>
+<ul>
+<li><b>Hybrid search</b> — chạy song song vector + từ khoá (BM25), gộp kết quả.</li>
+<li><b>Rerank</b> — lấy ~30 đoạn rồi dùng mô hình cross-encoder chấm lại, giữ 5 đoạn tốt nhất.
+Đây thường là <b>cải thiện lớn nhất</b> với chi phí nhỏ nhất.</li>
+</ul>
+</div></div>
+
+<div class="qa" id="q11"><div class="q"><span class="n">11</span>
+Câu hỏi cần nối nhiều tài liệu (multi-hop) thì sao?</div>
+<div class="a">
+<p>Slide đã nêu đúng đây là điểm yếu. Ví dụ: <i>"Nhân viên nào ký hợp đồng với nhà cung cấp
+có doanh số cao nhất năm ngoái?"</i> — cần tra bảng doanh số trước, rồi mới tra hợp đồng.</p>
+<p>RAG một lượt sẽ hỏng, vì một lần tra không thể ra cả hai. Ba hướng xử lý:</p>
+<ul>
+<li><b>Tra nhiều vòng (agentic RAG)</b> — cho LLM tự quyết định tra tiếp, dùng kết quả vòng
+trước làm câu truy vấn vòng sau.</li>
+<li><b>Tách câu hỏi</b> — chia thành các câu con, tra từng câu, rồi tổng hợp.</li>
+<li><b>Knowledge graph</b> — dựng sẵn quan hệ giữa các thực thể để đi theo liên kết thay vì
+tra lại từ đầu. Đây chính là ý tưởng của GraphRAG.</li>
+</ul>
+</div></div>
+
+<h2>Nhóm 4 — Vận hành</h2>
+
+<div class="qa" id="q12"><div class="q"><span class="n">12</span>
+Context window đã tới 1 triệu token — còn cần RAG không?</div>
+<div class="a">
+<p><b>Vẫn cần</b>, vì ba lý do:</p>
+<ul>
+<li><b>Chi phí</b> — nhét 500k token vào mỗi câu hỏi thì mỗi lượt hỏi tốn gấp hàng trăm lần
+so với nhét 5 đoạn. Nhân với số lượt hỏi mỗi ngày.</li>
+<li><b>Độ trễ</b> — đọc 500k token mất hàng chục giây.</li>
+<li><b>Quy mô</b> — kho tài liệu doanh nghiệp thường vài chục triệu token, vượt xa mọi
+context window.</li>
+</ul>
+<div class="note">Thêm nữa, độ chính xác <b>giảm khi ngữ cảnh quá dài</b> — mô hình hay bỏ sót
+thông tin nằm ở giữa. Đưa 5 đoạn đúng thường cho kết quả tốt hơn đưa cả cuốn sách.</div>
+<p>Context dài <i>có</i> chỗ dùng: khi tổng tài liệu nhỏ (vài chục trang) và bạn muốn giải pháp
+đơn giản nhất — lúc đó bỏ RAG cho gọn là hợp lý.</p>
+</div></div>
+
+<div class="qa" id="q13"><div class="q"><span class="n">13</span>
+Chi phí thực tế bao nhiêu?</div>
+<div class="a">
+<p>Tách làm hai phần, và phần đắt <b>không</b> phải phần người ta hay lo:</p>
+<table>
+<tr><th>Khoản</th><th>Khi nào phát sinh</th><th>Mức độ</th></tr>
+<tr><td>Embedding tài liệu</td><td>Một lần lúc index + khi tài liệu đổi</td>
+<td><b>Rẻ</b> — embedding rẻ hơn LLM hàng chục lần</td></tr>
+<tr><td>Lưu trữ vector</td><td>Liên tục</td><td>Nhỏ, trừ khi kho cực lớn</td></tr>
+<tr><td>Embedding câu hỏi</td><td>Mỗi lượt hỏi</td><td>Không đáng kể</td></tr>
+<tr><td><b>LLM sinh câu trả lời</b></td><td>Mỗi lượt hỏi</td>
+<td><b>Chiếm phần lớn chi phí</b></td></tr>
+</table>
+<p>Vì vậy giảm chi phí RAG thực chất là <b>giảm số token đưa vào LLM</b> — tức chọn top-K
+gọn và đoạn sạch, chứ không phải tiết kiệm ở khâu embedding.</p>
+</div></div>
+
+<div class="qa" id="q14"><div class="q"><span class="n">14</span>
+RAG làm chậm thêm bao nhiêu?</div>
+<div class="a">
+<p>Bước tra thường tốn <b>vài chục tới vài trăm mili-giây</b>: embedding câu hỏi + tìm trong
+vector DB. Có rerank thì cộng thêm chút nữa.</p>
+<p>So với thời gian LLM sinh câu trả lời (thường vài giây), phần này <b>gần như không đáng kể</b>.</p>
+<div class="note warn">Slide ghi "ứng dụng real-time cần &lt; 100ms" thì nên cẩn trọng —
+đúng, nhưng lúc đó nút thắt là <b>LLM</b>, không phải bước tra. Nếu cần dưới 100ms thì
+bản thân việc gọi LLM đã không khả thi rồi.</div>
+</div></div>
+
+<div class="qa" id="q15"><div class="q"><span class="n">15</span>
+Tài liệu sửa thì cập nhật thế nào?</div>
+<div class="a">
+<p>Chỉ cần <b>index lại phần thay đổi</b>, không đụng tới mô hình:</p>
+<ul>
+<li>File sửa → xoá vector cũ của file đó, embedding lại, ghi vector mới.</li>
+<li>File xoá → xoá vector tương ứng.</li>
+<li>File mới → embedding và thêm vào.</li>
+</ul>
+<p>Cách làm thực dụng: lưu kèm <b>hash nội dung</b> mỗi file, chạy định kỳ, chỉ xử lý file
+có hash đổi. Vài giây cho một lần cập nhật thông thường.</p>
+<div class="note bad">Ngoại lệ duy nhất phải làm lại toàn bộ: <b>đổi mô hình embedding</b>
+hoặc <b>đổi cách chia đoạn</b>.</div>
+</div></div>
+
+<div class="qa" id="q16"><div class="q"><span class="n">16</span>
+Đo chất lượng RAG bằng gì? Làm sao biết là tốt?</div>
+<div class="a">
+<p>Điểm mấu chốt: <b>đo tách hai khâu</b>, vì hỏng ở đâu thì sửa ở đó khác nhau.</p>
+<table>
+<tr><th>Khâu</th><th>Đo gì</th><th>Hỏng thì sửa gì</th></tr>
+<tr><td><b>Truy hồi</b></td><td>Đoạn đúng có nằm trong top-K không?</td>
+<td>Chia đoạn, mô hình embedding, hybrid, rerank</td></tr>
+<tr><td><b>Sinh câu trả lời</b></td><td>Câu trả lời có bám vào đoạn đã lấy không?</td>
+<td>Prompt, model, yêu cầu trích nguồn</td></tr>
+</table>
+<p>Cách làm tối thiểu mà hiệu quả: dựng <b>bộ 50–100 câu hỏi mẫu có đáp án đúng</b> lấy từ
+người dùng thật. Mỗi lần chỉnh tham số thì chạy lại bộ đó và so điểm.</p>
+<div class="note">Không có bộ câu hỏi mẫu thì mọi tinh chỉnh chỉ là cảm tính — đây là việc
+nên làm ngay từ đầu, trước cả khi tối ưu.</div>
+</div></div>
+
+<div class="qa" id="q17"><div class="q"><span class="n">17</span>
+Phân quyền tài liệu xử lý ra sao? Người A không được xem tài liệu của phòng B.</div>
+<div class="a">
+<p>Đây là câu hay bị bỏ quên tới lúc triển khai thật mới lộ ra.</p>
+<p><b>Nguyên tắc: lọc quyền ở bước truy hồi, không phải ở bước trả lời.</b> Tuyệt đối không
+dựa vào việc nhắc LLM "đừng nói về tài liệu này" — không đáng tin.</p>
+<ul>
+<li>Mỗi vector lưu kèm <b>metadata quyền</b> (phòng ban, mức mật, danh sách người xem).</li>
+<li>Khi tra, lọc theo quyền của người hỏi <b>ngay trong truy vấn</b>.</li>
+<li>Tài liệu ngoài quyền thì không bao giờ vào được ngữ cảnh của LLM.</li>
+</ul>
+<div class="note bad">Rủi ro thường gặp: một đoạn trích chứa thông tin mật lọt vào ngữ cảnh,
+LLM tóm tắt lại và <b>rò rỉ gián tiếp</b> dù không trích nguyên văn.</div>
+</div></div>
+
+<h2>Nhóm 5 — Về dự án Cowork-Local</h2>
+<p class="lead">Nhóm này gần như chắc chắn được hỏi, vì slide 17 đã tự nêu ra.</p>
+
+<div class="qa" id="q18"><div class="q"><span class="n">18</span>
+Vậy Cowork-Local đã có RAG chưa?</div>
+<div class="a">
+<p>Trả lời thẳng như slide 17 đã viết: <b>chưa có RAG theo nghĩa đầy đủ.</b></p>
+<figure>
+<svg viewBox="0 0 720 150" role="img" aria-label="Ba mức nạp ngữ cảnh">
+<rect x="10" y="24" width="222" height="104" rx="8" fill="#FDF3E3" stroke="#B26A00"/>
+<text x="121" y="48" font-size="13" font-weight="700" text-anchor="middle" fill="#8A5000">
+Mức 1 — Nạp thủ công</text>
+<text x="121" y="70" font-size="11.5" text-anchor="middle" fill="#2B3542">Đính kèm file, dán link,</text>
+<text x="121" y="86" font-size="11.5" text-anchor="middle" fill="#2B3542">Instructions của project</text>
+<text x="121" y="110" font-size="11" text-anchor="middle" fill="#8A5000">Người dùng tự chọn</text>
+<rect x="248" y="24" width="222" height="104" rx="8" fill="#EAF2FC" stroke="#1565C0"/>
+<text x="359" y="48" font-size="13" font-weight="700" text-anchor="middle" fill="#0A4EA3">
+Mức 2 — Tra theo cấu trúc</text>
+<text x="359" y="70" font-size="11.5" text-anchor="middle" fill="#2B3542">GraphRAG: sơ đồ file,</text>
+<text x="359" y="86" font-size="11.5" text-anchor="middle" fill="#2B3542">lớp, hàm, quan hệ</text>
+<text x="359" y="110" font-size="11" text-anchor="middle" fill="#0A4EA3">AI tự tra — đang ở đây</text>
+<rect x="486" y="24" width="224" height="104" rx="8" fill="#F2F4F7" stroke="#CBD5E1"
+  stroke-dasharray="5 4"/>
+<text x="598" y="48" font-size="13" font-weight="700" text-anchor="middle" fill="#5A6675">
+Mức 3 — Tra theo ngữ nghĩa</text>
+<text x="598" y="70" font-size="11.5" text-anchor="middle" fill="#5A6675">Embedding + Vector DB</text>
+<text x="598" y="86" font-size="11.5" text-anchor="middle" fill="#5A6675">tìm theo nghĩa</text>
+<text x="598" y="110" font-size="11" text-anchor="middle" fill="#8A94A3">chưa có</text>
+</svg>
+<figcaption>Dự án đang ở mức 2. Mức 3 mới là RAG như trình bày ở phần đầu.</figcaption>
+</figure>
+<p>Cách nói an toàn khi bị hỏi vặn: <i>"Hiện tại là truy xuất theo cấu trúc, chưa phải truy xuất
+theo ngữ nghĩa. Phần trình bày hôm nay là kiến thức nền cho bước tiếp theo."</i></p>
+</div></div>
+
+<div class="qa" id="q19"><div class="q"><span class="n">19</span>
+"GraphRAG" của dự án có phải GraphRAG của Microsoft không?</div>
+<div class="a">
+<div class="note warn"><b>Câu này rất dễ bị hỏi và dễ gây hiểu nhầm — nên chủ động làm rõ trước.</b></div>
+<table>
+<tr><th></th><th>GraphRAG (Microsoft)</th><th>GraphRAG trong Cowork-Local</th></tr>
+<tr><td>Đồ thị chứa gì</td><td>Thực thể và quan hệ do <b>LLM trích</b> từ nội dung</td>
+<td>File, lớp, hàm và liên kết import</td></tr>
+<tr><td>Dựng bằng gì</td><td>Gọi LLM nhiều lượt, tốn chi phí</td>
+<td>Phân tích cú pháp mã nguồn, <b>không tốn phí gọi AI</b></td></tr>
+<tr><td>Trả lời câu hỏi</td><td>Đi theo quan hệ + tóm tắt theo cụm</td>
+<td>Đọc sơ đồ và nội dung file liên quan</td></tr>
+</table>
+<p><b>Cùng tên, khác bản chất.</b> Slide của bạn mô tả đúng cái thứ hai — "quét file, ghi nhận
+mỗi file có class/hàm gì và liên kết với file nào".</p>
+<p>Nói rõ điểm này lại là <b>lợi thế</b>: cách của dự án <i>rẻ và nhanh hơn nhiều</i> vì không
+phải gọi LLM để dựng đồ thị.</p>
+</div></div>
+
+<div class="qa" id="q20"><div class="q"><span class="n">20</span>
+Muốn nâng lên RAG đầy đủ thì cần làm gì?</div>
+<div class="a">
+<p>Bốn việc, xếp theo thứ tự nên làm:</p>
+<table>
+<tr><th>#</th><th>Việc</th><th>Quyết định phải chốt</th></tr>
+<tr><td>1</td><td>Chọn mô hình embedding</td>
+<td>Chạy nội bộ hay gọi API — quyết định này ràng buộc mọi thứ sau, và
+<b>đổi về sau là phải index lại toàn bộ</b></td></tr>
+<tr><td>2</td><td>Chia đoạn tài liệu</td>
+<td>Cắt theo cấu trúc (mục, điều, hàm) trước khi cắt theo độ dài</td></tr>
+<tr><td>3</td><td>Chọn nơi lưu vector</td>
+<td>Quy mô hiện tại chỉ cần FAISS hoặc <code>pgvector</code></td></tr>
+<tr><td>4</td><td>Dựng bộ câu hỏi đánh giá</td>
+<td>50–100 câu có đáp án đúng — <b>làm trước khi tối ưu</b></td></tr>
+</table>
+<div class="note ok"><b>Điểm mạnh sẵn có:</b> dự án đã có sẵn khái niệm <i>project</i> với
+thư mục riêng và phân tách dữ liệu theo project. Đó chính là ranh giới phân quyền tự nhiên
+cho câu 17 — thứ mà nhiều dự án phải làm lại từ đầu.</div>
+</div></div>
+
+<h2>Ba câu nên chuẩn bị sẵn câu trả lời</h2>
+<div class="note bad"><b>1. "RAG có hết bịa không?"</b> → Không, chỉ giảm. Nói thẳng và nêu
+cách giảm: bắt trích nguồn, cho phép trả lời "không tìm thấy".</div>
+<div class="note bad"><b>2. "GraphRAG này có phải GraphRAG kia không?"</b> → Không, cùng tên
+khác bản chất. Chủ động nói trước khi bị hỏi.</div>
+<div class="note bad"><b>3. "Vậy dự án đã có RAG chưa?"</b> → Chưa đủ. Đang ở mức truy xuất
+theo cấu trúc, chưa có truy xuất theo ngữ nghĩa.</div>
+
+</div>
+</body>
+</html>

docs/refactor/DeltaTeam_prompt.md

@@ -0,0 +1,115 @@
+# HỆ THỐNG PROMPT KỸ SƯ TRƯỞNG PYTHON & KIẾN TRÚC SƯ TÁI CẤU TRÚC (TEAM DUY)
+
+Bạn là một **Kỹ sư phần mềm Python Cao cấp (Senior / Staff Python Engineer) & Chuyên gia Kiến trúc Ứng dụng Desktop Local-First**, giữ vai trò Tech Lead thực thi kỹ thuật cho **🔵 Team Duy** trong dự án **Cowork Local (Cowork-Local BamBOO)**.
+
+---
+
+## 🎯 NHIỆM VỤ CỐT LÕI & PHẠM VI SỞ HỮU CỦA TEAM DUY
+
+Nhiệm vụ của bạn là trực tiếp chỉ đạo và thực thi kế hoạch tái cấu trúc mã nguồn theo đúng tài liệu thiết kế kiến trúc `Feature_Architecture_Proposal.md` và cập nhật tiến độ vào file `Refactoring_Checklist.md`.
+
+### 📦 Các Phân Hệ Thư Mục Do Team Duy Quản Lý:
+- **Tầng Giao Diện (Presentation)**: `presentation/chat/` (Bóc tách từ `ui/chat_panel.py` và `ui/help_agent_widget.py`).
+- **Tầng Nghiệp Vụ (Application)**: `application/conversations/`, `application/model_routing/`.
+- **Tầng Miền Dữ Liệu (Domain)**: `domain/agents/`, `domain/models/`.
+- **Tầng Hạ Tầng (Infrastructure)**: `infrastructure/providers/`, `infrastructure/telemetry/`.
+- **Kiểm Thử & Quản Trị Hệ Thống (Testing & Governance)**: `tests/` (Unit, Contract, Integration, E2E Smoke), `scripts/` (Bộ công cụ kiểm duyệt CASAN Gate), `docs/governance/`.
+- **Các EPIC Trọng Tâm**: **R01, R03, R04, R08 (Phân hệ Chat UI: R08-T01 ➔ R08-T06), R10 (Chủ trì chính Testing Pyramid & Phát hành)**.
+
+---
+
+## ⚖️ CÁC QUY TẮC KIẾN TRÚC & NGUYÊN TẮC BẤT BIẾN
+
+1. **Kiến Trúc 4 Tầng Sạch (4-Tier Clean Architecture)**:
+   ```text
+   presentation/chat/ (PySide6 UI Widgets & Qt Signals)
+           │
+           ▼
+   application/conversations/ & application/model_routing/ (Pure Python Orchestration)
+           │
+           ▼
+   domain/agents/ & domain/models/ (Pure Python Entities, Events, Descriptors)
+           ▲
+           │
+   infrastructure/providers/ & infrastructure/telemetry/ (Adapters, Keyring, Network, Disk)
+   ```
+   - **QUY TẮC CỐT TỬ**: Tầng `domain/` và `application/` phải là **100% Pure Python**. TUYỆT ĐỐI KHÔNG import `PySide6`, `PyQt*` hay bất kỳ UI widget nào trong 2 tầng này.
+
+2. **Tuân Thủ Tuyệt Đối Cổng Kiểm Duyệt CASAN (CASAN Verification Gate)**:
+   - **C (Clean Arch)**: Chạy `python scripts/check_imports.py` phải đạt `0 Qt imports in domain and application`.
+   - **A (Atomic & Secret)**: 0 plaintext API Key/Token trong file cấu hình; 100% keys quản lý qua `SecretStore` (Keyring); ghi tệp an toàn qua `AtomicJsonFile`.
+   - **S (Single Responsibility)**: **GIỚI HẠN CỨNG: Không có file production nào vượt quá 400 dòng code (LOC)**.
+   - **A (Automated Tests)**: Bộ test chạy offline hoàn toàn, tốc độ siêu nhanh (< 1 giây cho unit tests), không phụ thuộc mạng hay Qt loop.
+   - **N (No Regression)**: 100% test pass khi chạy lệnh `pytest tests/`.
+
+3. **Bắt Buộc Comment Code Bằng Tiếng Anh (Mandatory English Comments)**:
+   - Ở **mỗi dòng hoặc khối code được chỉnh sửa/tạo mới**, bạn **BẮT BUỘC phải viết comment bằng Tiếng Anh** giải thích rõ logic xử lý, cách xử lý ngoại lệ và lý do kỹ thuật/kiến trúc (rationale).
+   - *Ví dụ mẫu*:
+     ```python
+     # Extract an immutable execution snapshot to decouple turn lifecycle from PySide6 UI state
+     request = ConversationExecutionRequest.from_ui_state(session_id=session_id, prompt=prompt)
+     ```
+
+4. **Ghi Nhận Mốc Thời Gian Thực Hiện (Start/End Timestamps)**:
+   - Trước khi bắt đầu code task nào, phải ghi nhận: `Start: YYYY-MM-DD HH:mm`.
+   - Sau khi code xong và unit test pass 100%, phải ghi nhận: `End: YYYY-MM-DD HH:mm` và đánh dấu `[x]` vào `Refactoring_Checklist.md`.
+
+5. **An Toàn Đa Luồng (Thread-Safety) & Snapshot Bất Biến**:
+   - Mọi tiến trình gọi AI và thực thi Tool phải chạy bất đồng bộ trong background thread, không bao giờ làm đơ Main Thread của PySide6.
+   - Giao diện UI chỉ được cập nhật thông qua Qt Signals/Slots lắng nghe luồng sự kiện `AgentEvent`.
+   - Luôn đóng gói trạng thái đầu vào thành `ConversationExecutionRequest` bất biến trước khi gửi vào Application Service.
+
+---
+
+## 🛠️ LỘ TRÌNH THỰC THI TỪNG BƯỚC (TEAM DUY)
+
+Khi thực hiện nhiệm vụ, tuân thủ đúng thứ tự 5 giai đoạn sau:
+
+### 📍 Giai Đoạn 1: Thiết Lập Nền Móng Kiến Trúc & Test Bảo Vệ (EPIC R01)
+1. `R01-T01`: Soạn thảo `docs/architecture/ADR-001-layered-architecture.md` định nghĩa ranh giới 4 tầng.
+2. `R01-T02`: Xây dựng `tests/fakes/fake_provider.py` & `fake_tool_executor.py` phục vụ test offline.
+3. `R01-T03`: Viết script phân tích cú pháp AST `scripts/check_imports.py` chặn import Qt trái phép.
+4. `R01-T04`: Viết Characterization Tests tại `tests/characterization/test_run_cowork.py` chụp snapshot hàm `core/chat_agent.py::run_cowork`.
+5. `R01-T05`: Phân loại và cô lập mã nguồn cũ trong `docs/architecture/dormant-code.md`.
+
+### 📍 Giai Đoạn 2: Chuẩn Hóa Provider & Hợp Nhất Bộ Định Tuyến (EPIC R03)
+1. `R03-T01`: Xây dựng bộ Contract Tests chuẩn hóa cho các Provider trong `tests/contracts/test_providers.py`.
+2. `R03-T02`: Tạo `domain/models/provider_descriptor.py` và `infrastructure/providers/provider_registry.py`.
+3. `R03-T03`: Xây dựng `application/model_routing/routing_application_service.py` (Pure Python) hỗ trợ 4 chế độ: Off, Auto, Manual, Fallback.
+4. `R03-T04` & `R03-T05`: Hợp nhất logic routing bị phân tán tại `ui/chat_panel.py#L638`, `ui/co4e_tab.py`, `ui/folder_tab.py` về gọi chung `RoutingApplicationService`.
+5. `R03-T06`: Tách bộ ghi nhận token usage thành `infrastructure/telemetry/usage_sink.py`.
+
+### 📍 Giai Đoạn 3: Động Cơ Hội Thoại & Vòng Đời Turn Chat (EPIC R04)
+1. `R04-T01`: Định nghĩa frozen dataclass snapshot `domain/agents/conversation_execution_request.py`.
+2. `R04-T02`: Định nghĩa các sự kiện có kiểu dữ liệu mạnh trong `domain/agents/agent_event.py` (`TextChunkEvent`, `ToolCallStartedEvent`, `ToolCallFinishedEvent`, `TurnCompletedEvent`, `ErrorEvent`).
+3. `R04-T03`: Cài đặt `application/conversations/conversation_application_service.py` điều phối toàn bộ vòng đời turn.
+4. `R04-T04` & `R04-T05`: Chuyển đổi `ui/cowork_tab.py` và `core/task_executors.py` sang dùng chung `ConversationApplicationService`.
+
+### 📍 Giai Đoạn 4: Phân Rã God-Widget Màn Hình Chat (EPIC R08 - Phân Hệ Chat)
+Bóc tách file khổng lồ `ui/chat_panel.py` (>1.800 dòng) thành 6 widget con chuyên biệt (< 400 dòng/file):
+1. `R08-T01`: `presentation/chat/chat_history_widget.py` (Render bong bóng chat, markdown stream, tool cards).
+2. `R08-T02`: `presentation/chat/composer_widget.py` (Ô nhập liệu text auto-resize, phím tắt Ctrl+Enter).
+3. `R08-T03`: `presentation/chat/attachment_picker.py` (Bộ chọn file, folder, ảnh đính kèm).
+4. `R08-T04`: `presentation/chat/audio_recorder_widget.py` (Ghi âm giọng nói & nhận diện văn bản).
+5. `R08-T05`: `presentation/chat/chat_output_panel.py` (Panel hiển thị và theo dõi file output trong turn).
+6. `R08-T06`: `presentation/chat/chat_panel.py` (Shell container điều phối các widget con và `Floating HelpAgent`).
+
+### 📍 Giai Đoạn 5: Tháp Kiểm Thử, Cổng CI Quality Gate & Smoke Test (EPIC R10 - Chủ Trì Chính)
+1. `R10-T01`: Cấu trúc lại thư mục test phân tầng (`tests/unit/`, `tests/contracts/`, `tests/integration/`, `tests/fakes/`).
+2. `R10-T02`: Xây dựng bộ script kiểm thử tự động (`scripts/check_imports.py`, `scripts/check_loc.py`, `scripts/audit_security.py`, `scripts/run_quality_gate.py`).
+3. `R10-T03`: Cập nhật tài liệu `README.md` và `START_CONTRIBUTING.md` với sơ đồ 4 tầng và hướng dẫn cấu hình Git hook.
+4. `R10-T04`: Soạn thảo `docs/governance/contributor-recipes.md` (3 công thức: Thêm Provider mới, Thêm Tool/MCP mới, Thêm Màn hình UI mới).
+5. `R10-T05`: Xây dựng bộ kiểm thử khói phát hành `tests/e2e/test_smoke.py` chạy qua headless Qt kiểm tra tự động 5 luồng nghiệp vụ cốt lõi.
+
+---
+
+## 📋 CHECKLIST TIÊU CHUẨN HOÀN THÀNH (DEFINITION OF DONE - DOD)
+
+Trước khi đóng bất kỳ task nào hoặc gửi PR, bạn phải tự kiểm tra 7 tiêu chí sau:
+- [ ] 1. **Kích thước file (LOC)**: Mọi file sửa đổi hoặc tạo mới đều **< 400 dòng code**.
+- [ ] 2. **Kiến trúc sạch (Clean Arch)**: 0 import `PySide6`/Qt trong `domain/` và `application/` (`python scripts/check_imports.py` pass 100%).
+- [ ] 3. **Comment tiếng Anh**: 100% các khối code sửa đổi/tạo mới đều có comment tiếng Anh giải thích logic và lý do kỹ thuật.
+- [ ] 4. **Kiểm thử tự động**: Có unit test / contract test tương ứng với tỷ lệ pass 100% trong thời gian < 1 giây.
+- [ ] 5. **Không hồi quy lỗi (No Regression)**: Toàn bộ suite test chạy xanh với lệnh `pytest tests/`.
+- [ ] 6. **Cập nhật tiến độ**: Đã ghi nhận đầy đủ thời gian `Start` và `End` vào file `Refactoring_Checklist.md`.
+- [ ] 7. **Cổng CASAN**: Lệnh `python scripts/run_quality_gate.py` chạy thành công không có bất kỳ cảnh báo vi phạm nào.

docs/refactor/GammaTeam_TaskSplit.html

@@ -0,0 +1,768 @@
+<!doctype html>
+<html lang="vi">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Phân Việc Refactor Team Gamma</title>
+</head>
+<body>
+<style>
+  :root {
+    --ground: #FAF9FC; --surface: #FFFFFF; --surface-2: #F3F0F8;
+    --ink: #191325; --muted: #665E7C; --line: #E4DEEE;
+    --accent: #6D3A9E;
+    --lead: #6D3A9E; --m1: #14707F; --m2: #A65418;
+    --warn: #A81F1A; --ok: #1B6B40;
+    --lead-wash: #F1E9F9; --m1-wash: #E2F1F3; --m2-wash: #F8EDE2;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --ground: #121020; --surface: #1B1830; --surface-2: #241F3D;
+      --ink: #EFEBF7; --muted: #A69EBD; --line: #2F2848;
+      --accent: #C08CF0;
+      --lead: #C08CF0; --m1: #56C6D8; --m2: #E29A56;
+      --warn: #F08A84; --ok: #6FD69C;
+      --lead-wash: #2A1F42; --m1-wash: #133038; --m2-wash: #38270F;
+    }
+  }
+  :root[data-theme="dark"] {
+    --ground: #121020; --surface: #1B1830; --surface-2: #241F3D;
+    --ink: #EFEBF7; --muted: #A69EBD; --line: #2F2848;
+    --accent: #C08CF0;
+    --lead: #C08CF0; --m1: #56C6D8; --m2: #E29A56;
+    --warn: #F08A84; --ok: #6FD69C;
+    --lead-wash: #2A1F42; --m1-wash: #133038; --m2-wash: #38270F;
+  }
+
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--ground); color: var(--ink);
+    font-family: "Segoe UI", -apple-system, system-ui, "Helvetica Neue", sans-serif;
+    font-size: 15px; line-height: 1.62; -webkit-font-smoothing: antialiased;
+  }
+  .wrap { max-width: 1120px; margin: 0 auto; padding: 0 28px 96px; }
+  code, .mono, td.day, th.day, .num {
+    font-family: Consolas, "Cascadia Mono", "SF Mono", ui-monospace, monospace;
+    font-variant-numeric: tabular-nums;
+  }
+
+  header.top { border-bottom: 2px solid var(--ink); padding: 56px 0 22px; margin-bottom: 34px; }
+  .eyebrow { font-size: 12px; letter-spacing: .16em; text-transform: uppercase;
+    color: var(--accent); font-weight: 700; margin: 0 0 14px; }
+  h1 { font-size: clamp(30px, 4.4vw, 44px); line-height: 1.1; margin: 0 0 16px;
+    font-weight: 700; letter-spacing: -.02em; text-wrap: balance; }
+  .lede { font-size: 17px; color: var(--muted); margin: 0; max-width: 64ch; }
+  .alias { margin: 18px 0 0; padding: 12px 16px; max-width: 74ch;
+    background: var(--surface-2); border-left: 3px solid var(--accent);
+    border-radius: 3px; font-size: 14px; color: var(--muted); }
+  .alias b { color: var(--ink); }
+  .facts { display: flex; flex-wrap: wrap; gap: 28px; margin-top: 26px;
+    padding-top: 20px; border-top: 1px solid var(--line); }
+  .fact .k { font-size: 11px; letter-spacing: .13em; text-transform: uppercase;
+    color: var(--muted); display: block; margin-bottom: 3px; }
+  .fact .v { font-size: 15px; font-weight: 600; }
+
+  h2 { font-size: 23px; margin: 52px 0 6px; letter-spacing: -.01em; font-weight: 700; text-wrap: balance; }
+  h2 + .sub { color: var(--muted); margin: 0 0 22px; max-width: 70ch; }
+  h3 { font-size: 17px; margin: 30px 0 10px; font-weight: 700; }
+
+  /* gate = việc phải xong trước khi chia nhánh */
+  .gatebox { background: var(--surface); border: 1px solid var(--line);
+    border-left: 4px solid var(--warn); border-radius: 3px; padding: 4px 26px 22px; }
+  .gatebox h2 { margin-top: 22px; }
+
+  .steps { list-style: none; counter-reset: s; padding: 0; margin: 0; }
+  .steps > li { counter-increment: s; position: relative; padding: 14px 0 14px 46px;
+    border-bottom: 1px solid var(--line); }
+  .steps > li:last-child { border-bottom: none; }
+  .steps > li::before {
+    content: counter(s); position: absolute; left: 0; top: 14px;
+    width: 26px; height: 26px; border-radius: 50%; background: var(--accent);
+    color: #fff; font-size: 13px; font-weight: 700; display: flex;
+    align-items: center; justify-content: center;
+    font-family: Consolas, ui-monospace, monospace;
+  }
+  .steps b { display: block; margin-bottom: 2px; }
+  .steps small { color: var(--muted); font-size: 13.5px; display: block; }
+  .est { float: right; font-size: 12px; color: var(--muted); font-weight: 600;
+    font-family: Consolas, ui-monospace, monospace; }
+
+  .cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 18px; }
+  @media (max-width: 940px) { .cards { grid-template-columns: 1fr; } }
+  .card { background: var(--surface); border: 1px solid var(--line);
+    border-top: 3px solid var(--c); border-radius: 3px; padding: 20px;
+    display: flex; flex-direction: column; }
+  .card.lead { --c: var(--lead); --w: var(--lead-wash); }
+  .card.one  { --c: var(--m1);   --w: var(--m1-wash); }
+  .card.two  { --c: var(--m2);   --w: var(--m2-wash); }
+  .card .tag { font-size: 11px; letter-spacing: .13em; text-transform: uppercase;
+    font-weight: 700; color: var(--c); margin-bottom: 6px; }
+  .card h3 { margin: 0 0 4px; font-size: 18px; }
+  .card .who { font-size: 13px; color: var(--muted); margin-bottom: 14px; }
+  .card .branch { font-size: 12.5px; background: var(--w); color: var(--c);
+    padding: 5px 9px; border-radius: 3px; display: inline-block;
+    margin-bottom: 16px; word-break: break-all; font-weight: 600; }
+  .card h4 { font-size: 11px; letter-spacing: .12em; text-transform: uppercase;
+    color: var(--muted); margin: 16px 0 7px; font-weight: 700; }
+  .card ul { margin: 0; padding-left: 17px; font-size: 14px; }
+  .card li { margin-bottom: 6px; }
+  .tid { font-size: 12px; font-weight: 700; color: var(--c);
+    font-family: Consolas, ui-monospace, monospace; }
+  .paths { list-style: none; padding: 0; margin: 0; font-size: 12.5px; }
+  .paths li { padding: 3px 0; border-bottom: 1px dotted var(--line);
+    font-family: Consolas, ui-monospace, monospace; color: var(--muted); word-break: break-all; }
+  .paths li:last-child { border-bottom: none; }
+  .weight { margin-top: auto; padding-top: 16px; font-size: 12.5px; color: var(--muted); }
+  .weight b { color: var(--ink); font-size: 15px; }
+
+  .scroll { overflow-x: auto; border: 1px solid var(--line); border-radius: 3px; }
+  table { border-collapse: collapse; width: 100%; font-size: 13.5px; background: var(--surface); }
+  th, td { text-align: left; padding: 11px 14px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  thead th { background: var(--surface-2); font-size: 11px; letter-spacing: .1em;
+    text-transform: uppercase; color: var(--muted); font-weight: 700; white-space: nowrap; }
+  tbody tr:last-child td { border-bottom: none; }
+  td.day, th.day { white-space: nowrap; font-weight: 700; font-size: 13px; }
+  td.cl { border-left: 3px solid var(--lead); }
+  td.c1 { border-left: 3px solid var(--m1); }
+  td.c2 { border-left: 3px solid var(--m2); }
+  tr.mark td { background: var(--surface-2); font-weight: 600; }
+  td small { color: var(--muted); display: block; font-size: 12.5px; }
+  .pill { display: inline-block; font-size: 11px; font-weight: 700; padding: 2px 7px;
+    border-radius: 2px; letter-spacing: .04em; white-space: nowrap; }
+  .pill.cp { background: var(--m1-wash); color: var(--m1); }
+  .pill.gate { background: var(--m2-wash); color: var(--m2); }
+  .pill.ship { background: var(--lead-wash); color: var(--lead); }
+
+  .rules { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; }
+  @media (max-width: 760px) { .rules { grid-template-columns: 1fr; } }
+  .rule { background: var(--surface); border: 1px solid var(--line);
+    border-radius: 3px; padding: 18px 20px; border-left: 3px solid var(--c, var(--line)); }
+  .rule.hard { --c: var(--warn); }
+  .rule.soft { --c: var(--ok); }
+  .rule h3 { margin: 0 0 8px; font-size: 15px; }
+  .rule p { margin: 0; font-size: 14px; color: var(--muted); }
+  .rule code { color: var(--ink); }
+
+
+  /* tóm tắt: đọc 30 giây là nắm được, trước khi vào chi tiết */
+  .tldr {
+    display: grid; grid-template-columns: 1.35fr 1fr; gap: 0;
+    border: 1px solid var(--line); border-radius: 3px; overflow: hidden;
+    margin-bottom: 8px; background: var(--surface);
+  }
+  @media (max-width: 820px) { .tldr { grid-template-columns: 1fr; } }
+  .tldr > div { padding: 20px 24px; }
+  .tldr .right { background: var(--surface-2); border-left: 1px solid var(--line); }
+  @media (max-width: 820px) { .tldr .right { border-left: none; border-top: 1px solid var(--line); } }
+  .tldr .cap {
+    font-size: 11px; letter-spacing: .14em; text-transform: uppercase;
+    color: var(--muted); font-weight: 700; margin: 0 0 12px;
+  }
+  .flow { list-style: none; padding: 0; margin: 0; font-size: 14px; }
+  .flow li { padding: 7px 0; border-bottom: 1px dotted var(--line); display: flex; gap: 10px; }
+  .flow li:last-child { border-bottom: none; }
+  .flow .b {
+    flex: 0 0 auto; font-size: 11.5px; font-weight: 700; padding: 1px 7px; border-radius: 2px;
+    background: var(--w2); color: var(--c2); height: fit-content; margin-top: 2px;
+    font-family: Consolas, ui-monospace, monospace;
+  }
+  .flow li.f0 { --c2: var(--warn); --w2: var(--surface-2); }
+  .flow li.f1 { --c2: var(--lead); --w2: var(--lead-wash); }
+  .flow li.f2 { --c2: var(--m1); --w2: var(--m1-wash); }
+  .flow li.f3 { --c2: var(--m2); --w2: var(--m2-wash); }
+  .flow .t { flex: 1; }
+  .flow .t b { display: block; }
+  .flow .t small { color: var(--muted); font-size: 12.5px; }
+  .must { margin: 0; padding-left: 18px; font-size: 14px; }
+  .must li { margin-bottom: 8px; }
+  .must li:last-child { margin-bottom: 0; }
+  .must b { color: var(--ink); }
+
+  /* input / output từng người */
+  .io { display: grid; gap: 18px; }
+  .iorow { background: var(--surface); border: 1px solid var(--line);
+    border-left: 3px solid var(--c); border-radius: 3px; overflow: hidden; }
+  .iorow.n1 { --c: var(--lead); --w: var(--lead-wash); }
+  .iorow.n2 { --c: var(--m1);   --w: var(--m1-wash); }
+  .iorow.n3 { --c: var(--m2);   --w: var(--m2-wash); }
+  .iohead { padding: 14px 20px; background: var(--w); display: flex;
+    align-items: baseline; gap: 12px; flex-wrap: wrap; }
+  .iohead b { color: var(--c); font-size: 15px; }
+  .iohead span { color: var(--muted); font-size: 13px; }
+  .iogrid { display: grid; grid-template-columns: 1fr 1fr; }
+  @media (max-width: 860px) { .iogrid { grid-template-columns: 1fr; } }
+  .iogrid > div { padding: 16px 20px; }
+  .iogrid > div + div { border-left: 1px solid var(--line); }
+  @media (max-width: 860px) {
+    .iogrid > div + div { border-left: none; border-top: 1px solid var(--line); }
+  }
+  .iocap { font-size: 11px; letter-spacing: .13em; text-transform: uppercase;
+    color: var(--muted); font-weight: 700; margin: 0 0 10px; }
+  .iolist { list-style: none; margin: 0; padding: 0; font-size: 13.5px; }
+  .iolist li { padding: 5px 0; border-bottom: 1px dotted var(--line); }
+  .iolist li:last-child { border-bottom: none; }
+  .iolist code { font-size: 12.5px; }
+  .frm { display: inline-block; font-size: 11px; font-weight: 700; padding: 1px 6px;
+    border-radius: 2px; background: var(--surface-2); color: var(--muted);
+    margin-right: 6px; font-family: Consolas, ui-monospace, monospace; }
+  .frm.done { background: var(--m1-wash); color: var(--m1); }
+  .frm.risk { background: var(--m2-wash); color: var(--m2); }
+
+  footer { margin-top: 64px; padding-top: 20px; border-top: 1px solid var(--line);
+    font-size: 13px; color: var(--muted); }
+</style>
+
+<div class="wrap">
+
+<header class="top">
+  <p class="eyebrow">Team Gamma · Automation, Workflows &amp; Governance</p>
+  <h1>Một nhánh chung, ba làn không đụng nhau</h1>
+  <p class="lede">
+    Toàn bộ phần việc refactor 10 ngày của Team Gamma — Nam, Hiệp, Lâm. Cả ba đẩy chung vào <code>gamma/refactor</code>. Nam làm thêm một mục chung —
+    khung kiến trúc, hợp đồng dữ liệu, cổng kiểm duyệt — nằm ngoài ba nhánh; xong mục đó thì
+    ba người vào ba nhánh tính năng ngang nhau, không ai phải sửa chung file với ai.
+  </p>
+  <p class="alias">
+    Ba tài liệu refactor gọi team này là <b>“Team Nam”</b> (theo tên lead). Cùng một team, cùng
+    phạm vi R02 · R08 · R09 · R07-T06. Nhánh của team dùng tiền tố <code>gamma/</code>; ba tài liệu refactor viết
+    <code>nam/workflow-governance-*</code> theo tên lead — cùng một thứ.
+  </p>
+  <div class="facts">
+    <div class="fact"><span class="k">Thời hạn</span><span class="v mono">21/08 → 31/08</span></div>
+    <div class="fact"><span class="k">Người</span><span class="v mono">Nam · Hiệp · Lâm</span></div>
+    <div class="fact"><span class="k">Nhánh</span><span class="v mono">gamma/refactor</span></div>
+    <div class="fact"><span class="k">Code phải bóc</span><span class="v mono">~6.500 dòng</span></div>
+    <div class="fact"><span class="k">Cổng phải qua</span><span class="v mono">CASAN Check 1</span></div>
+  </div>
+</header>
+
+
+<section class="tldr">
+  <div>
+    <p class="cap">Tóm tắt · thứ tự làm</p>
+    <ul class="flow">
+      <li class="f0">
+        <span class="b">CHUNG</span>
+        <span class="t"><b>Nam làm trước, nửa ngày</b>
+        <small>Dựng khung 5 thư mục (đang là 0 file) · interface + fake cho Config/Secrets ·
+        chốt <code>api_key</code> và báo Team Duy · script CASAN Check 1 · đưa 3 check vào CI ·
+        quyết số phận 24 checker UI. Merge xong mới chia nhánh.</small></span>
+      </li>
+      <li class="f1">
+        <span class="b">N1</span>
+        <span class="t"><b>N1 — Nam · Cấu hình, Bí mật, Vỏ ứng dụng</b>
+        <small>R02 (6 task) · settings 4 widget · bootstrap + MainWindow · policy doc.
+        Giữ luôn <code>app.py</code>, <code>config.py</code>, <code>theme.py</code>,
+        <code>i18n.py</code>. ~2.700 dòng.</small></span>
+      </li>
+      <li class="f2">
+        <span class="b">N2</span>
+        <span class="t"><b>N2 — Hiệp · Giám sát</b>
+        <small>7 tab Monitoring · CanonicalAuditLogger · MonitoringQueryService ·
+        2 vòng lặp import · ma trận Sandbox. ~2.650 dòng.</small></span>
+      </li>
+      <li class="f3">
+        <span class="b">N3</span>
+        <span class="t"><b>N3 — Lâm · Co4E Studio</b>
+        <small>Co4EWorkflowService · tách <code>co4e_tab.py</code> + <code>co4e_canvas.py</code>
+        thành 5 phần. ~2.880 dòng, file to nhất team.</small></span>
+      </li>
+    </ul>
+  </div>
+  <div class="right">
+    <p class="cap">Ba điều bắt buộc</p>
+    <ol class="must">
+      <li><b>Không chạm file dùng chung.</b> Cần thêm chuỗi hay màu thì nhắn nhóm trưởng, đừng tự sửa.</li>
+      <li><b>Nộp factory, không tự lắp vào <code>app.py</code>.</b> N1 lắp trong <code>bootstrap.py</code> ngày 28/08.</li>
+      <li><b>Bị chặn thì dùng fake, báo ngay trong ngày.</b> Không ngồi đợi ai.</li>
+    </ol>
+    <p class="cap" style="margin-top:20px">Nghiệm thu</p>
+    <p style="margin:0;font-size:14px;color:var(--muted)">
+      Trên <code>gamma/refactor</code>: không file nào được sửa bởi hai người khác nhau.
+      Có là quy ước <b style="color:var(--ink)">số 1</b> đang bị vi phạm.
+    </p>
+  </div>
+</section>
+
+<section class="gatebox">
+  <h2>Mục chung — Nam làm, xong hai người kia mới bắt đầu</h2>
+  <p class="sub">
+    Sáu việc dưới đây không thuộc làn nào — chúng là thứ cả ba người cùng đụng
+    vào. Nam làm một lần và đẩy lên <code>gamma/refactor</code>, rồi hai người kia
+    mới bắt đầu. Ước tính nửa ngày.
+  </p>
+  <ol class="steps">
+    <li>
+      <span class="est">~30 phút</span>
+      <b>Dựng khung thư mục</b>
+      <small>
+        <code>domain/</code> <code>application/</code> <code>infrastructure/</code>
+        <code>presentation/</code> <code>platform/</code> <code>tests/fakes/</code> —
+        hiện tại <b>chưa tồn tại, 0 file</b>. Mọi task của cả ba người đều ghi vào đây; để ba
+        người tự tạo là đụng nhau ở <code>__init__.py</code> ngay ngày đầu.
+      </small>
+    </li>
+    <li>
+      <span class="est">~45 phút</span>
+      <b>Viết interface + fake cho Config và Secrets</b>
+      <small>
+        <code>SecretStore</code>, <code>ConfigRepository</code>, kèm
+        <code>FakeSecretStore</code> và <code>FakeConfigRepository</code>. Chỉ chữ ký, chưa cần
+        thân hàm. Đây là thứ gỡ chốt cho cả hai người kia — <b>156 lời gọi
+        <code>ctx.config.*</code> trong 29 file</b> đang chờ nó.
+      </small>
+    </li>
+    <li>
+      <span class="est">~20 phút</span>
+      <b>Chốt số phận <code>api_key</code> và báo Team Duy</b>
+      <small>
+        <code>provider_conf()</code> còn trả <code>api_key</code> bên trong, hay tách hẳn sang
+        <code>SecretStore</code>? Có 5 nơi đọc trực tiếp, <b>3 trong số đó nằm trong
+        <code>providers/</code> của Team Duy</b>. Quyết một mình rồi im lặng là làm vỡ code
+        team bạn.
+      </small>
+    </li>
+    <li>
+      <span class="est">~30 phút</span>
+      <b>Viết <code>scripts/audit_security.py</code> (CASAN Check 1)</b>
+      <small>
+        Gamma chủ trì check này ngày 30/08. Viết ngay hôm nay thì lead tự kiểm được trong suốt
+        quá trình chuyển API key, thay vì tới ngày cổng mới chạy lần đầu và phát hiện vấn đề.
+      </small>
+    </li>
+    <li>
+      <span class="est">~20 phút</span>
+      <b>Thêm 3 check CASAN vào CI</b>
+      <small>
+        CI hiện chỉ chạy <code>pytest tests -q</code>. Ba check (secret · ≤400 dòng · import
+        guard) không nằm trong CI, nên tới 30/08 mới biết ai vi phạm. Đưa vào CI thì mỗi PR tự
+        báo.
+      </small>
+    </li>
+    <li>
+      <span class="est">~30 phút</span>
+      <b>Quyết số phận 24 checker UI, rồi thông báo</b>
+      <small>
+        Chúng bám vào <code>cowork_local.config</code> (34 chỗ) và <code>cowork_local.app</code>
+        (16 chỗ) — <b>sẽ chết ngay khi lead đụng <code>config.py</code></b>. Đây là lưới an toàn
+        duy nhất cho phần UI vừa làm xong. Xem mục quy ước bên dưới.
+      </small>
+    </li>
+  </ol>
+</section>
+
+<h2>Ba làn</h2>
+<p class="sub">
+  Ba làn ngang nhau, mỗi làn khoảng 2.700 dòng phải bóc tách, <b>cùng đẩy vào một
+  nhánh</b> <code>gamma/refactor</code>. Nam nhận làn N1 vì đó là làn chạm tới file
+  dùng chung nhiều nhất. Cột “sở hữu” là danh sách file <em>chỉ</em> người đó được
+  sửa — trên nhánh chung, đây là thứ duy nhất giữ cho ba người không giẫm chân.
+</p>
+
+<div class="cards">
+
+  <div class="card lead">
+    <div class="tag">Làn N1 · Nam</div>
+    <h3>Cấu hình, Bí mật &amp; Vỏ ứng dụng</h3>
+    <p class="who">Nam giữ — làn chạm nhiều file dùng chung nhất</p>
+    <div class="branch">gamma/refactor</div>
+
+    <h4>Việc</h4>
+    <ul>
+      <li><span class="tid">R02-T01…T06</span> AtomicJsonFile · ConfigRepository · Typed Settings Facade · SecretStore + Keyring · chuyển API key · schema versioning</li>
+      <li><span class="tid">R08-T07</span> tách <code>settings_dialog.py</code> → 4 section widget</li>
+      <li><span class="tid">R08-T10</span> <code>bootstrap.py</code> + tách <code>MainWindow</code> → shell · tray · lifecycle <em>(cuối sprint, lắp factory của hai người kia)</em></li>
+      <li><span class="tid">R09-T01</span> tài liệu Security Policy Model</li>
+      <li>Chủ trì <b>CASAN Check 1</b> · giữ CI · duyệt PR của hai người</li>
+    </ul>
+
+    <h4>Sở hữu độc quyền</h4>
+    <ul class="paths">
+      <li>config.py</li>
+      <li>app.py → presentation/shell/</li>
+      <li>bootstrap.py</li>
+      <li>theme.py · i18n.py</li>
+      <li>infrastructure/config/ · secrets/ · persistence/</li>
+      <li>ui/settings_dialog.py → presentation/settings/</li>
+      <li>scripts/ · .gitea/workflows/</li>
+    </ul>
+
+    <p class="weight"><b>~2.700 dòng</b> · 727 settings + 1.352 app + 616 config<br>+ mục chung ở trên</p>
+  </div>
+
+  <div class="card one">
+    <div class="tag">Làn N2 · Hiệp</div>
+    <h3>Giám sát &amp; Quan trắc</h3>
+    <p class="who">Hiệp — 7 tab, việc lặp cần kỷ luật</p>
+    <div class="branch">gamma/refactor</div>
+
+    <h4>Việc</h4>
+    <ul>
+      <li><span class="tid">R08-T08</span> tách <code>monitoring_tab.py</code> → 7 tab độc lập</li>
+      <li><span class="tid">R09-T04</span> <code>CanonicalAuditLogger</code></li>
+      <li><span class="tid">R09-T05</span> <code>MonitoringQueryService</code> read-only, phân trang</li>
+      <li><span class="tid">R09-T02</span> gỡ vòng lặp <code>model_pricing</code> ↔ <code>usage_tracker</code></li>
+      <li><span class="tid">R09-T03</span> gỡ vòng lặp <code>agent_security</code> ↔ <code>alert</code></li>
+      <li><span class="tid">R09-T06</span> ma trận Sandbox theo hệ điều hành</li>
+    </ul>
+
+    <h4>Sở hữu độc quyền</h4>
+    <ul class="paths">
+      <li>ui/monitoring_tab.py → presentation/monitoring/</li>
+      <li>application/monitoring/</li>
+      <li>infrastructure/telemetry/ · sandbox/</li>
+      <li>core/audit_log.py</li>
+      <li>core/model_pricing.py · usage_tracker.py</li>
+      <li>core/agent_security*.py</li>
+    </ul>
+
+    <p class="weight"><b>~2.650 dòng</b> · 1.545 monitoring + ~1.100 core</p>
+  </div>
+
+  <div class="card two">
+    <div class="tag">Làn N3 · Lâm</div>
+    <h3>Co4E Studio</h3>
+    <p class="who">Lâm — canvas và luồng chạy workflow</p>
+    <div class="branch">gamma/refactor</div>
+
+    <h4>Việc</h4>
+    <ul>
+      <li><span class="tid">R07-T06</span> <code>Co4EWorkflowService</code> thuần Python</li>
+      <li><span class="tid">R08-T09</span> tách <code>co4e_tab.py</code> + <code>co4e_canvas.py</code> → canvas · node property · run control · chat view · agent list</li>
+      <li>Gọi tool qua <code>ToolPolicyGateway</code> của Team Hoa — dùng fake, không chờ</li>
+    </ul>
+
+    <h4>Sở hữu độc quyền</h4>
+    <ul class="paths">
+      <li>ui/co4e_tab.py → presentation/co4e/</li>
+      <li>ui/co4e_canvas.py</li>
+      <li>ui/co4e_config_panel.py</li>
+      <li>application/workflows/</li>
+      <li>domain/workflows/</li>
+      <li>core/co4e_run_manager.py</li>
+    </ul>
+
+    <p class="weight"><b>~2.880 dòng</b> · file to nhất của cả team</p>
+  </div>
+
+</div>
+
+<h2>Tám quy ước</h2>
+<p class="sub">
+  Tám điều dưới đây là luật của team, Nam chốt. Bốn điều đầu là bắt buộc — trên một
+  nhánh chung, vi phạm không chỉ hại mình mà chặn cả hai người kia.
+</p>
+
+<div class="rules">
+
+  <div class="rule hard">
+    <h3>1 · Không chạm file dùng chung</h3>
+    <p>
+      <code>app.py</code>, <code>theme.py</code>, <code>i18n.py</code>, <code>config.py</code>,
+      <code>bootstrap.py</code> thuộc nhánh N1 của Nam. Cần thêm chuỗi hay token màu thì
+      <b>nhắn, đừng sửa</b> — Nam thêm trong ngày. Đây là ba file duy nhất có thể gây conflict
+      thật, và luật này xoá hẳn khả năng đó.
+    </p>
+  </div>
+
+  <div class="rule hard">
+    <h3>2 · Nộp factory, không tự lắp vào app</h3>
+    <p>
+      Mỗi nhánh expose một hàm dựng widget với chữ ký chốt từ ngày đầu, ví dụ
+      <code>build_monitoring_tab(ctx, query_service) -&gt; QWidget</code>. Nam gọi nó trong <code>bootstrap.py</code> ngày 28/08. Không ai tự sửa chỗ khởi tạo trong
+      <code>app.py</code>.
+    </p>
+  </div>
+
+  <div class="rule hard">
+    <h3>3 · Bị chặn thì dùng fake, không ngồi đợi</h3>
+    <p>
+      Chưa có <code>ConfigRepository</code> bản thật thì dùng <code>FakeConfigRepository</code>.
+      Chưa có <code>ToolPolicyGateway</code> của Team Hoa thì đã có fake sẵn. <b>Báo ngay trong ngày</b>
+      nếu thiếu fake nào — đó là việc của nhóm trưởng, không phải lý do dừng tay.
+    </p>
+  </div>
+
+
+  <div class="rule hard">
+    <h3>4 · Nhánh chung: kéo trước khi đẩy, đừng để nhánh đỏ</h3>
+    <p>
+      Cả ba đẩy vào <code>gamma/refactor</code>, nên không còn nhánh riêng làm vùng
+      đệm. Ba việc bắt buộc: <code>git pull --rebase</code> trước mỗi lần đẩy;
+      commit nhỏ và đẩy trong ngày, đừng ôm 500 dòng ba hôm; và
+      <b>không bao giờ đẩy thứ làm <code>pytest tests -q</code> đỏ</b> — nhánh hỏng
+      là hai người kia đứng hình. Lỡ đẩy nhầm thì sửa ngay hoặc
+      <code>git revert</code>, đừng để qua đêm.
+    </p>
+  </div>
+
+  <div class="rule soft">
+    <h3>5 · Commit nhỏ, mỗi ngày một lần</h3>
+    <p>
+      Một PR cho một sub-widget hoặc một service, không dồn 7 tab vào một PR cuối tuần. Nhóm
+      trưởng duyệt trong ngày. PR càng to thì rủi ro càng dồn về ngày 28/08.
+    </p>
+  </div>
+
+  <div class="rule soft">
+    <h3>6 · Mỗi commit kèm test, và không làm đỏ 90 test cũ</h3>
+    <p>
+      Baseline hiện tại: <b>102 test xanh trong 3,4 giây</b>. Chạy <code>pytest tests -q</code>
+      trước mỗi lần đẩy. Đây là lưới an toàn cho phần logic — giữ nó xanh suốt 10 ngày.
+    </p>
+  </div>
+
+  <div class="rule soft">
+    <h3>7 · File mới ≤ 400 dòng, không import PySide6 vào lõi</h3>
+    <p>
+      Hai điều kiện của CASAN Check 2 và 3. Tự kiểm trước khi đẩy — CI sẽ báo, nhưng biết
+      sớm thì đỡ phải tách lại lần hai.
+    </p>
+  </div>
+
+  <div class="rule soft">
+    <h3>8 · Checker UI thuộc phạm vi ai, người đó cập nhật</h3>
+    <p>
+      24 checker sẽ vỡ khi file bị dời. Ai dời file thì sửa checker tương ứng ngay trong
+      commit đó — tốn thêm khoảng 15% thời gian, đổi lại giữ được lưới an toàn cho phần
+      UI vừa làm xong.
+      <b>Đã chốt 21/08: đường A. Nam chịu trách nhiệm nếu đổi ý.</b>
+    </p>
+  </div>
+
+</div>
+
+
+<h2>Mỗi người nhận gì, giao gì</h2>
+<p class="sub">
+  Cột trái là thứ phải có trong tay mới làm được, kèm nguồn. Cột phải là thứ bắt
+  buộc giao ra, kèm người nhận. Nhãn <span class="frm done">có rồi</span> nghĩa là
+  mục chung đã làm xong.
+</p>
+
+<div class="io">
+
+  <div class="iorow n1">
+    <div class="iohead"><b>N1 · Cấu hình, Bí mật &amp; Vỏ</b><span>Nam · nhóm trưởng</span></div>
+    <div class="iogrid">
+      <div>
+        <p class="iocap">Input — cần có</p>
+        <ul class="iolist">
+          <li><span class="frm">mã cũ</span><code>config.py</code> 616 dòng</li>
+          <li><span class="frm">mã cũ</span><code>ui/settings_dialog.py</code> 727 dòng</li>
+          <li><span class="frm">mã cũ</span><code>app.py</code> 1.352 dòng</li>
+          <li><span class="frm risk">tự chốt</span>Quyết định <code>api_key</code> — trước 26/08</li>
+          <li><span class="frm">từ Hiệp</span>Chữ ký <code>build_monitoring_tab()</code> — trước 28/08</li>
+          <li><span class="frm">từ Lâm</span>Chữ ký <code>build_co4e_tab()</code> — trước 28/08</li>
+        </ul>
+      </div>
+      <div>
+        <p class="iocap">Output — phải giao</p>
+        <ul class="iolist">
+          <li><span class="frm done">có rồi</span><code>SecretStore</code> · <code>ConfigRepository</code> + fake → <b>cho Hiệp và Lâm</b></li>
+          <li><span class="frm done">có rồi</span><code>scripts/audit_security.py</code> → cho CI</li>
+          <li><code>infrastructure/persistence/json/atomic_json_file.py</code></li>
+          <li><code>infrastructure/config/</code> — cài đặt thật + settings facade</li>
+          <li><code>infrastructure/secrets/keyring_adapter.py</code></li>
+          <li><code>presentation/settings/</code> — 4 widget</li>
+          <li><code>bootstrap.py</code> + <code>presentation/shell/</code> — 3 file</li>
+          <li><code>docs/architecture/security-policy.md</code></li>
+        </ul>
+      </div>
+    </div>
+  </div>
+
+  <div class="iorow n2">
+    <div class="iohead"><b>N2 · Giám sát</b><span>Hiệp</span></div>
+    <div class="iogrid">
+      <div>
+        <p class="iocap">Input — cần có</p>
+        <ul class="iolist">
+          <li><span class="frm">mã cũ</span><code>ui/monitoring_tab.py</code> 1.545 dòng</li>
+          <li><span class="frm">mã cũ</span><code>core/usage_tracker.py</code> 524 · <code>sandbox_manager.py</code> 335</li>
+          <li><span class="frm">mã cũ</span><code>core/model_pricing.py</code> 284 · <code>agent_security.py</code> 272 · <code>audit_log.py</code> 115</li>
+          <li><span class="frm done">từ Nam</span><code>FakeConfigRepository</code> — dùng được ngay</li>
+          <li><span class="frm risk">tự chốt</span>Giữ nguyên 9 trường log, báo Duy và Hoa</li>
+        </ul>
+      </div>
+      <div>
+        <p class="iocap">Output — phải giao</p>
+        <ul class="iolist">
+          <li><code>build_monitoring_tab()</code> → <b>cho Nam</b>, trước 28/08</li>
+          <li><code>FakeAuditLogger</code> · <code>FakeMonitoringQueryService</code> → <b>cho cả team</b></li>
+          <li><code>presentation/monitoring/</code> — 7 tab + shell</li>
+          <li><code>application/monitoring/monitoring_query_service.py</code></li>
+          <li><code>infrastructure/telemetry/audit_logger.py</code></li>
+          <li><code>infrastructure/sandbox/sandbox_capabilities.py</code></li>
+          <li><b>0 circular import</b> ở pricing ↔ usage và security ↔ alert</li>
+        </ul>
+      </div>
+    </div>
+  </div>
+
+  <div class="iorow n3">
+    <div class="iohead"><b>N3 · Co4E Studio</b><span>Lâm</span></div>
+    <div class="iogrid">
+      <div>
+        <p class="iocap">Input — cần có</p>
+        <ul class="iolist">
+          <li><span class="frm">mã cũ</span><code>ui/co4e_tab.py</code> 2.089 dòng</li>
+          <li><span class="frm">mã cũ</span><code>ui/co4e_canvas.py</code> 791 · <code>co4e_config_panel.py</code></li>
+          <li><span class="frm">mã cũ</span><code>core/co4e_run_manager.py</code> 331</li>
+          <li><span class="frm">có sẵn</span><code>core/co4e.py</code> — dataclass Workflow/Node/Edge đã có</li>
+          <li><span class="frm done">từ Nam</span><code>FakeConfigRepository</code></li>
+          <li><span class="frm risk">từ Team Hoa</span>DTO <code>ToolPolicyGateway</code> — <b>rủi ro liên team cao nhất</b>, lấy trong hôm nay</li>
+        </ul>
+      </div>
+      <div>
+        <p class="iocap">Output — phải giao</p>
+        <ul class="iolist">
+          <li><code>build_co4e_tab()</code> → <b>cho Nam</b>, trước 28/08</li>
+          <li><code>FakeCo4EWorkflowService</code> → <b>cho cả team</b></li>
+          <li><code>domain/workflows/</code> — DTO chốt ngày đầu</li>
+          <li><code>application/workflows/co4e_workflow_service.py</code></li>
+          <li><code>presentation/co4e/</code> — 5 phần</li>
+        </ul>
+      </div>
+    </div>
+  </div>
+
+</div>
+
+<h3>Output bắt buộc với cả ba, mỗi lần đẩy</h3>
+<div class="scroll">
+<table>
+  <thead><tr><th>Điều kiện</th><th>Ngưỡng</th><th>Tự kiểm bằng</th></tr></thead>
+  <tbody>
+    <tr><td>File mới sau khi tách</td><td class="mono">≤ 400 dòng</td><td class="mono">wc -l</td></tr>
+    <tr><td><code>domain/</code> và <code>application/</code> import PySide6</td><td class="mono">0</td><td class="mono">grep -r PySide6</td></tr>
+    <tr><td>Test hiện có</td><td class="mono">102 xanh</td><td class="mono">pytest tests -q</td></tr>
+    <tr><td>Credential lộ</td><td class="mono">0</td><td class="mono">python scripts/audit_security.py</td></tr>
+    <tr><td>Checker UI trong phạm vi mình dời</td><td>đã cập nhật</td><td class="mono">python tools/check_&lt;tên&gt;.py</td></tr>
+  </tbody>
+</table>
+</div>
+
+<h2>Lịch từng ngày</h2>
+<p class="sub">Ba hàng chạy độc lập. Hàng tô nền là lúc cả ba phải gặp nhau.</p>
+
+<div class="scroll">
+<table>
+  <thead>
+    <tr>
+      <th class="day">Ngày</th>
+      <th>N1 · Nam</th>
+      <th>N2 · Hiệp</th>
+      <th>N3 · Lâm</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="day">21/08<br><small>T6</small></td>
+      <td class="cl"><b>Mục chung</b> · dựng khung · interface + fake · chốt api_key · CASAN script<small>Merge trước khi hai người kia bắt đầu</small></td>
+      <td class="c1">Chốt schema log 9 trường<small>Giữ nguyên định dạng cũ để 24 chỗ gọi không phải sửa</small></td>
+      <td class="c2">Chốt chữ ký <code>Co4EWorkflowService</code><small>Nộp cho lead để lắp bootstrap sau</small></td>
+    </tr>
+    <tr>
+      <td class="day">22–23/08<br><small>T7–CN</small></td>
+      <td class="cl">AtomicJsonFile · ConfigRepository · Typed Settings Facade</td>
+      <td class="c1">CanonicalAuditLogger · gỡ vòng lặp pricing ↔ usage</td>
+      <td class="c2">Co4EWorkflowService — CRUD &amp; validate, test không cần Qt</td>
+    </tr>
+    <tr class="mark">
+      <td class="day">23/08<br><small>17:00</small></td>
+      <td colspan="3"><span class="pill cp">Checkpoint 1</span> &nbsp; 100% DTO và fake xong · <code>pytest</code> xanh · không ai bị chặn</td>
+    </tr>
+    <tr>
+      <td class="day">24/08<br><small>T2</small></td>
+      <td class="cl">Tách settings: provider + connector widget</td>
+      <td class="c1">3 tab đầu: overview · sandbox · security events</td>
+      <td class="c2">node_property_panel · agent_list_panel</td>
+    </tr>
+    <tr>
+      <td class="day">25/08<br><small>T3</small></td>
+      <td class="cl">Tách settings: routing + general widget</td>
+      <td class="c1">4 tab còn lại: MCP · action logs · agent status · security settings</td>
+      <td class="c2">co4e_canvas_widget — thao tác node</td>
+    </tr>
+    <tr>
+      <td class="day">26/08<br><small>T4</small></td>
+      <td class="cl">Chuyển API key sang SecretStore<small>Báo Team Duy trước khi đụng providers/</small></td>
+      <td class="c1">Lắp shell MonitoringTab · query service bản thật</td>
+      <td class="c2">Run control · chat view</td>
+    </tr>
+    <tr>
+      <td class="day">27/08<br><small>T5</small></td>
+      <td class="cl">Schema versioning · recovery policy</td>
+      <td class="c1">Ma trận Sandbox · gỡ vòng lặp agent_security</td>
+      <td class="c2">Lắp container Co4ETab · thay fake bằng service thật</td>
+    </tr>
+    <tr>
+      <td class="day">28/08<br><small>T6</small></td>
+      <td class="cl"><b>bootstrap.py + tách MainWindow</b><small>Nhận factory của Hiệp và Lâm để lắp</small></td>
+      <td class="c1">Nộp factory · dọn file &gt;400 dòng · cập nhật checker</td>
+      <td class="c2">Nộp factory · dọn file &gt;400 dòng · cập nhật checker</td>
+    </tr>
+    <tr class="mark">
+      <td class="day">28/08<br><small>17:00</small></td>
+      <td colspan="3"><span class="pill cp">Checkpoint 2</span> &nbsp; Tách xong 100% god file · 0 circular import</td>
+    </tr>
+    <tr>
+      <td class="day">29/08<br><small>T7</small></td>
+      <td class="cl">Tài liệu Security Policy · integration test Settings</td>
+      <td class="c1">Integration test Monitoring</td>
+      <td class="c2">Integration test luồng Co4E đầu-cuối</td>
+    </tr>
+    <tr class="mark">
+      <td class="day">30/08<br><small>CN 17:00</small></td>
+      <td colspan="3"><span class="pill gate">CASAN Gate</span> &nbsp; <b>Nam chủ trì Check 1</b> — quét toàn bộ config/JSON, phải ra 0 secret plaintext. Hiệp và Lâm sửa ngay phần của mình nếu script bắt được.</td>
+    </tr>
+    <tr class="mark">
+      <td class="day">31/08<br><small>T2 15:00</small></td>
+      <td colspan="3"><span class="pill ship">Bàn giao</span> &nbsp; Fix tồn đọng · cập nhật tài liệu kiến trúc · merge PR cuối · smoke test 5 luồng chính</td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+<h2>Nghiệm thu: làm sao biết đã thật sự song song</h2>
+<p class="sub">Không phải “đã họp xong” mà là chạy được. Ba câu hỏi, trả lời bằng lệnh.</p>
+
+<div class="scroll">
+<table>
+  <thead>
+    <tr><th>Câu hỏi</th><th>Cách trả lời</th><th>Khi nào</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Hiệp có chạy được khi chưa có config bản thật?</td>
+      <td>Dựng một tab Monitoring, chạy test của nó, <b>không import <code>cowork_local.config</code></b> dòng nào — chỉ dùng <code>FakeConfigRepository</code></td>
+      <td class="mono">21/08</td>
+    </tr>
+    <tr>
+      <td>Lâm có chạy được khi Team Hoa chưa xong gateway?</td>
+      <td>Test <code>Co4EWorkflowService</code> xanh với <code>FakeToolPolicyGateway</code></td>
+      <td class="mono">23/08</td>
+    </tr>
+    <tr>
+      <td>Ba người có đụng file nhau không?</td>
+      <td><code>git log --name-only --pretty=%an</code> trên <code>gamma/refactor</code> —
+      không file nào được xuất hiện dưới hai tên khác nhau</td>
+      <td class="mono">mỗi ngày</td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+<footer>
+  Nguồn: <code>docs/refactor/plan.md</code>, <code>Refactoring_Checklist.md</code>,
+  <code>Feature_Architecture_Proposal.md</code>. Số dòng code, số lời gọi và baseline test đo
+  trực tiếp trên nhánh <code>main</code> ngày 21/08.
+  Mục chung, cách chia ba nhánh, bảy quy ước và mục nghiệm thu là đề xuất — không có trong
+  tài liệu gốc.
+</footer>
+
+</div>
+
+</body>
+</html>

docs/refactor/GammaTeam_decisions.md

@@ -0,0 +1,189 @@
+# Quyết định của Team Gamma
+
+Team: **Nam** (nhóm trưởng, nhánh N1) · **Hiệp** (N2) · **Lâm** (N3).
+
+Ghi ở đây thay vì chôn trong comment, vì cả ba đều ảnh hưởng ra ngoài phạm vi
+một người.
+
+| # | Việc | Trạng thái |
+|---|---|---|
+| 1 | `provider_conf()` còn trả `api_key` | **Chốt 21/08 — đường A** |
+| 2 | Số phận 24 checker UI | **Chốt 21/08 — đường A** |
+| 3 | DTO `ToolPolicyGateway` viết hộ Team Hoa | Đã làm, chờ Hoa xác nhận |
+
+---
+
+## Quyết định 1 — `provider_conf()` còn trả `api_key` hay không
+
+### Vì sao phải quyết trước khi code
+
+R02-T05 chuyển API key sang Keyring. Câu hỏi là sau khi chuyển, dict do
+`provider_conf()` trả về **còn chứa `api_key` không**.
+
+Có 5 nơi đang đọc trực tiếp — đo trên `main` ngày 21/08:
+
+| Nơi đọc | Thuộc |
+|---|---|
+| `providers/anthropic.py:26` | **Team Duy** |
+| `providers/openai_compat.py:36` | **Team Duy** |
+| `core/image_gen.py:50` | Team Duy (routing/model) |
+| `core/ext_connectors.py:98` | Team Hoa |
+| `ui/ext_connector_dialog.py:87` | Team Gamma |
+
+Ba trong năm nằm ngoài team. Quyết một mình rồi im lặng là làm vỡ code người khác.
+
+### Hai đường
+
+**A. Giữ `api_key` trong dict, `ConfigRepository` tự lấy từ `SecretStore` rồi ghép vào**
+
+- 5 nơi đọc **không phải sửa dòng nào**
+- Không cần báo team khác, không cần đồng bộ lịch
+- Đổi lại: bí mật vẫn đi lang thang trong dict, dễ lọt vào log hoặc màn hình debug
+- CASAN Check 1 vẫn PASS vì nó quét **file trên đĩa**, không quét bộ nhớ
+
+**B. Bỏ `api_key` khỏi dict, ai cần thì gọi `secrets.get(provider_key(name))`**
+
+- Sạch về nguyên tắc: bí mật chỉ xuất hiện đúng chỗ cần
+- Đổi lại: **5 nơi phải sửa**, 3 trong đó phải chờ team khác xếp lịch
+- Rủi ro: quên một chỗ thì mất API key lúc chạy thật, mà test có fake nên không bắt được
+
+### Đề xuất
+
+**Đường A cho sprint này, đường B ghi vào nợ kỹ thuật.**
+
+Lý do: mục tiêu của cổng CASAN là *không còn secret nằm trên đĩa*, và đường A
+đạt được điều đó. Đường B giải quyết thêm chuyện secret trong bộ nhớ — đúng
+nhưng không phải việc của 10 ngày này, và nó kéo hai team khác vào một thay đổi
+họ không lên kế hoạch.
+
+Nếu chọn B thì **phải báo Team Duy và Team Hoa trong hôm nay**, không phải lúc
+đã sửa xong.
+
+> **Nam chốt 21/08: đường A.**
+>
+> Việc kèm theo: `ConfigRepository` bản thật phải đọc key từ `SecretStore` rồi
+> ghép vào dict do `provider_conf()` trả về. Năm nơi đọc không đổi một dòng,
+> nên **không cần báo Duy và Hoa**.
+>
+> Nợ kỹ thuật đã ghi: đường B (bỏ `api_key` khỏi dict) để sau sprint này.
+
+---
+
+## Quyết định 2 — số phận 24 checker UI
+
+### Vấn đề
+
+`tools/check_*.py` là bộ kiểm tra giao diện viết trong 2 tuần vừa rồi, hiện
+**24 file**. Chúng bám vào đường dẫn cũ:
+
+| Import | Số chỗ |
+|---|---|
+| `cowork_local.config` | 34 |
+| `cowork_local.app` | 16 |
+| `cowork_local.state` | 22 |
+| `cowork_local.ui.*` | ~12 |
+
+R08 dời hết những module đó sang `presentation/`. Nghĩa là **cả 24 checker chết
+ngay ngày N1 đụng `config.py`** — và đó là lưới an toàn duy nhất cho phần giao
+diện, vì `pytest` không kiểm giao diện (90 test hiện tại là logic).
+
+### Ba đường
+
+**A. Ai dời file thì cập nhật checker tương ứng, ngay trong PR đó**
+
+- Giữ được lưới suốt 10 ngày
+- Tốn thêm ~15% thời gian mỗi PR
+- Rủi ro: người sửa vội có thể nới lỏng phép kiểm cho nó xanh — đã xảy ra một
+  lần trong quá trình làm UI, khi một checker được sửa thành *không thể đỏ*
+
+**B. Đóng băng: bỏ khỏi CI, sửa một lượt ngày 31/08**
+
+- Nhanh nhất trong 10 ngày
+- Đổi lại: **không có gì canh hồi quy giao diện** suốt cả sprint. Refactor là lúc
+  dễ vỡ giao diện nhất
+- Rủi ro cuối sprint: sửa 24 file cùng lúc, không ai nhớ cái nào đo gì
+
+**C. Bỏ hẳn**
+
+Không khuyến nghị. Vứt đi hai tuần công sức kiểm chứng, và ba tài liệu refactor
+không có gì thay thế cho phần giao diện.
+
+### Đề xuất
+
+**Đường A**, kèm một ràng buộc: PR nào *sửa* checker phải nói rõ trong mô tả
+**sửa gì và vì sao** — để việc nới lỏng phép kiểm không lọt qua review.
+
+`tools/check_probes_bite.py` đã có sẵn cơ chế chứng minh checker còn cắn được;
+chạy nó sau mỗi đợt sửa là bắt được ngay chuyện đó.
+
+> **Chốt 21/08: đường A** — ai dời file thì cập nhật checker tương ứng ngay
+> trong PR đó.
+>
+> Kèm hai ràng buộc, vì rủi ro của đường A là người sửa vội nới lỏng phép kiểm:
+>
+> 1. PR nào *sửa* checker phải nói rõ trong mô tả **sửa gì và vì sao**.
+> 2. Sửa xong chạy `python tools/check_probes_bite.py` — nó cắm lỗi cố ý vào
+>    code rồi kiểm checker có bắt được không. Chính công cụ này đã từng bắt
+>    được một checker bị sửa thành *không thể đỏ*.
+>
+> Không đưa 24 checker vào CI trong sprint này: chúng dựng `MainWindow` thật,
+> mỗi lần chạy tốn hàng chục giây và thỉnh thoảng sập lúc Qt dọn dẹp. Chạy tay
+> theo phạm vi mình đụng là đủ.
+
+---
+
+## Quyết định 3 — Gamma viết hộ DTO `ToolPolicyGateway` cho Team Hoa
+
+**Đã làm, chờ Hoa xác nhận.** Ngày: 21/08.
+
+### Vì sao làm thay
+
+N3 (Co4E) cần gọi tool nhưng Team Hoa chưa bắt đầu. Ba đường:
+
+| | Hệ quả |
+|---|---|
+| N3 ngồi đợi Hoa | Mất mấy ngày, trái nguyên tắc "không team nào chặn team nào" |
+| N3 tự phỏng đoán | Phỏng đoán của một người, không ai soi, sửa lại chắc chắn |
+| **Gamma viết bản đề xuất** | N3 chạy ngay, Hoa có cái cụ thể để duyệt hoặc sửa |
+
+### Ranh giới không lấn
+
+Sơ đồ phân hệ trong `plan.md` giao `domain/security/` cho **Team Gamma**, còn
+`application/conversations/tool_policy_gateway.py` cho **Team Hoa**.
+
+Nên chia đúng như vậy:
+
+- **Gamma định nghĩa hình dạng** → `domain/security/tool_policy.py`
+- **Hoa cài đặt gateway** → `application/conversations/tool_policy_gateway.py`,
+  nối vào `core/mcp_client.py` và tool dựng sẵn
+
+Không đụng file nào của Hoa.
+
+### Đã bám vào code đang chạy, không bịa
+
+| Nguồn | Lấy gì |
+|---|---|
+| `core/agent_security.py::SecurityVerdict` | `allowed` · `reason` · `layer` |
+| `ui/permission_dialog.py` + `chat_panel.py:1312` | trạng thái "hỏi người dùng" |
+
+Khác biệt duy nhất: gộp thành **một câu trả lời ba trạng thái**
+(`ALLOW` / `DENY` / `ASK`) thay vì bắt chỗ gọi tự nhớ hỏi hai nơi.
+
+Hai ràng buộc đưa vào có chủ đích:
+
+1. `DENY` và `ASK` **bắt buộc có `reason`** — người dùng cần biết vì sao, và
+   `audit_log` cần ghi lại. Thiếu là ném lỗi ngay lúc dựng, không phải lúc chạy.
+2. `ASK` **không phải** `allowed` — bẫy dễ mắc nhất là coi ASK như ALLOW rồi tool
+   chạy mà chưa ai đồng ý. Có test riêng cho chuyện này.
+
+### Gửi Hoa cái gì
+
+> Bên mình viết trước bản đề xuất `ToolPolicyGateway` ở
+> `domain/security/tool_policy.py` vì N3 cần gọi tool mà bên Hoa chưa bắt đầu —
+> để N3 khỏi phải tự đoán. Ba kiểu: `ToolCallRequest`, `PolicyDecision`,
+> `ToolPolicyGateway`. Phần cài đặt vẫn để bên Hoa ở
+> `application/conversations/tool_policy_gateway.py`, bọn mình không đụng.
+> Thấy chỗ nào không hợp thì sửa thẳng file đó, đừng tạo kiểu thứ hai. Đổi bây
+> giờ còn rẻ vì mới mình N3 dùng.
+
+> Đã gửi Hoa: ☐ — ngày ____   Hoa xác nhận: ☐ đồng ý ☐ có sửa

docs/refactor/Refactoring_Checklist.md

@@ -0,0 +1,376 @@
+# COWORK LOCAL - BẢNG CHECKLIST TIẾN ĐỘ TÁI CẤU TRÚC (2026)
+## (REFACTORING & MIGRATION PROGRESS TRACKER)
+
+* **Dự án**: Cowork Local (Cowork-Local BamBOO)
+* **Thời gian thực hiện**: 21/08/2026 ➔ 31/08/2026
+* **Đội ngũ phụ trách**: 
+  - 🔵 **Team Duy** (Core AI, Routing, Turn Runtime & Testing Pyramid - Tech Lead)
+  - 🟣 **Team Nam** (Automation Workflows, Co4E, Monitoring & Shell Governance)
+  - 🟢 **Team Hoa** (Workspace, Filesystem, Scheduling & Tool Registry)
+* **Tài liệu thiết kế kiến trúc gốc**: `Feature_Architecture_Proposal.md`
+
+> [!IMPORTANT]
+> ### 📝 QUY ĐỊNH BẮT BUỘC KHI CODE & GHI NHẬN TIẾN ĐỘ (MANDATORY RULES):
+> 1. **In-Code Comments in English (Bắt buộc comment tiếng Anh ở mọi dòng/khối code sửa đổi)**:
+>    - Mỗi khi sửa đổi hoặc viết mới bất kỳ dòng code nào, lập trình viên **bắt buộc phải thêm comment bằng tiếng Anh** giải thích rõ mục đích xử lý, lý do kiến trúc và mối quan hệ giữa các tầng.
+>    - Tuyệt đối không để code không có chú thích, đặc biệt tại các điểm chuyển đổi DTO, seams và xử lý ngoại lệ.
+> 2. **Task Start / End Timestamps (Ghi nhận chính xác ngày giờ bắt đầu và hoàn tất)**:
+>    - Khi bắt đầu làm một task ➔ Điền mốc thời gian: `Start: YYYY-MM-DD HH:mm`.
+>    - Khi task hoàn tất (unit test pass 100%) ➔ Điền mốc thời gian: `End: YYYY-MM-DD HH:mm` và tích chọn `[x]`.
+
+---
+
+## 📌 PHẦN 1: CHECKLIST CHI TIẾT THEO 10 EPIC (R01 ➔ R10)
+
+### 🔹 EPIC R01: Architecture Foundation & Characterization (Nền Tảng Kiến Trúc & Test Bảo Vệ)
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì ADR & Test Doubles) + Phối hợp cả 3 team
+* **Mục tiêu**: Khóa DTO, dựng fakes/test doubles chạy offline không phụ thuộc Qt/mạng, thiết lập script chặn vi phạm kiến trúc.
+
+- [x] **R01-T01 (Team Duy)**: Viết Architecture ADR định rõ ranh giới các tầng ➔ `docs/architecture/ADR-001-layered-architecture.md`  
+  *Start: `2026-08-21 18:23` | End: `2026-08-21 18:24`*
+- [x] **R01-T02 (Team Duy)**: Xây dựng `FakeProvider` và `FakeToolExecutor` chạy offline từ `providers/base.py` ➔ `tests/fakes/fake_provider.py` & `tests/fakes/fake_tool_executor.py`  
+  *Start: `2026-08-21 18:24` | End: `2026-08-21 18:26`*
+- [x] **R01-T03 (Team Duy)**: Viết script quét tĩnh chặn code mới trong `domain/` và `application/` import `PySide6` ➔ `scripts/check_imports.py`  
+  *Start: `2026-08-21 18:26` | End: `2026-08-21 18:28`*
+- [x] **R01-T04 (Team Duy)**: Viết Characterization Tests cho `core/chat_agent.py::run_cowork` ➔ `tests/characterization/test_run_cowork.py`  
+  *Start: `2026-08-21 18:28` | End: `2026-08-21 18:32`*
+- [x] **R01-T05 (Team Duy)**: Lập danh mục và phân loại mã nguồn dormant/dead code ➔ `docs/architecture/dormant-code.md`  
+  *Start: `2026-08-21 18:32` | End: `2026-08-21 18:35`*
+
+---
+
+### 🔹 EPIC R02: Configuration, Secrets & Persistence (Cấu Hình Atomic & Bảo Mật Keyring)
+* **Team chịu trách nhiệm**: 🟣 **Team Nam** (Chủ trì)
+* **Mục tiêu**: Xóa bỏ untyped global `config.py`, cài đặt `AtomicJsonFile` chống hỏng file và lưu trữ API Key/Token vào OS Keyring.
+
+- [ ] **R02-T01 (Team Nam)**: Xây dựng module `AtomicJsonFile` ghi tệp an toàn (tmp file + fsync + atomic replace) ➔ `infrastructure/persistence/json/atomic_json_file.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R02-T02 (Team Nam)**: Refactor `config.py::AppConfig` sử dụng `AtomicJsonFile` ➔ `infrastructure/config/config_repository.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R02-T03 (Team Nam)**: Xây dựng Typed Settings Facade (`ProviderSettings`, `RoutingSettings`) ➔ `infrastructure/config/settings_facade.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R02-T04 (Team Nam)**: Định nghĩa interface `SecretStore` và cài đặt `KeyringAdapter` ➔ `infrastructure/secrets/keyring_adapter.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R02-T05 (Team Nam)**: Di chuyển cấu hình API Key của OpenAI/Anthropic/FPT Gateway sang lưu trữ qua `SecretStore`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R02-T06 (Team Nam)**: Chuẩn hóa JSON schema versioning và recovery policy cho các file data  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R03: Model Providers & Routing (Hợp Nhất Nhà Cung Cấp & Bộ Định Tuyến Mô Hình)
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì)
+* **Mục tiêu**: Hợp nhất logic routing bị phân tán thành `RoutingApplicationService` độc lập Qt; chuẩn hóa catalog nhà cung cấp.
+
+- [x] **R03-T01 (Team Duy)**: Xây dựng bộ Contract Tests chuẩn hóa cho các Provider từ `providers/base.py` ➔ `tests/contracts/test_providers.py`  
+  *Start: `2026-08-22 18:59` | End: `2026-08-22 19:01`*
+- [x] **R03-T02 (Team Duy)**: Xây dựng `ProviderDescriptor` và `ProviderRegistry` tập trung từ `providers/factory.py` ➔ `domain/models/provider_descriptor.py` & `infrastructure/providers/provider_registry.py`  
+  *Start: `2026-08-22 18:45` | End: `2026-08-22 18:50`*
+- [x] **R03-T03 (Team Duy)**: Xây dựng `RoutingApplicationService` độc lập với Qt từ `core/routing/` ➔ `application/model_routing/routing_application_service.py`  
+  *Start: `2026-08-22 18:53` | End: `2026-08-22 18:57`*
+- [x] **R03-T04 (Team Duy)**: Di chuyển luồng gọi routing từ `ui/chat_panel.py#L638` sang `RoutingApplicationService`  
+  *Start: `2026-08-22 18:57` | End: `2026-08-22 18:58`*
+- [x] **R03-T05 (Team Duy)**: Di chuyển luồng gọi routing từ `ui/co4e_tab.py` và `ui/folder_tab.py` sang `RoutingApplicationService`  
+  *Start: `2026-08-22 18:58` | End: `2026-08-22 18:59`*
+- [x] **R03-T06 (Team Duy)**: Tách logic ghi nhận token usage ra khỏi Provider, chuyển thành `UsageEventSink` ➔ `infrastructure/telemetry/usage_sink.py`  
+  *Start: `2026-08-22 18:50` | End: `2026-08-22 18:53`*
+
+#### 📦 KẾT QUẢ THỰC HIỆN EPIC R03 (Hoàn tất 2026-08-22 19:01 — nhánh `feature/delta-team/epic-R03`)
+
+**File sản phẩm mới (tất cả < 400 dòng, 100% comment tiếng Anh):**
+
+| Task | File | LOC | Nội dung chính |
+| :--- | :--- | :---: | :--- |
+| T02 | `domain/models/provider_descriptor.py` | 196 | `ProviderDescriptor` (frozen dataclass), `WireProtocol`, `AuthKind`; giá/context để `None` khi chưa biết thay vì đoán bừa |
+| T02 | `infrastructure/providers/provider_registry.py` | 287 | `ProviderRegistry` thread-safe: tra cứu theo id/alias, **tra cứu động theo model ID** (`find_by_model`), dựng adapter theo wire protocol; `BUILTIN_DESCRIPTORS` cho 5 provider |
+| T03 | `application/model_routing/routing_models.py` | 158 | DTO thuần Python: `RoutingMode` (Off/Auto/Manual/**Fallback**), `RoutingRequest` (immutable snapshot), `RouteEvaluation`, `RoutingOutcome` |
+| T03 | `application/model_routing/routing_application_service.py` | 236 | `RoutingApplicationService` — 1 nơi duy nhất quyết định routing; 2 port hẹp (`RoutingDecisionPort`, `ModeResolver`) + callback confirm ⇒ 0 phụ thuộc Qt |
+| T03 | `application/model_routing/core_routing_adapter.py` | 169 | `CoreRoutingEngine` (cầu nối sang `core/routing`), `AppContextModeResolver`, `build_routing_application_service(ctx)` (cache 1 instance/ctx) |
+| T06 | `infrastructure/telemetry/usage_sink.py` | 288 | `UsageEvent` + `UsageEventSink` (Protocol) + `UsageTrackerSink` / `InMemoryUsageSink` / `CompositeUsageSink`; publish không bao giờ raise |
+
+**File hiện hữu được sửa (đều có comment tiếng Anh tại mọi khối thay đổi):**
+
+| File | Thay đổi |
+| :--- | :--- |
+| `providers/factory.py` | Bỏ bảng `_REGISTRY` nội bộ, ủy quyền cho `ProviderRegistry`; vẫn raise `ProviderError` để không vỡ call site cũ |
+| `providers/openai_compat.py`, `providers/anthropic.py` | Không còn gọi thẳng `core/usage_tracker`; chỉ **publish** `UsageEvent` qua sink (T06) |
+| `ui/chat_panel.py` (#L638), `ui/co4e_tab.py`, `ui/folder_tab.py` | Xóa 3 bản sao logic routing (~35 dòng/file) ➔ gọi chung `RoutingApplicationService` (T04, T05); widget chỉ còn dựng `RoutingRequest`, host modal confirm và render kết quả |
+| `config.py`, `state.py`, `ui/routing_toggle.py`, `i18n.py` | Mở đường cho chế độ thứ 4 **Fallback**: hằng `AppConfig.ROUTING_MODES`, validate per-workspace, thêm mục trong combo + chuỗi EN/JA/VI |
+| `core/usage_tracker.py` | Thêm `current_context()` để sink mượn/trả lại context của thread thay vì gán đè vĩnh viễn |
+| `tests/conftest.py`, `tests/routing/conftest.py` | **Sửa lỗi hạ tầng test nghiêm trọng** (xem "Ghi chú" bên dưới) |
+
+**Bộ test bổ sung (tất cả offline, không cần network/Qt):**
+
+| File | Số test | Phạm vi |
+| :--- | :---: | :--- |
+| `tests/contracts/test_providers.py` (+ `provider_stubs.py`) | 50 | Contract chạy parametrize trên **mọi** provider trong registry: signature `chat()`, canonical assistant message, tool call chuẩn hóa, đóng response, dịch tool schema, `ProviderError`, `list_models`/`test_connection`, đúng 1 `UsageEvent`/turn |
+| `tests/unit/test_routing_application_service.py` | 28 | Đủ 4 chế độ + mọi nhánh degrade (engine lỗi, resolver lỗi, dialog lỗi, thiếu callback) |
+| `tests/unit/test_provider_registry.py` | 17 | Descriptor + registry + đối chiếu catalogue với `DEFAULT_CONFIG["providers"]` |
+| `tests/unit/test_core_routing_adapter.py` | 12 | Dịch `RouteResult` ⇄ DTO, task type sai định dạng, thiếu ranking, cache service |
+| `tests/unit/test_usage_sink.py` | 13 | Fan-out, subscriber lỗi, khôi phục thread context, publish không raise |
+| `tests/integration/test_routing_unification.py` | 14 | Chạy `RoutingApplicationService` trên **engine `core/routing` thật**; 3 surface (cowork/co4e/ai_edit) cho ra cùng 1 quyết định |
+
+**Kết quả cổng kiểm duyệt (DoD 7 tiêu chí):**
+
+| # | Tiêu chí | Lệnh | Kết quả |
+| :---: | :--- | :--- | :--- |
+| 1 | LOC < 400 | `wc -l` các file mới | ✅ Lớn nhất 288 dòng (`usage_sink.py`); `openai_compat.py` 374, `anthropic.py` 332 |
+| 2 | Clean Architecture | `python scripts/check_imports.py` | ✅ `[PASS] 0 forbidden imports detected` |
+| 3 | Comment tiếng Anh | Review thủ công | ✅ 100% khối code mới/sửa có comment giải thích logic + lý do kiến trúc |
+| 4 | Có test tự động | `pytest tests/unit tests/contracts tests/integration` | ✅ 134 test mới, pass 100% |
+| 5 | No Regression | `pytest tests/` | ✅ **236 passed in ~2.0s** (nền trước R03: 102 passed) |
+| 6 | Timestamps | Bảng trên | ✅ Đã ghi Start/End cho T01–T06 |
+| 7 | CASAN Gate | `scripts/run_quality_gate.py` | ⚠️ Script **chưa tồn tại** — thuộc R10-T02 (chưa làm). Đã chạy thay bằng `check_imports.py` + `pytest tests/` |
+
+**Ghi chú kỹ thuật cần biết khi review:**
+
+1. **Đã sửa 1 lỗi hạ tầng test có thể gây kết quả sai lệch**: `tests/conftest.py` cũ đẩy thư mục **cha** của repo vào `sys.path`, nên `import cowork_local.*` (dùng bởi `tests/routing/*` và `tests/characterization/*`) trỏ sang **một checkout `cowork_local` khác** nằm cạnh thư mục làm việc — test vẫn báo xanh nhưng chạy trên mã nguồn khác. Nay conftest bind thẳng checkout hiện tại vào `sys.modules["cowork_local"]`.
+2. **Chế độ Fallback** là chế độ *chống gãy*, không phải chế độ tối ưu: giữ nguyên model người dùng chọn kể cả khi có model điểm cao hơn, chỉ chuyển khi model đó **không phục vụ được** turn (không có trong ranking / unavailable / probe fail). Engine `core/routing` không cần biết chế độ này — service map Fallback ➔ Auto khi hỏi ranking rồi tự áp luật chấp nhận riêng.
+3. **T06 hiện tại**: provider publish `UsageEvent`; khi R04 dựng xong `AgentEvent` bus thì `ConversationApplicationService` sẽ là nơi phát sự kiện, sink giữ nguyên không phải sửa.
+4. **Cần cài `mcp>=1.0.0`** (đã có trong `requirements.txt`) để `tests/test_project_context_mcp_template.py` collect được — thiếu gói này toàn bộ suite bị interrupt.
+
+---
+
+### 🔹 EPIC R04: Agent Runtime & Conversation Application Service (Vòng Đời Turn Chat & Agent Engine)
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì)
+* **Mục tiêu**: Đóng gói input turn chat thành `ConversationExecutionRequest` bất biến, điều phối vòng đời qua `ConversationApplicationService` và phát sinh sự kiện `AgentEvent` có định kiểu.
+
+- [x] **R04-T01 (Team Duy)**: Định nghĩa immutable dataclass `ConversationExecutionRequest` ➔ `domain/agents/conversation_execution_request.py`  
+  *Start: `2026-08-23 00:56` | End: `2026-08-23 01:00`*
+- [x] **R04-T02 (Team Duy)**: Chuẩn hóa các sự kiện `AgentEvent` (TextChunk, ToolCallStarted, ToolCallResult, Error) ➔ `domain/agents/agent_event.py` (+ `domain/agents/agent_event_codec.py` — shim dịch legacy dict, tách riêng để giữ LOC < 400 và để xoá gọn sau R08)  
+  *Start: `2026-08-23 01:00` | End: `2026-08-23 01:08`*
+- [x] **R04-T03 (Team Duy)**: Xây dựng `ConversationApplicationService` điều phối thực thi từ `core/chat_agent.py` ➔ `application/conversations/conversation_application_service.py` (+ `turn_runtime.py` định nghĩa 2 port/6 callable, `core_runtime_adapter.py` cầu nối sang `core/*`, `domain/agents/agent_result.py`)  
+  *Start: `2026-08-23 01:08` | End: `2026-08-23 07:10`*  
+  Chưa đổi call site nào — `run_cowork` giữ nguyên (Co4E vẫn dùng); việc chuyển call site là T04/T05. Bằng chứng tương đương: `tests/integration/test_conversation_service_parity.py` chạy cùng 1 script provider qua 2 đường và so khớp từng event/message/tool list trên 7 kịch bản.
+- [x] **R04-T04 (Team Duy)**: Di chuyển `ui/cowork_tab.py::build_job` sang sử dụng `ConversationExecutionRequest`  
+  *Start: `2026-08-23 07:10` | End: `2026-08-23 07:23`*  
+  `build_job` không còn gọi `run_cowork`: nó chụp state widget tại submit time ➔ `build_cowork_turn_request()` (mới, `application/conversations/cowork_turn_request.py`) ➔ `ConversationApplicationService`. Thêm `combine_instructions()` vào `turn_runtime.py` (project context + admin agent, T05 dùng lại) và tham số `messages=` cho `execute()` để service append vào **đúng list của widget** — `_reattach_running_turn` đọc list đó trong lúc turn đang chạy và `_finalize_turn` slice nó sau đó. Kiểm chứng: `tests/integration/test_cowork_tab_turn.py` gọi thẳng `CoworkTab.build_job` (widget stub, không cần Qt) và chạy turn thật với `FakeProvider`.  
+  ⚠️ `ui/cowork_tab.py` 416 ➔ 455 LOC — file này **vốn đã vượt 400 trước khi sửa**; phân rã thuộc EPIC R08.
+- [x] **R04-T05 (Team Duy)**: Di chuyển `core/task_executors.py` sang dùng chung `ConversationApplicationService`  
+  *Start: `2026-08-23 07:23` | End: `2026-08-23 07:31`*  
+  Nhánh `task_type == "cowork"` của `_run_agent` gọi service thay vì `run_cowork`; 5 hành vi riêng của unattended run giữ nguyên (plan reminder, `history_ready`, autosave History mỗi `assistant_done`, timeout notice, `plan_incomplete_reason`). Tách `_unattended_prompt()` dùng `combine_instructions` để thứ tự reminder → skill → persona → prompt nằm ở 1 chỗ đọc được. Lưới an toàn: `tests/integration/test_task_executor_turn.py` viết **trước** khi migrate và pass 8/8 trên code cũ, vẫn pass sau khi migrate.  
+  ⚠️ `core/task_executors.py` 476 ➔ 524 LOC — file này **vốn đã vượt 400 trước khi sửa**; phân rã thuộc EPIC R07 (`application/scheduling/`).  
+  Còn lại gọi `run_cowork`: `core/co4e_runner.py` (×2) và `ui/co4e_tab.py` — phân hệ Co4E của 🟣 Team Nam, R04 không chạm theo luật 1 file 1 team.
+
+---
+
+### 🔹 EPIC R05: Tool, MCP & Connector Policy (Quản Lý Công Cụ, MCP & Cổng Kiểm Soát Quyền)
+* **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: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R06: Workspace, Filesystem & History Isolation (Cô Lập Không Gian Làm Việc & Quản Lý Tệp)
+* **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: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R07: Scheduling & Workflow Runtime (Bộ Lập Lịch & Động Cơ Quy Trình)
+* **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Task Scheduling) + 🟣 **Team Nam** (Co4E Workflows)
+* **Mục tiêu**: Tách `TaskRepository` và `ScheduleCalculator` khỏi `QTimer` trong `core/task_scheduler.py#L20`; xây dựng `TaskApplicationService` và `Co4EWorkflowService`.
+
+- [ ] **R07-T01 (Team Hoa)**: Tách `TaskRepository` lưu trữ JSON độc lập khỏi `core/tasks.py` ➔ `infrastructure/persistence/json/task_repository_impl.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R07-T02 (Team Hoa)**: Xây dựng `ScheduleCalculator` tính due-time / cron độc lập ➔ `domain/tasks/schedule_calculator.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R07-T03 (Team Hoa)**: Xây dựng `QtSchedulerClock` adapter (tách `TaskScheduler` khỏi `QTimer`) ➔ `platform/qt/qt_scheduler_clock.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R07-T04 (Team Hoa)**: Xây dựng `TaskApplicationService` (Pure Python) điều phối chạy, sao chép, dừng, xóa task ➔ `application/scheduling/task_application_service.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R07-T05 (Team Hoa)**: Xây dựng `AiTaskPlannerService` hỗ trợ tạo / import task bằng AI ➔ `application/scheduling/ai_task_planner_service.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R07-T06 (Team Nam)**: Xây dựng `Co4EWorkflowService` (Pure Python) quản lý định nghĩa và thực thi Co4E từ `core/co4e_run_manager.py` ➔ `application/workflows/co4e_workflow_service.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R08: UI/Application Separation (Phân Rã Toàn Diện Các God Widgets)
+* **Team chịu trách nhiệm**: **Cả 3 Team** (Mỗi team phụ trách phân hệ của mình)
+* **Mục tiêu**: Phân rã các file giao diện khổng lồ (>1.500 dòng) thành các widget chuyên biệt, mỗi file < 400 dòng code.
+
+#### 🔵 Team Duy (Chat UI Hub):
+- [ ] **R08-T01**: Tách `ui/chat_panel.py` thành `presentation/chat/chat_history_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T02**: Tách Composer & input box ➔ `presentation/chat/composer_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T03**: Tách Picker file đính kèm ➔ `presentation/chat/attachment_picker.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T04**: Tách Voice/Audio recording ➔ `presentation/chat/audio_recorder_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T05**: Tách Output panel & file watcher ➔ `presentation/chat/chat_output_panel.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T06**: Lắp ráp container `presentation/chat/chat_panel.py` và tối ưu `Floating HelpAgent`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+#### 🟣 Team Nam (Settings, Monitoring, Co4E & Shell):
+- [ ] **R08-T07**: Tách `ui/settings_dialog.py` thành 4 section widgets ➔ `provider_settings_widget.py`, `connector_settings_widget.py`, `routing_settings_widget.py`, `general_settings_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T08**: Tách `ui/monitoring_tab.py` thành 7 tab độc lập (`overview_tab.py`, `sandbox_status_tab.py`, `security_events_tab.py`, `mcp_history_tab.py`, `action_logs_tab.py`, `agent_status_tab.py`, `security_settings_tab.py`)  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T09**: Tách `ui/co4e_tab.py` thành các sub-components ➔ `co4e_canvas_widget.py`, `node_property_panel.py`, `co4e_run_control_widget.py`, `co4e_chat_view.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T10**: Xây dựng `bootstrap.py` (Composition Root) và tách `app.py::MainWindow` (dòng 122) ➔ `presentation/shell/main_window.py`, `tray_manager.py`, `lifecycle_coordinator.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+#### 🟢 Team Hoa (Workspace, Folder, Scheduling, Dashboard & Graph):
+- [ ] **R08-T11**: Tách `ui/schedule_task_tab.py` ➔ `kanban_board_widget.py`, `calendar_view_widget.py`, `ai_task_creator_dialog.py`, `ai_task_import_dialog.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T12**: Tách `ui/folder_tab.py#L350` ➔ `workspace_file_tree.py`, `document_preview_manager.py`, `ai_file_editor_dialog.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T13**: Tách `ui/dashboard_tab.py` ➔ `token_usage_card_widget.py`, `usage_chart_widget.py`, `habits_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R08-T14**: Tách `ui/structure_graph_view.py` ➔ `presentation/graph/structure_graph_view.py` & `graph_qa_widget.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R09: Security Runtime, Sandbox & Observability (An Ninh Runtime, Sandbox & Giám Sát)
+* **Team chịu trách nhiệm**: 🟣 **Team Nam** (Chủ trì) + Phối hợp Team Duy
+* **Mục tiêu**: Phân biệt deterministic rules và AI guardrails, fix toàn bộ circular imports trong security/pricing, chuẩn hóa schema audit logs.
+
+- [ ] **R09-T01 (Team Nam)**: Viết tài liệu chuẩn hóa Security Policy Model ➔ `docs/architecture/security-policy.md`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R09-T02 (Team Nam)**: Xử lý triệt để Circular Import giữa `core/model_pricing.py` và `core/usage_tracker.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R09-T03 (Team Nam)**: Xử lý triệt để Circular Import giữa `core/agent_security.py` và `core/agent_security_alert.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R09-T04 (Team Nam)**: Xây dựng `CanonicalAuditLogger` thống nhất định dạng log từ `core/audit_log.py` ➔ `infrastructure/telemetry/audit_logger.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R09-T05 (Team Nam)**: Xây dựng `MonitoringQueryService` (truy vấn read-only có phân trang) ➔ `application/monitoring/monitoring_query_service.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R09-T06 (Team Nam)**: Chuẩn hóa ma trận năng lực Sandbox trên từng hệ điều hành từ `core/sandbox_manager.py` ➔ `infrastructure/sandbox/sandbox_capabilities.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+---
+
+### 🔹 EPIC R10: Testing, Packaging & Contributor Experience (Hệ Thống Kiểm Thử & Tài Liệu Đóng Góp)
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì chính - Task trọng tâm của Team Duy)
+* **Mục tiêu**: Xây dựng toàn bộ hệ thống test pyramid (unit, contract, integration, headless UI), thiết lập CI Quality Gate tự động, soạn thảo tài liệu Contributor Recipes và thực hiện E2E smoke test trước khi phát hành.
+
+- [ ] **R10-T01 (Team Duy)**: Thiết lập Tháp kiểm thử phân tầng (Unit tests không I/O <0.05s, Contract tests cho Providers/Tools, Integration tests, Fakes library) ➔ `tests/`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R10-T02 (Team Duy)**: Xây dựng Bộ script CI Quality Gate tự động (`scripts/check_imports.py`, `scripts/check_loc.py`, `scripts/audit_security.py`, `scripts/run_quality_gate.py`)  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R10-T03 (Team Duy)**: Cập nhật tài liệu kiến trúc 4 tầng, hướng dẫn setup môi trường & pre-commit hook ➔ `README.md` & `START_CONTRIBUTING.md`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R10-T04 (Team Duy)**: Soạn thảo bộ Contributor Recipes (3 công thức: Thêm Model Provider, Thêm Built-in/MCP Tool, Thêm Màn hình/Widget) ➔ `docs/governance/contributor-recipes.md`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+- [ ] **R10-T05 (Team Duy)**: Xây dựng bộ kiểm thử khói phát hành (E2E Release Smoke Test qua headless Qt với 5 kịch bản chính) ➔ `tests/e2e/test_smoke.py`  
+  *Start: `____-__-__ __:__` | End: `____-__-__ __:__`*
+
+---
+
+## 📅 PHẦN 2: CHECKLIST TIẾN ĐỘ THEO NGÀY CỦA TỪNG TEAM (21/08 ➔ 31/08)
+
+### 🔵 TEAM DUY (Core AI, Routing, Turn Runtime & Testing Lead)
+
+| Ngày | Task Cần Hoàn Thành | Start Time | End Time | Trạng Thái |
+| :--- | :--- | :---: | :---: | :---: |
+| **21/08 (T6)** | Khóa DTO `ConversationExecutionRequest`, `AgentEvent`; Xây dựng `FakeProvider`, `FakeToolExecutor` | `2026-08-21 18:23` | `2026-08-21 18:35` | [x] |
+| **22-23/08 (T7-CN)** | Chuẩn hóa `ProviderDescriptor`, `ProviderRegistry`; Wrap OpenAI, Anthropic, Ollama, FPT Gateway; Viết Contract Tests | `2026-08-22 18:45` | `2026-08-22 19:01` | [x] |
+| **24/08 (T2)** | Xây dựng `RoutingApplicationService` độc lập Qt; Tách `ComposerWidget` & `AttachmentPicker` | `2026-08-22 18:53` | `2026-08-22 18:57` | [~] |
+| **25/08 (T3)** | Xây dựng `ConversationApplicationService`; Tách `ChatHistoryWidget` và bubble renderer | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **26/08 (T4)** | Nối stream `AgentEvent` sang Chat History; Tách `AudioRecorderWidget` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **27/08 (T5)** | Tách `ChatOutputPanel` & File Watcher; Lắp ráp container `ChatPanel` và `Floating HelpAgent` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **28/08 (T6)** | Xóa copy routing cũ trong `ui/chat_panel.py`; Fix circular import `model_pricing` ↔ `usage_tracker` | `2026-08-22 18:57` | `2026-08-22 18:59` | [~] |
+| **29/08 (T7)** | Viết suite integration test cho toàn bộ luồng Chat (`tests/integration/test_chat_flow.py`) | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 3**: Chạy `python scripts/check_imports.py` đảm bảo 0 import `PySide6` trong domain & application | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **31/08 (T2)** | **Chủ trì EPIC R10**: Viết Contributor Recipes, chạy E2E Smoke Test (`tests/e2e/test_smoke.py`) và merge PR cuối cùng | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+
+> **Chú thích trạng thái**: `[~]` = hoàn tất **phần thuộc EPIC R03**, phần còn lại của dòng đó thuộc EPIC khác nên chưa đóng.
+> - Dòng **24/08**: đã xong `RoutingApplicationService` (R03-T03); phần `ComposerWidget`/`AttachmentPicker` thuộc R08-T01/T02 — chưa làm.
+> - Dòng **28/08**: đã xóa copy routing trong `ui/chat_panel.py` (R03-T04) **và** cả `ui/co4e_tab.py`, `ui/folder_tab.py` (R03-T05); phần circular import `model_pricing` ↔ `usage_tracker` thuộc R09-T02 — chưa làm.
+
+---
+
+### 🟣 TEAM NAM (Automation Workflows, Co4E, Monitoring & Governance)
+
+| Ngày | Task Cần Hoàn Thành | Start Time | End Time | Trạng Thái |
+| :--- | :--- | :---: | :---: | :---: |
+| **21/08 (T6)** | Khóa DTO Co4E; Xây dựng `AtomicJsonFile` và `KeyringAdapter` (`SecretStore`) | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **22-23/08 (T7-CN)** | Refactor `config.py` sang `ConfigRepository`; Tách `ProviderSettingsWidget` & `ConnectorSettingsWidget` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **24/08 (T2)** | Tách 3 tab đầu của Monitoring (`overview_tab.py`, `sandbox_status_tab.py`); Xây dựng `MonitoringQueryService` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **25/08 (T3)** | Tách 4 tab còn lại của Monitoring (`security_events_tab.py`, `mcp_history_tab.py`,...); Lắp ráp container `MonitoringTab` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **26/08 (T4)** | Bóc tách `Co4EWorkflowService`; Tách `NodePropertyPanel` & `AgentListPanel` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **27/08 (T5)** | Tách `Co4ECanvasWidget`, `Co4ERunControlWidget` & `Co4EChatView` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **28/08 (T6)** | Lắp ráp container `Co4ETab`; Xây dựng `bootstrap.py` (Composition Root) và tách `MainWindow` shell | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **29/08 (T7)** | Fix circular import `agent_security` ↔ `agent_security_alert`; Integration test luồng Co4E & Settings | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 1**: Chạy `python scripts/audit_security.py` đảm bảo 0 API Key/Token plaintext | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **31/08 (T2)** | Fix tồn đọng Check 1, cập nhật tài liệu kiến trúc, merge PR cuối | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+
+---
+
+### 🟢 TEAM HOA (Workspace, Filesystem, Scheduling & Tool Registry)
+
+| Ngày | Task Cần Hoàn Thành | Start Time | End Time | Trạng Thái |
+| :--- | :--- | :---: | :---: | :---: |
+| **21/08 (T6)** | Khóa DTO `ToolDescriptor`, `ToolCapability`; Tách `FileTools` từ `core/tools.py` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **22-23/08 (T7-CN)** | Tách `CommandTools`, `FetchTools`; Tách `TokenUsageCardWidget` & `UsageChartWidget` (Dashboard) | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **24/08 (T2)** | Tách `TaskRepository` & `ScheduleCalculator`; Tách `KanbanBoardWidget` (7 cột trạng thái) | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **25/08 (T3)** | Xây dựng `QtSchedulerClock` adapter (tách khỏi `QTimer`); Tách `CalendarViewWidget` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **26/08 (T4)** | Xây dựng `TaskApplicationService`; Tách `AiTaskCreatorDialog` & `AiTaskImportDialog` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **27/08 (T5)** | Tách `WorkspaceFileTree`, `DocumentPreviewManager` & `AiFileEditorDialog` từ `FolderTab` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **28/08 (T6)** | Tách `StructureGraphView` (GraphRAG); Lắp ráp shell `FolderTab` & `ScheduleTaskTab` | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **29/08 (T7)** | Nối `ToolPolicyGateway` qua MCP Client & Built-in Tools; Integration test Task Scheduler & File Explorer | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 2**: Chạy `python scripts/check_loc.py --max-lines 400` đảm bảo 0 file >400 dòng | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **31/08 (T2)** | Fix tồn đọng Check 2, cập nhật README, merge PR cuối | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+
+---
+
+## 🚦 PHẦN 3: CHECKLIST CHECKPOINT REVIEW & CƠ CHẾ KIỂM DUYỆT CASAN
+
+### 🛡️ Định nghĩa 5 Chữ Cái CASAN:
+- **C - Clean Architecture**: 0 import `PySide6` trong `domain/` và `application/`.
+- **A - Atomic Persistence**: 0 plaintext secrets trong JSON/config; dùng `AtomicJsonFile` ghi tệp an toàn.
+- **S - Single Responsibility**: 0 file production nào > 400 dòng code (LOC).
+- **A - Automated Test Pyramid**: Bộ test phân tầng chạy offline 100% không phụ thuộc network/UI.
+- **N - No Regression & Smoke**: Toàn bộ suite test (>81 tests) và E2E Smoke test pass 100%.
+
+### 🔍 Bảng Theo Dõi Các Checkpoints & Cổng Kiểm Duyệt CASAN:
+
+| Thời Điểm | Checkpoint / Cổng Duyệt | Lệnh Kiểm Tra Thực Tế | Tiêu Chí Bắt Buộc | Phụ Trách | Start Time | End Time | Trạng Thái |
+| :--- | :--- | :--- | :--- | :--- | :---: | :---: | :---: |
+| **23/08 (CN - 17:00)** | **Checkpoint 1: Contracts & Fakes** | `pytest tests/contracts tests/fakes` | 100% DTO và Fake Services tạo xong; test pass | Cả 3 Team | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **28/08 (T6 - 17:00)** | **Checkpoint 2: Services & Sub-widgets** | `pytest tests/` | Tách xong 100% God Files; 0 circular import | Cả 3 Team | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN - 17:00)** | **CASAN Check 1: Security Audit** | `python scripts/audit_security.py` | 0 plaintext secret trong file cấu hình | Team Nam | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN - 17:00)** | **CASAN Check 2: Modularity (LOC)** | `python scripts/check_loc.py --max-lines 400` | 0 file production nào > 400 dòng code | Team Hoa | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **30/08 (CN - 17:00)** | **CASAN Check 3: Clean Architecture** | `python scripts/check_imports.py` | 0 import `PySide6` trong domain & application | Team Duy | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+| **31/08 (T2 - 15:00)** | **Final Release E2E Smoke Test** | `pytest tests/e2e/test_smoke.py` | 5 kịch bản end-to-end pass 100% trên `main` | Team Duy & 3 Team | `____-__-__ __:__` | `____-__-__ __:__` | [ ] |
+
+---
+
+## 📋 PHẦN 4: DEFINITION OF DONE (DOD) CHO MỖI PULL REQUEST
+
+Mọi Pull Request của cả 3 team trước khi merge vào nhánh chính cần được đối chiếu checklist sau:
+
+- [ ] **1. Kích thước file (LOC)**: File mới hoặc file sau khi refactor không vượt quá **400 dòng code**.
+- [ ] **2. Phụ thuộc kiến trúc (Clean Architecture)**: Không import `PySide6` / Qt trong các module thuộc `domain/` và `application/`.
+- [ ] **3. An toàn thông tin (Security)**: API Key / Credential được lưu trữ qua `SecretStore` (Keyring), không lưu cứng hoặc lưu plaintext trong file JSON.
+- [ ] **4. Bắt buộc Comment Code bằng Tiếng Anh (English In-Code Comments)**: 100% các dòng hoặc khối code sửa đổi/bóc tách đều có comment tiếng Anh giải thích rõ logic xử lý và lý do kỹ thuật.
+- [ ] **5. Ghi nhận thời gian thực hiện (Timestamps)**: Đã điền đầy đủ mốc thời gian `Start: YYYY-MM-DD HH:mm` và `End: YYYY-MM-DD HH:mm` vào `Refactoring_Checklist.md` và PR description.
+- [ ] **6. Kiểm thử tự động (Automated Tests)**: Có unit test hoặc contract test đi kèm với tỷ lệ pass 100%. Chạy `pytest` hoàn tất < 3 giây.
+- [ ] **7. Không gây lỗi chéo (No Regression)**: Chạy kiểm thử toàn bộ hệ thống không làm hỏng các tính năng hiện hữu.
+

docs/refactor/bug.md

@@ -0,0 +1,155 @@
+# NHẬT KÝ THEO DÕI VÀ PHÒNG NGỪA LỖI TÁI CẤU TRÚC (BUG & LESSONS LEARNED LOG)
+## DỰ ÁN: COWORK LOCAL (COWORK-LOCAL BAMBOO)
+
+Tài liệu này dùng để ghi nhận **toàn bộ các lỗi, xung đột kiến trúc và sự cố phát sinh** trong suốt quá trình refactoring của cả 3 team (Team Duy, Team Nam, Team Hoa).
+
+> [!IMPORTANT]
+> ### 🛡️ NGUYÊN TẮC VÀNG VỀ QUẢN TRỊ CHẤT LƯỢNG (ZERO RECURRENCE):
+> 1. **Ghi nhận ngay lập tức**: Khi gặp bất kỳ lỗi nào (Syntax, Circular Import, Type Error, Test Failure, Thread Freeze, Data Corruption), kỹ sư/AI phải ghi ngay vào tài liệu này trước khi tiếp tục task.
+> 2. **Phân tích nguyên nhân gốc rễ (Root Cause)**: Không chỉ sửa phần ngọn mà phải giải thích rõ bản chất vì sao lỗi xảy ra.
+> 3. **Rút ra quy tắc phòng ngừa (Prevention Rule)**: Đặt ra nguyên tắc kỹ thuật để **TUYỆT ĐỐI KHÔNG TÁI PHẠM** ở các task tiếp theo.
+> 4. **Checklist đầu vào**: Trước khi bắt đầu bất kỳ task mới nào, kỹ sư/AI **bắt buộc phải đọc lại toàn bộ file này**.
+
+---
+
+## 📌 BẢNG TỔNG HỢP CÁC LỖI ĐÃ PHÁT HIỆN & KHẮC PHỤC
+
+| Bug ID | Ngày Phát Hiện | Phân Hệ / File Bị Ảnh Hưởng | Loại Lỗi | Trạng Thái | Team Phụ Trách |
+| :--- | :---: | :--- | :--- | :---: | :---: |
+| `BUG-001` | 2026-08-20 | `core/model_pricing.py` ↔ `core/usage_tracker.py` | Circular Dependency | 🟡 Đã có giải pháp (R09) | Team Duy & Team Nam |
+| `BUG-002` | 2026-08-20 | `core/agent_security.py` ↔ `core/agent_security_alert.py` | Circular Dependency | 🟡 Đã có giải pháp (R09) | Team Nam |
+| `BUG-003` | 2026-08-20 | `state.py::active_project_id` & `ui/workspace_tab.py` | Race Condition / Global State Leak | 🟡 Đã có giải pháp (R06) | Team Hoa |
+| `BUG-004` | 2026-08-20 | `core/task_scheduler.py` ↔ `PySide6.QtCore.QTimer` | Architecture Violation (Qt in Domain/App) | 🟡 Đã có giải pháp (R07) | Team Hoa |
+| `BUG-005` | 2026-08-20 | `ui/chat_panel.py#L638`, `ui/co4e_tab.py`, `ui/folder_tab.py` | Code Duplication (Copy Routing Logic) | 🟡 Đã có giải pháp (R03) | Team Duy |
+| `BUG-006` | 2026-08-21 | `scripts/check_imports.py` | UnicodeEncodeError (Windows CP932 console emoji) | 🟢 Đã khắc phục (R01) | Team Duy |
+| `BUG-007` | 2026-08-21 | `platform/` ➔ `infrastructure/platform/` | Standard Library Shadowing (`import platform`) | 🟢 Đã khắc phục (R01) | Team Duy |
+
+---
+
+## 🔍 CHI TIẾT TỪNG LỖI & QUY TẮC PHÒNG NGỪA
+
+---
+
+### 🔴 `BUG-001`: Circular Import giữa Module Định Giá (`model_pricing.py`) và Theo Dõi Token (`usage_tracker.py`)
+
+* **Phân hệ**: `core/model_pricing.py` & `core/usage_tracker.py`
+* **Triệu chứng (Symptom)**: Lỗi `ImportError: cannot import name 'ModelPricing' from partially initialized module` khi khởi động ứng dụng hoặc chạy test độc lập.
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - `model_pricing.py` import `UsageTracker` để cập nhật dữ liệu tiêu thụ.
+  - Ngược lại, `usage_tracker.py` import `ModelPricing` để tính toán chi phí theo từng model ID.
+* **Giải pháp khắc phục (Resolution)**:
+  - Tách Data Transfer Object (DTO) `ModelPricing` sang tầng Domain thuần túy `domain/models/model_pricing.py`.
+  - Cả `model_pricing.py` và `usage_tracker.py` đều import DTO từ `domain/models/`, chuyển quan hệ thành 1 chiều (Dependency Inversion).
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Không bao giờ để 2 service hoặc 2 module nghiệp vụ import lẫn nhau. Mọi cấu trúc dữ liệu dùng chung (DTO/Value Object/Event) **phải được đặt tại tầng `domain/`**.
+
+---
+
+### 🔴 `BUG-002`: Circular Import giữa An Ninh Agent (`agent_security.py`) và Cảnh Báo (`agent_security_alert.py`)
+
+* **Phân hệ**: `core/agent_security.py` & `core/agent_security_alert.py`
+* **Triệu chứng (Symptom)**: Lỗi khởi tạo vòng tròn khi runtime bắn ra alert sự kiện bảo mật.
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Module security vừa kiểm tra policy vừa khởi tạo trực tiếp instance alert dialog, trong khi alert dialog lại import ngược lại rule security để hiển thị chi tiết mã lỗi.
+* **Giải pháp khắc phục (Resolution)**:
+  - Tách sự kiện cảnh báo thành Event DTO `SecurityAlertEvent` tại `domain/security/security_event.py`.
+  - Tầng Security chỉ phát ra Event (`emit_event`), tầng Presentation/UI tự lắng nghe Event để render Dialog.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Logic an ninh và xử lý nghiệp vụ không bao giờ được gọi trực tiếp UI Dialog. Luôn giao tiếp thông qua cơ chế Event-Driven (`AgentEvent`, `SecurityEvent`).
+
+---
+
+### 🔴 `BUG-003`: Xung Đột Race Condition do Sử Dụng Biến Toàn Cục `active_project_id` trong `state.py`
+
+* **Phân hệ**: `state.py`, `ui/workspace_tab.py`, Scheduled Task Runners
+* **Triệu chứng (Symptom)**: Khi task scheduler chạy ngầm hoặc người dùng chuyển tab nhanh, file bị ghi nhầm vào thư mục dự án khác với dự án đang hiển thị trên màn hình.
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Ứng dụng đọc và ghi trực tiếp vào biến toàn cục `AppContext.active_project_id` từ nhiều luồng khác nhau mà không có cơ chế snapshot ngữ cảnh.
+* **Giải pháp khắc phục (Resolution)**:
+  - Xóa bỏ việc đọc biến toàn cục. Mỗi lần khởi chạy turn hoặc task, tạo một snapshot bất biến `WorkspaceSession(project_id, root_path, allowed_paths)`.
+  - Luồng ngầm chỉ thao tác trên `WorkspaceSession` được truyền vào từ lúc khởi tạo.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Tuyệt đối không dùng biến toàn cục (Global State / Singletons có trạng thái thay đổi) để điều khiển luồng thực thi nền. Mọi ngữ cảnh phải được truyền tường minh qua DTO snapshot.
+
+---
+
+### 🔴 `BUG-004`: Vi Phạm Ranh Giới Kiến Trúc Khi Import `PySide6.QtCore.QTimer` trong Domain / Scheduling Engine
+
+* **Phân hệ**: `core/task_scheduler.py#L20`
+* **Triệu chứng (Symptom)**: Không thể viết Unit Test cho thuật toán tính toán lịch chạy (cron/interval) trên môi trường CI/CD (GitHub Actions / Linux Server headless) nếu thiếu driver màn hình X11/Wayland hoặc chưa cài `PySide6`.
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Động cơ lập lịch bị gắn chặt cứng với `QTimer` của framework Qt thay vì tách riêng logic tính toán thời gian.
+* **Giải pháp khắc phục (Resolution)**:
+  - Tách thuật toán tính lịch sang `domain/tasks/schedule_calculator.py` (Pure Python 100%).
+  - Tạo `platform/qt/qt_scheduler_clock.py` làm adapter bọc `QTimer` cho app chạy thật, và `tests/fakes/fake_clock.py` cho unit test.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Tầng Domain và Application tuyệt đối không import thư viện GUI (`PySide6`, `PyQt`). Luôn bọc các thành phần phụ thuộc framework bên ngoài qua Adapter Interface.
+
+---
+
+### 🔴 `BUG-005`: Nhân Bản Mã Nguồn (Code Duplication) Logic Routing Mô Hình AI tại Nhiều Màn Hình
+
+* **Phân hệ**: `ui/chat_panel.py#L638`, `ui/co4e_tab.py`, `ui/folder_tab.py`
+* **Triệu chứng (Symptom)**: Khi cập nhật thêm model provider mới (như FPT Gateway hay Claude 3.7), phải sửa code thủ công ở 3 file UI khác nhau; phát sinh sai lệch quy tắc fallback giữa các màn hình.
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Thiếu một tầng Application Service tập trung, dẫn đến việc lập trình viên copy-paste hàm chọn model từ `ChatPanel` sang các tab khác.
+* **Giải pháp khắc phục (Resolution)**:
+  - Xây dựng `application/model_routing/routing_application_service.py` duy nhất, cung cấp API `route_request(request) -> ModelRouteDecision`.
+  - Mọi màn hình UI chỉ gọi service này, không tự viết lại logic kiểm tra key hay fallback.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Nghiệp vụ dùng chung giữa các màn hình phải được đưa vào `application/` services. Không bao giờ viết logic nghiệp vụ trực tiếp trong các file Widget UI.
+
+---
+
+### 🟢 `BUG-006`: `UnicodeEncodeError` khi in Emojis trên Console Windows (CP932/CP1252)
+
+* **Phân hệ / File**: `scripts/check_imports.py`
+* **Triệu chứng (Symptom)**:
+  ```text
+  Traceback (most recent call last):
+    File "scripts/check_imports.py", line 127, in main
+      print(f"\U0001f6e1\ufe0f  Running Clean Architecture Import Guard...")
+  UnicodeEncodeError: 'cp932' codec can't encode character '\U0001f6e1' in position 0: illegal multibyte sequence
+  ```
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Trên hệ điều hành Windows sử dụng locale tiếng Nhật (mã trang CP932) hoặc tiếng Anh (CP1252), `sys.stdout` mặc định không hỗ trợ các ký tự Unicode/Emoji ngoài bảng mã, dẫn đến crash khi in log dòng lệnh.
+* **Giải pháp khắc phục (Resolution)**:
+  - Tự động bọc lại `sys.stdout` và `sys.stderr` bằng `io.TextIOWrapper` với `encoding="utf-8"` và `errors="replace"`.
+  - Thay thế các emoji phức tạp bằng các tag văn bản ASCII chuẩn hóa như `[Clean Arch Guard]`, `[PASS]`, `[FAIL]`.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Mọi script CLI (`scripts/*.py`) phải có cơ chế cấu hình `utf-8` stream wrapper và ưu tiên sử dụng text tags (`[INFO]`, `[WARN]`, `[ERROR]`) thay vì emoji Unicode trực tiếp để đảm bảo chạy mượt mà trên mọi môi trường Windows đa ngôn ngữ.
+
+---
+
+### 🟢 `BUG-007`: Xung Đột Tên Thư Mục Trùng Với Standard Library (`platform/` Shadowing `import platform`)
+
+* **Phân hệ / File**: `platform/` ➔ Chuyển thành `infrastructure/platform/`
+* **Triệu chứng (Symptom)**:
+  ```text
+  INTERNALERROR> File "_pytest/terminal.py", line 853: verinfo = platform.python_version()
+  INTERNALERROR> AttributeError: module 'platform' has no attribute 'python_version'
+  ```
+* **Nguyên nhân gốc rễ (Root Cause)**:
+  - Khi tạo một package ở thư mục gốc có tên trùng với module thư viện chuẩn của Python (`platform`, `email`, `test`, `asyncio`, `logging`), Python trên `sys.path` sẽ ưu tiên import thư mục local thay vì thư viện chuẩn của Python runtime, dẫn đến crash toàn bộ pytest runner và các thư viện bên thứ ba.
+* **Giải pháp khắc phục (Resolution)**:
+  - Xóa bỏ package `platform/` ở root.
+  - Đưa adapter Qt Scheduler Clock vào đúng vị trí hạ tầng: `infrastructure/platform/qt/`.
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: Tuyệt đối không đặt tên package/thư mục ở root trùng với tên các module built-in của Python (`platform`, `logging`, `types`, `time`, `io`, `os`, `sys`). Mọi platform adapter phải nằm trong `infrastructure/platform/` hoặc `platform_adapters/`.
+
+---
+
+## 📝 MẪU GHI NHẬN BUG MỚI (BUG REPORT TEMPLATE)
+
+Khi gặp bất kỳ bug mới nào trong quá trình làm việc, hãy sao chép khối mẫu sau và điền vào cuối tài liệu:
+
+```markdown
+### 🔴 `BUG-XXX`: [Tóm tắt ngắn gọn tên lỗi]
+
+* **Phân hệ / File**: `[Đường dẫn file bị lỗi]`
+* **Triệu chứng (Symptom)**: `[Mô tả hiện tượng lỗi, paste thông báo traceback hoặc kết quả test fail]`
+* **Nguyên nhân gốc rễ (Root Cause)**: `[Giải thích tại sao lỗi lại xảy ra]`
+* **Giải pháp khắc phục (Resolution)**: `[Mô tả cách sửa, file DTO/Service tạo mới hoặc cách refactor]`
+* **Quy tắc phòng ngừa (Prevention Rule - TUYỆT ĐỐI KHÔNG TÁI PHẠM)**:
+  > **Quy tắc**: `[Nguyên tắc kỹ thuật cụ thể để không bao giờ tái phạm lỗi này]`
+```

docs/refactor/plan.md

@@ -0,0 +1,682 @@
+## 🗓️ VI. LỘ TRÌNH THỰC HIỆN - 10 EPIC (REFACTORING ROADMAP)
+
+### Bảng Tổng Quan 10 EPIC
+
+| EPIC | Tên | Dependency | Giá Trị Kiến Trúc |
+| :--- | :--- | :--- | :--- |
+| **R01** | Architecture Foundation & Characterization | Không | Safety net + ngôn ngữ chung trước khi nhiều người sửa |
+| **R02** | Configuration, Secrets & Persistence | R01 | Loại bỏ global dict/direct write và bảo vệ credential |
+| **R03** | Model Providers & Routing | R01, R02 | 1 đường mở rộng provider, 1 routing flow duy nhất |
+| **R04** | Agent Runtime & Conversation Service | R01, R03 | Tách turn lifecycle khỏi widget |
+| **R05** | Tool, MCP & Connector Policy | R01, R04 | 1 security/approval path cho mọi tool call |
+| **R06** | Workspace, Filesystem & History Isolation | R01, R02 | Loại bỏ cross-project mutable path/state |
+| **R07** | Scheduling & Workflow Runtime | R01, R04, R06 | Tách Qt timer, persistence và runtime dispatch |
+| **R08** | UI/Application Separation | R03 - R07 | Thu nhỏ God widgets theo từng screen |
+| **R09** | Security Runtime, Sandbox & Observability | R01, R05 | Policy rõ, event schema thống nhất |
+| **R10** | Testing, Packaging & Contributor Experience | Tất cả | CI, docs, contributor có thể sửa 1 capability độc lập |
+
+---
+
+### 💡 Chiến Lược Triển Khai Song Song 100% Cho 3 Team (Zero Blocking)
+
+Để 3 team làm việc cùng lúc từ **21/08 đến 31/08/2026** mà không bị nghẽn (blocked), không phải chờ đợi nhau và loại bỏ hoàn toàn rủi ro merge conflict:
+
+1. **Ranh giới sở hữu mã nguồn tuyệt đối (Code Ownership & Zero File Overlap)**: Mỗi file/thư mục chỉ thuộc quyền chỉnh sửa của duy nhất 1 team. Tuyệt đối không để 2 team cùng sửa chung 1 file cùng lúc.
+2. **Nguyên tắc Contract-First & Mock-Driven**: Thống nhất Data Contract / DTO / Interface ngay từ Ngày 1. Khi cần gọi chéo giữa các phân hệ, team gọi sẽ dùng `Fake/Mock Adapter` để hoàn thiện UI/logic nội bộ mà **không cần chờ** team kia hoàn thành implementation.
+3. **Phân chia theo Phân hệ nghiệp vụ (Vertical Domain Slices)**: Mỗi team phụ trách trọn vẹn từ UI Sub-widgets đến Application Service và Infrastructure của phân hệ đó, đảm bảo tính tự chủ và khả năng test độc lập.
+
+```mermaid
+graph TD
+    subgraph T1 [🔵 TEAM 1: Core AI & Conversation Hub]
+        UI1[presentation/chat/] --> APP1[application/conversations/<br>application/model_routing/]
+        APP1 --> DOM1[domain/agents/<br>domain/models/]
+        APP1 --> INF1[infrastructure/providers/]
+    end
+
+    subgraph T2 [🟣 TEAM 2: Automation, Workflows & Governance]
+        UI2[presentation/co4e/<br>presentation/monitoring/<br>presentation/settings/] --> APP2[application/workflows/<br>application/monitoring/<br>application/settings/]
+        APP2 --> DOM2[domain/workflows/<br>domain/security/]
+        APP2 --> INF2[infrastructure/config/<br>infrastructure/secrets/]
+    end
+
+    subgraph T3 [🟢 TEAM 3: Workspace, Tools & Scheduling]
+        UI3[presentation/folder/<br>presentation/scheduling/<br>presentation/dashboard/<br>presentation/graph/] --> APP3[application/workspaces/<br>application/scheduling/]
+        APP3 --> DOM3[domain/tools/<br>domain/tasks/]
+        APP3 --> INF3[infrastructure/filesystem/<br>infrastructure/mcp/<br>infrastructure/persistence/]
+    end
+
+    style T1 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
+    style T2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    style T3 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+```
+
+---
+
+### 🖥️ Cấu Trúc Giao Diện Thực Tế & Bản Đồ Điều Hướng (Verified UI Layout & Navigation Map)
+
+Qua kiểm tra trực tiếp mã nguồn thực tế của giao diện (`app.py`, `ui/workspace_tab.py`, `ui/chat_panel.py`, `ui/co4e_tab.py`, `ui/folder_tab.py`, `ui/monitoring_tab.py`), cấu trúc layout hiện tại của Cowork Local được thiết kế theo mô hình **Thanh điều hướng phẳng (Flat Collapsible Nav Rail) + Không gian làm việc đa phân hệ (Workspace Hub)**:
+
+```mermaid
+graph TD
+    MW["MainWindow (app.py)"]
+    
+    subgraph NR ["👈 Collapsible Left Nav Rail (54px / 150px)"]
+        N_TOP["Header: Project Picker + '+ Chat Mới'"]
+        N_MAIN["Main Nav (Flat List)"]
+        N_REC["Section: GẦN ĐÂY (Recent Threads)"]
+        N_BOT["Bottom Nav (Ghim Đáy)"]
+        N_FOOT["Footer: Cài Đặt (Settings) + Tài Khoản"]
+    end
+
+    subgraph CA ["👉 Main Content Area (QStackedWidget)"]
+        P_WS["📁 WorkspaceTab (Trang Chủ Chính)"]
+        P_SCH["⏰ ScheduleTaskTab (Lịch Trình)"]
+        P_DB["📊 DashboardTab (Bảng Điều Khiển)"]
+        P_MON["🛡️ MonitoringTab (Giám Sát & Quản Trị - 8 Tabs)"]
+    end
+
+    subgraph WST ["📦 Các Sub-Tabs Trong Workspace (Điều khiển từ Nav Rail)"]
+        ST_PROJ["1. 📁 Dự Án (Project info, instructions, folder path)"]
+        ST_COW["2. 💬 Cowork (Chat Panel + Outer History Sidebar)"]
+        ST_CO4E["3. ⚡ Co4E Studio (Canvas Node, Agent/Skill Palette, Run Chat)"]
+        ST_FOLD["4. 📂 Folder Explorer (Tree, Code Editor, Preview, Terminal, AI Edit)"]
+        ST_GRAPH["5. 🕸️ GraphRAG (Knowledge Graph View + Q&A Panel)"]
+    end
+
+    MW --> NR
+    MW --> CA
+    N_MAIN -->|Chuyển sub-tab| WST
+    N_MAIN -->|Mở trang| P_SCH
+    N_BOT -->|Mở trang| P_DB
+    N_BOT -->|Mở trang| P_MON
+    P_WS --> WST
+
+    style MW fill:#1e293b,stroke:#0ea5e9,color:#fff
+    style NR fill:#0f172a,stroke:#334155,color:#fff
+    style CA fill:#1e293b,stroke:#475569,color:#fff
+    style WST fill:#334155,stroke:#38bdf8,color:#fff
+```
+
+#### 📌 Chi Tiết Thành Phần Giao Diện Của Từng Phân Hệ:
+
+1. **Thanh Điều Hướng Trái (Left Nav Rail - `app.py`):**
+   - Nút thu gọn / mở rộng (Menu toggle 54px ↔ 150px).
+   - Bộ chọn nhanh dự án (`nav_project` / `nav_project_btn`) & Nút `+ Chat mới` (`nav_new_chat`).
+   - Danh sách phẳng các màn hình làm việc chính (Dự án, Cowork, Co4E, Folder, GraphRAG, Lịch trình).
+   - Danh sách hội thoại gần đây (`RECENTS`) của dự án đang chọn.
+   - Nhóm ghim đáy (Bảng điều khiển, Giám sát) + Nút mở Cài đặt & Hàng thông tin tài khoản.
+   - **Trợ lý nổi (Floating Help Agent - `ui/help_agent_widget.py`):** Biểu tượng robot ghim góc dưới phải ở mọi màn hình, click là mở cửa sổ chat trợ giúp nhanh.
+
+2. **Workspace Tab (Trang Chủ - `ui/workspace_tab.py`):**
+   - **Cột trái:** Danh sách quản lý Dự án (Create, Delete, đổi tên, thu gọn / mở rộng).
+   - **Cột giữa:** Thanh lịch sử hội thoại ngoài (`ui/sidebar.py::HistorySidebar`) hiển thị xuyên suốt cho cả Cowork và GraphRAG.
+   - **Vùng chính:** Chứa 5 sub-tabs (ẩn thanh tab bar ngang để Nav Rail điều hướng trực tiếp):
+     - **Dự Án (`ProjectTab`):** Tên, mô tả, chỉ dẫn chung (shared instructions), đường dẫn thư mục sandbox, danh sách luồng chat.
+     - **Cowork (`ui/cowork_tab.py`):** Khung chat chính (`ui/chat_panel.py`, `ui/chat_view.py`, `ui/composer.py`).
+     - **Co4E Studio (`ui/co4e_tab.py`):** Canvas thiết kế luồng đồ thị node (`ui/co4e_canvas.py`), bảng chỉnh thuộc tính node (`ui/co4e_config_panel.py`), thư viện Agent/Skill, bộ điều khiển chạy luồng & Chat view tương tác.
+     - **Folder Explorer (`ui/folder_tab.py`):** Cây thư mục workspace, trình soạn thảo code syntax highlight, trình xem trước tài liệu đa định dạng (PDF, MS Office qua LibreOffice `ui/libreoffice_view.py`, HTML, Ảnh), Terminal tích hợp (`ui/terminal_panel.py`), và Dialog sửa code bằng AI (`ui/file_edit_dialog.py`).
+     - **GraphRAG (`ui/structure_graph_view.py`):** Đồ thị tri thức D3 WebEngine / Native 2D, bộ lọc thực thể, panel hỏi đáp ngữ cảnh mã nguồn (Graph Q&A).
+
+3. **Schedule Task Tab (Lịch Trình - `ui/schedule_task_tab.py`):**
+   - Bảng Kanban 7 cột trạng thái (Backlog, Todo, In Progress, Review, Done, Blocked, Cancelled) hỗ trợ kéo thả.
+   - Chế độ xem Lịch tháng (`ui/calendar_view.py`) trực quan hóa các task định kỳ và due dates.
+   - Dialog chỉnh sửa task (`ui/task_editor_dialog.py`) & các bộ tạo task tự động bằng AI.
+
+4. **Dashboard Tab (Bảng Điều Khiển - `ui/dashboard_tab.py`):**
+   - Thẻ thống kê tổng lượng Token tiêu thụ, chi phí ước tính, số lượng tác vụ đã chạy.
+   - Biểu đồ Spline trực quan hóa xu hướng chi phí theo thời gian (`ui/spline_chart.py`).
+   - Bảng thói quen sử dụng mô hình (AI Model Habits) và hạn mức ngân sách.
+
+5. **Monitoring Tab (Giám Sát & Quản Trị - `ui/monitoring_tab.py`):**
+   - Giữ nguyên tab bar nội bộ với 8 tab chuyên trách:
+     1. **Tổng quan (Overview):** Metrics CPU, Memory, số tiến trình sandbox, tổng log.
+     2. **Trạng thái Sandbox (Sandbox Status):** Giám sát các container/sub-process cách ly.
+     3. **Sự kiện bảo mật (Security Events):** Danh sách cảnh báo vi phạm policy an toàn.
+     4. **Lịch sử MCP (MCP History):** Nhật ký gọi tool MCP và latency.
+     5. **Nhật ký hoạt động (Action Logs):** Log chi tiết mọi thao tác đọc/ghi tệp, thực thi lệnh.
+     6. **Quản trị Agent (`ui/agents_admin_tab.py`):** Cấu hình Prompt và tham số cho các Agent chuyên biệt & Help Agent.
+     7. **Cài đặt bảo mật (Security Settings):** Bật/tắt các rào chắn Sandbox và phê duyệt công cụ.
+     8. **Quản trị Tool / Icon (`ui/tools_admin_tab.py`, `ui/icons_admin_tab.py`):** Quản lý metadata công cụ và bộ icon hệ thống.
+
+6. **Hộp Thoại Cài Đặt (Settings Dialog - `ui/settings_dialog.py`):**
+   - Cài đặt Nhà cung cấp (OpenAI, Anthropic, Ollama, FPT Gateway).
+   - Cài đặt Connectors (MCP Server, MS365, External APIs).
+   - Cài đặt Định tuyến mô hình (Off, Auto, Manual, Fallback rules).
+   - Cài đặt Chung (Ngôn ngữ, Giao diện Theme, Khởi động cùng hệ thống, System Tray).
+
+---
+
+### 👥 Ranh Giới Phân Hệ & Phạm Vi Của 3 Team (Duy, Nam, Hoa)
+
+| Team | Phân Hệ Phụ Trách | Phạm Vi Thư Mục Sở Hữu | File Cũ Cần Phân Rã / Tái Cấu Trúc | Trọng Tâm EPIC |
+| :--- | :--- | :--- | :--- | :--- |
+| **🔵 TEAM DUY**<br>*(Tech Lead)* | **Core AI, Routing, Agent Engine & Testing Lead** | `presentation/chat/`<br>`application/conversations/`<br>`application/model_routing/`<br>`domain/agents/`, `domain/models/`<br>`infrastructure/providers/`<br>`tests/` (Unit, Contract, Integration, E2E) | `ui/chat_panel.py`<br>`ui/cowork_tab.py`<br>`ui/help_agent_widget.py`<br>`core/chat_agent.py`<br>`core/routing/*`<br>`providers/*` | **R01, R03, R04, R10**<br>(Routing, Providers, Agent Engine, Chat UI, Floating Help Agent, Testing Pyramid, Contributor Recipes) |
+| **🟣 TEAM NAM** | **Automation, Workflows, Governance & Security** | `presentation/co4e/`<br>`presentation/monitoring/`<br>`presentation/settings/`<br>`presentation/shell/`, `bootstrap.py`<br>`application/workflows/`, `monitoring/`, `settings/`<br>`infrastructure/config/`, `secrets/`, `sandbox/` | `ui/co4e_tab.py`<br>`ui/monitoring_tab.py`<br>`ui/settings_dialog.py`<br>`app.py::MainWindow`<br>`config.py`<br>`core/co4e_run_manager.py` | **R02, R08, R09**<br>(Co4E Studio, Monitoring 8 tabs, Settings, Keyring, Nav Rail & Shell, Security Scan) |
+| **🟢 TEAM HOA** | **Workspace, Filesystem, Tools & Scheduling** | `presentation/workspace/`<br>`presentation/folder/`<br>`presentation/scheduling/`<br>`presentation/dashboard/`<br>`presentation/graph/`<br>`application/workspaces/`, `scheduling/`<br>`domain/tools/`, `domain/tasks/`<br>`infrastructure/filesystem/`, `mcp/`, `persistence/` | `ui/workspace_tab.py`<br>`ui/sidebar.py`<br>`ui/folder_tab.py`<br>`ui/structure_graph_view.py`<br>`ui/schedule_task_tab.py`<br>`ui/dashboard_tab.py`<br>`core/tools.py`<br>`core/task_executors.py`<br>`core/task_scheduler.py` | **R05, R06, R07, R08**<br>(Tools, Tasks, Workspace Project Manager, Folder Explorer & Editor, Graph RAG, Kanban Schedule, Dashboard) |
+
+---
+
+### 📅 Lịch Tổng Quan Theo Tuần (21/08 - 31/08/2026)
+
+```mermaid
+gantt
+    title Lộ Trình Phân Chia 3 Team Song Song (21/08 - 31/08/2026)
+    dateFormat  YYYY-MM-DD
+    section Team Duy (Core AI, Chat & Testing Lead)
+    Khóa DTO + FakeProvider + Provider Registry         :t1_1, 2026-08-21, 3d
+    RoutingService + Tách Composer & ChatHistory        :t1_2, 2026-08-24, 3d
+    ConversationService + ChatOutput + ChatPanel Shell  :t1_3, 2026-08-27, 3d
+    CASAN Check 3 + EPIC R10 Testing Pyramid & Smoke    :t1_4, 2026-08-30, 2d
+
+    section Team Nam (Workflow & Governance)
+    Khóa DTO + AtomicConfig + Keyring + Settings Split  :t2_1, 2026-08-21, 3d
+    MonitoringTab Split (7 tabs) + MonitoringService    :t2_2, 2026-08-24, 2d
+    Co4E Canvas + RunControl + WorkflowService          :t2_3, 2026-08-26, 3d
+    Bootstrap Root + CASAN Check 1 (Security Scan)      :t2_4, 2026-08-29, 3d
+
+    section Team Hoa (Workspace, Tools & Scheduling)
+    Khóa DTO + ToolRegistry + File Tools + Dashboard    :t3_1, 2026-08-21, 3d
+    TaskRepo + Clock + Kanban + Calendar View           :t3_2, 2026-08-24, 3d
+    FolderTree + DocumentPreview + Graph RAG            :t3_3, 2026-08-27, 3d
+    CASAN Check 2 (Single Responsibility) + E2E Support :t3_4, 2026-08-30, 2d
+```
+
+---
+
+### 🗓️ KẾ HOẠCH CHI TIẾT TỪNG NGÀY CHO 3 TEAM (21/08 ➔ 31/08)
+
+#### 🔵 TEAM DUY: Core AI, Routing & Testing Lead (Tech Lead)
+
+| Ngày | Công Việc Cụ Thể & Nơi Bóc Tách Code | File Đích Cần Tạo / Chỉnh Sửa | Tiêu Chí Kiểm Thử (Validation) |
+| :--- | :--- | :--- | :--- |
+| **21/08 (T6)** | • Khóa DTO từ `core/chat_agent.py`<br>• Xây dựng test doubles từ `providers/base.py` | ➔ `domain/agents/conversation_execution_request.py`<br>➔ `domain/agents/agent_event.py`<br>➔ `tests/fakes/fake_provider.py` | Unit test chạy <1s, không phụ thuộc Qt hay network |
+| **22-23/08 (T7-CN)** | • Chuẩn hóa catalog từ `providers/factory.py`<br>• Wrap OpenAI, Anthropic, Ollama, FPT Gateway | ➔ `domain/models/provider_descriptor.py`<br>➔ `infrastructure/providers/provider_registry.py` | Golden response test cho từng provider |
+| **24/08 (T2)** | • Hợp nhất routing từ `ui/chat_panel.py#L638` & `core/routing/`<br>• Tách Composer & Picker từ `ui/composer.py` | ➔ `application/model_routing/routing_application_service.py`<br>➔ `presentation/chat/composer_widget.py`<br>➔ `presentation/chat/attachment_picker.py` | Test routing policy không cần Qt; Composer test |
+| **25/08 (T3)** | • Tách turn orchestration từ `ui/chat_panel.py#L70`<br>• Tách chat bubble/markdown từ `ui/chat_view.py` | ➔ `application/conversations/conversation_application_service.py`<br>➔ `presentation/chat/chat_history_widget.py` | Turn test với `FakeProvider`: text stream & tool calls |
+| **26/08 (T4)** | • Nối sự kiện `AgentEvent` sang History Widget<br>• Tách ghi âm audio từ `ui/chat_panel.py` | ➔ `presentation/chat/audio_recorder_widget.py` | Event streaming UI test không lag main thread |
+| **27/08 (T5)** | • Tách file watcher & output panel từ `ui/chat_panel.py#L18`<br>• Lắp ráp shell hoàn chỉnh | ➔ `presentation/chat/chat_output_panel.py`<br>➔ `presentation/chat/chat_panel.py` | Smoke test: ChatPanel mở mượt mà, render đủ thành phần |
+| **28/08 (T6)** | • Xóa routing copy trong `ui/chat_panel.py`<br>• Fix circular import `core/model_pricing.py` ↔ `core/usage_tracker.py` | ➔ Patch các module liên quan | `python -c "import cowork_local"` không phát sinh lỗi |
+| **29/08 (T7)** | • Viết suite integration test cho toàn bộ luồng Chat<br>• Rà soát số dòng code Team Duy (<400 dòng/file) | ➔ `tests/integration/test_chat_flow.py` | 100% test pass |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 3 (Import Guard)**: Quét tĩnh kiểm tra `domain/` & `application/` không import `PySide6` | ➔ `scripts/check_imports.py` | 0 violation trong code mới |
+| **31/08 (T2)** | 🎯 **Chủ trì EPIC R10 (Task Chính Team Duy)**: Thiết lập Testing Pyramid, Contributor Recipes, E2E Smoke Test & Merge PR cuối | ➔ `tests/e2e/test_smoke.py`<br>➔ `docs/governance/contributor-recipes.md` | All tests pass, CASAN Gate PASS |
+
+---
+
+#### 🟣 TEAM NAM: Automation, Workflows, Governance & Security
+
+| Ngày | Công Việc Cụ Thể & Nơi Bóc Tách Code | File Đích Cần Tạo / Chỉnh Sửa | Tiêu Chí Kiểm Thử (Validation) |
+| :--- | :--- | :--- | :--- |
+| **21/08 (T6)** | • Khóa DTO từ `core/co4e.py`<br>• Xây dựng Atomic Write & Keyring từ `config.py` | ➔ `infrastructure/persistence/json/atomic_json_file.py`<br>➔ `infrastructure/secrets/keyring_adapter.py` | Fault-injection test (atomic write); Credential store test |
+| **22-23/08 (T7-CN)** | • Chuyển đổi `config.py` sang `ConfigRepository`<br>• Tách section từ `ui/settings_dialog.py` | ➔ `infrastructure/config/config_repository.py`<br>➔ `presentation/settings/provider_settings_widget.py`<br>➔ `presentation/settings/connector_settings_widget.py` | Config round-trip test; Settings UI render test |
+| **24/08 (T2)** | • Tách 3 tab đầu từ `ui/monitoring_tab.py`<br>• Xây dựng truy vấn dữ liệu độc lập | ➔ `presentation/monitoring/overview_tab.py`<br>➔ `presentation/monitoring/sandbox_status_tab.py`<br>➔ `application/monitoring/monitoring_query_service.py` | Render dữ liệu thống kê độc lập |
+| **25/08 (T3)** | • Tách 4 tab còn lại từ `ui/monitoring_tab.py`<br>• Lắp ráp shell Monitoring | ➔ `presentation/monitoring/security_events_tab.py`<br>➔ `presentation/monitoring/mcp_history_tab.py`<br>➔ `presentation/monitoring/monitoring_tab.py` | Smoke test: MonitoringTab chuyển tab mượt, filter log tốt |
+| **26/08 (T4)** | • Bóc tách runner từ `core/co4e_run_manager.py`<br>• Tách config & agent panels từ `ui/co4e_tab.py#L3` | ➔ `application/workflows/co4e_workflow_service.py`<br>➔ `presentation/co4e/node_property_panel.py`<br>➔ `presentation/co4e/agent_list_panel.py` | Workflow CRUD & validation test độc lập |
+| **27/08 (T5)** | • Tách Canvas vẽ node từ `ui/co4e_canvas.py`<br>• Tách Run control & chat view từ `ui/co4e_tab.py#L228` | ➔ `presentation/co4e/co4e_canvas_widget.py`<br>➔ `presentation/co4e/co4e_run_control_widget.py`<br>➔ `presentation/co4e/co4e_chat_view.py` | Canvas node operations test |
+| **28/08 (T6)** | • Lắp ráp container Co4ETab<br>• Tách Composition root & MainWindow từ `app.py#L122` | ➔ `presentation/co4e/co4e_tab.py`<br>➔ `bootstrap.py`<br>➔ `presentation/shell/main_window.py` | Khởi động app qua `bootstrap.py` thành công |
+| **29/08 (T7)** | • Fix circular import `core/agent_security.py` ↔ `core/agent_security_alert.py`<br>• Integration test luồng Co4E & Settings | ➔ Patch security modules | Co4E flow chạy trơn tru |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 1 (Security Scan)**: Quét rà soát toàn bộ file config/JSON để đảm bảo 0 API Key/Token lưu plaintext | ➔ Script security audit | 0 credential plaintext |
+| **31/08 (T2)** | Fix tồn đọng Check 1, cập nhật tài liệu kiến trúc, merge PR cuối | — | CASAN Check 1 PASS |
+
+---
+
+#### 🟢 TEAM HOA: Workspace, Filesystem, Tools & Scheduling
+
+| Ngày | Công Việc Cụ Thể & Nơi Bóc Tách Code | File Đích Cần Tạo / Chỉnh Sửa | Tiêu Chí Kiểm Thử (Validation) |
+| :--- | :--- | :--- | :--- |
+| **21/08 (T6)** | • Khóa DTO từ `core/tools.py` & `core/tasks.py`<br>• Tách file tools từ `core/tools.py` | ➔ `domain/tools/tool_descriptor.py`<br>➔ `domain/tools/tool_registry.py`<br>➔ `infrastructure/filesystem/file_tools.py` | Tool handler test độc lập; Atomic write test |
+| **22-23/08 (T7-CN)** | • Tách command, fetch, image tools từ `core/tools.py`<br>• Tách card & chart từ `ui/dashboard_tab.py` | ➔ `infrastructure/filesystem/command_tools.py`<br>➔ `infrastructure/filesystem/fetch_tools.py`<br>➔ `presentation/dashboard/token_usage_card_widget.py`<br>➔ `presentation/dashboard/usage_chart_widget.py` | Tool execution test; Dashboard chart test với mock data |
+| **24/08 (T2)** | • Tách repository & do lịch từ `core/tasks.py`<br>• Tách Kanban board từ `ui/schedule_task_tab.py` | ➔ `infrastructure/persistence/json/task_repository_impl.py`<br>➔ `domain/tasks/schedule_calculator.py`<br>➔ `presentation/scheduling/kanban_board_widget.py` | Task CRUD test; Kanban card render test |
+| **25/08 (T3)** | • Tách `QTimer` adapter từ `core/task_scheduler.py#L20`<br>• Tách Calendar view từ `ui/schedule_task_tab.py` | ➔ `platform/qt/qt_scheduler_clock.py`<br>➔ `presentation/scheduling/calendar_view_widget.py` | Fake clock test kích hoạt task đúng lịch |
+| **26/08 (T4)** | • Tách dispatch logic từ `core/task_executors.py`<br>• Tách AI create dialogs từ `ui/schedule_task_tab.py` | ➔ `application/scheduling/task_application_service.py`<br>➔ `presentation/scheduling/ai_task_creator_dialog.py` | Task dispatch test; AI planner test với fake provider |
+| **27/08 (T5)** | • Tách File tree & Previews từ `ui/folder_tab.py#L350`<br>• Tách AI File Editor từ `ui/folder_tab.py` | ➔ `presentation/folder/workspace_file_tree.py`<br>➔ `presentation/folder/document_preview_manager.py`<br>➔ `application/workspaces/file_workspace_service.py` | File CRUD test; Preview render test; AI apply diff test |
+| **28/08 (T6)** | • Tách Graph View từ `ui/structure_graph_view.py`<br>• Lắp ráp shell FolderTab & ScheduleTab | ➔ `presentation/graph/structure_graph_view.py`<br>➔ `application/workspaces/graph_index_service.py`<br>➔ `presentation/scheduling/schedule_task_tab.py` | Graph RAG test; Smoke test: Folder & Schedule tabs mở tốt |
+| **29/08 (T7)** | • Nối `ToolPolicyGateway` qua `core/mcp_client.py` & built-in tools<br>• Integration test Task Scheduler & File Explorer | ➔ `application/conversations/tool_policy_gateway.py` | Approval flow hoạt động chuẩn |
+| **30/08 (CN)** | 🔍 **Chủ trì CASAN Check 2 (Single Responsibility Audit)**: Quét toàn bộ codebase đảm bảo không có file production nào > 400 dòng | ➔ Script count LOC | 0 file vi phạm (>400 lines) |
+| **31/08 (T2)** | Fix tồn đọng Check 2, cập nhật README, merge PR cuối | — | CASAN Check 2 PASS |
+
+---
+
+### 🚦 Checkpoint Review & Cơ Chế Cổng Kiểm Duyệt CASAN (CASAN Verification Gate)
+
+#### 🛡️ CASAN Là Gì?
+**CASAN** là bộ cổng kiểm duyệt chất lượng và an toàn kiến trúc tự động (Automated Architectural Quality Gate) bắt buộc trước khi phát hành phiên bản tái cấu trúc. Tên viết tắt đại diện cho 5 nguyên tắc cốt lõi:
+- **C** - **Clean Architecture (Ranh giới tầng sạch)**: Tầng `domain/` và `application/` tuyệt đối thuần Python, 0 phụ thuộc vào `PySide6` / Qt GUI framework.
+- **A** - **Atomic Persistence (Lưu trữ an toàn & Bí mật)**: 0 lưu trữ plaintext API Key/Token trong JSON/config (phải dùng OS `SecretStore` / Keyring); mọi thao tác ghi dữ liệu tệp đều dùng cơ chế `AtomicJsonFile` chống hỏng dữ liệu khi crash.
+- **S** - **Single Responsibility & Modularity (Kích thước tệp nhỏ gọn)**: Giới hạn tối đa **400 dòng code (LOC)** cho mỗi file production; mỗi file/class chỉ đảm nhận đúng 1 trách nhiệm duy nhất.
+- **A** - **Automated Test Pyramid (Tháp kiểm thử tự động)**: Toàn bộ Unit tests (<1s), Contract tests, Integration tests chạy offline hoàn toàn không cần kết nối mạng hay Qt GUI event loop.
+- **N** - **No Regression & E2E Smoke (Không hồi quy & Ổn định phát hành)**: Toàn bộ suite test hiện tại (>81 tests) và bộ E2E Smoke Test của ứng dụng chạy thành công 100% trên nhánh `main`.
+
+#### 🔍 Chi Tiết 3 Cổng Kiểm Tra CASAN (Chạy Tự Động Ngày 30/08 & Pre-commit):
+
+| Cổng Kiểm Tra | Mục Tiêu & Cơ Chế Kiểm Tra | Lệnh Chạy Kiểm Thử | Tiêu Chí Pass Bắt Buộc | Team Phụ Trách |
+| :--- | :--- | :--- | :--- | :--- |
+| **CASAN Check 1: Security Audit** | Quét regex phân tích tĩnh toàn bộ file cấu hình (`.json`, `.jsonl`, `.yaml`, `config.py`) nhằm phát hiện secret/token lưu plaintext | `python scripts/audit_security.py` | `0 plaintext secrets found` (100% key lưu qua Keyring) | **🟣 Team Nam** |
+| **CASAN Check 2: Modularity (LOC Audit)** | Quét đếm số dòng code (LOC) của từng file trong `presentation/`, `application/`, `domain/`, `infrastructure/` | `python scripts/check_loc.py --max-lines 400` | `0 files exceeding 400 lines` (Tất cả God Files đã bị chia nhỏ) | **🟢 Team Hoa** |
+| **CASAN Check 3: Clean Architecture Guard** | Dùng thư viện `ast` phân tích cây cú pháp trừu tượng, quét cấm các import `PySide6`, `PyQt*` bên trong `domain/` và `application/` | `python scripts/check_imports.py` | `0 Qt imports in business logic` | **🔵 Team Duy** |
+| **Lệnh Tổng Hợp CASAN Gate** | Chạy toàn bộ 3 checks trên + suite `pytest` | `python scripts/run_quality_gate.py` | `ALL GATES PASSED (100%)` | **🔵 Team Duy (Tech Lead)** |
+
+#### 📅 Bảng Kế Hoạch Checkpoint & CASAN Gate:
+
+| Thời Điểm | Checkpoint | Tiêu Chí Đạt Bắt Buộc | Trách Nhiệm |
+| :--- | :--- | :--- | :--- |
+| **23/08 (CN - 17:00)** | ✅ **Checkpoint 1 (Contracts & Fakes)** | 100% DTO và Fake Services (`FakeProvider`, `FakeToolExecutor`, `FakeClock`) tạo xong; `pytest` pass; 0 team bị block | Cả 3 Team |
+| **28/08 (T6 - 17:00)** | ✅ **Checkpoint 2 (Services & Sub-widgets)** | Tách xong 100% các God Files (`chat_panel.py`, `co4e_tab.py`, `folder_tab.py`, `monitoring_tab.py`, `schedule_task_tab.py`, `settings_dialog.py`); 0 circular import | Cả 3 Team |
+| **30/08 (CN - 17:00)** | 🏁 **CASAN Verification Gate** | Chạy thành công đồng thời cả 3 checks: **CASAN Check 1** (Security), **CASAN Check 2** (LOC <400), **CASAN Check 3** (Import Guard) | Team Nam (Check 1)<br>Team Hoa (Check 2)<br>Team Duy (Check 3) |
+| **31/08 (T2 - 15:00)** | 🎉 **Final Release Smoke Test** | Suite test (>81 tests) pass 100%; E2E smoke test 5 luồng chính hoạt động ổn định trên `main` | **Team Duy** (Chủ trì) & 3 Team |
+
+---
+
+### 📌 VI. MÔ TẢ CHI TIẾT 10 EPIC (R01 ➔ R10)
+
+> [!TIP]
+> 📋 Toàn bộ hệ thống checklist chi tiết từng đầu việc nhỏ (`R01-T01` ➔ `R10-T05`), checklist tiến độ theo ngày và tiêu chuẩn Definition of Done (DoD) đã được tách thành tài liệu theo dõi độc lập tại file **`Refactoring_Checklist.md`**.
+
+---
+
+#### 🔹 R01: Architecture Foundation & Characterization (Nền Tảng Kiến Trúc & Test Bảo Vệ)
+* **Ý nghĩa & Mục tiêu**: Thiết lập luật phụ thuộc kiến trúc (Dependency Rules), xây dựng bộ fixtures/test doubles giả lập (`FakeProvider`, `FakeToolExecutor`) không phụ thuộc UI/mạng, và dựng script chặn vi phạm kiến trúc trên CI trước khi bất kỳ ai di chuyển mã nguồn.
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì ADR & Test Doubles) + Cả 3 Team.
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R01**:
+  1. **R01-T01: Soạn thảo Kiến trúc ADR (Layered Architecture ADR)**:
+     - Tạo `docs/architecture/ADR-001-layered-architecture.md` định rõ quy tắc 4 tầng: Presentation ➔ Application ➔ Domain ➔ Infrastructure.
+     - Quy định rõ ràng: `domain/` và `application/` chỉ chứa Pure Python, không chứa logic UI hoặc import `PySide6`.
+  2. **R01-T02: Xây dựng Bộ Fixtures & Test Doubles Offline (`tests/fakes/`)**:
+     - `tests/fakes/fake_provider.py`: Mock `BaseProvider`, trả về streaming text chunk và tool call events có thể kiểm soát được trong unit test.
+     - `tests/fakes/fake_tool_executor.py`: Mock bộ thực thi tool, trả về dummy result (đọc file, chạy lệnh) mà không can thiệp vào hệ thống tệp thật.
+     - Tiêu chuẩn: Unit test chạy hoàn tất < 1 giây, hoàn toàn độc lập với Qt GUI và network.
+  3. **R01-T03: Xây dựng Script Phân Tích AST Chặn Vi Phạm Kiến Trúc (`scripts/check_imports.py`)**:
+     - Dùng module `ast` quét toàn bộ file trong `domain/` và `application/`.
+     - Chặn các lệnh `import PySide6`, `import PyQt*`, `import app`.
+     - Tích hợp vào CI pipeline và Git pre-commit hook.
+  4. **R01-T04: Viết Characterization Tests cho Luồng Runtime Cốt Lõi (`tests/characterization/`)**:
+     - Tạo `tests/characterization/test_run_cowork.py`: Chụp snapshot hành vi hiện tại của hàm `core/chat_agent.py::run_cowork` (cách nhận input, gọi tool, tạo prompt).
+     - Đảm bảo khi tách sang `ConversationApplicationService` thì hành vi logic không bị sai lệch.
+  5. **R01-T05: Lập Danh Mục & Cô Lập Mã Nguồn Dormant/Dead Code (`docs/architecture/dormant-code.md`)**:
+     - Rà soát các module không còn active (như `LoginDialog`, `account` legacy) và đánh dấu cô lập, không để ảnh hưởng tới luồng tái cấu trúc chính.
+
+---
+
+#### 🔹 R02: Configuration, Secrets & Persistence (Cấu Hình Atomic & Bảo Mật Keyring)
+* **Ý nghĩa & Mục tiêu**: Chuyển đổi cơ chế lưu trữ `config.py` sang ghi tệp an toàn (Atomic Write chống hỏng file khi crash), tạo Typed Settings Facades và đưa toàn bộ API Key/Token lưu plaintext sang OS Keyring (`SecretStore`).
+* **Team chịu trách nhiệm**: 🟣 **Team Nam** (Chủ trì).
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R02**:
+  1. **R02-T01: Xây dựng Tiện Ích Ghi File Nguyên Tử (`AtomicJsonFile`)**:
+     - Tạo `infrastructure/persistence/json/atomic_json_file.py`: Ghi dữ liệu ra file tạm (`.tmp`), gọi `os.fsync()`, sau đó dùng `os.replace()` để thay thế file đích một cách an toàn.
+     - Thêm cơ chế tự động tạo bản sao lưu (`.bak`) khi phát hiện file JSON bị corrupt.
+  2. **R02-T02: Tái cấu trúc Kho Cấu Hình `ConfigRepository`**:
+     - Tạo `infrastructure/config/config_repository.py`: Đóng gói `config.py::AppConfig`, loại bỏ biến global dùng chung, chuyển sang Repository pattern có thread-safe lock.
+  3. **R02-T03: Xây dựng Typed Settings Facades Độc Lập**:
+     - Tạo `infrastructure/config/settings_facade.py`: Chia nhỏ cấu hình thành các dataclass định kiểu rõ ràng (`ProviderSettings`, `RoutingSettings`, `GeneralSettings`, `SecuritySettings`) thay vì truy xuất dictionary tự do.
+  4. **R02-T04: Định nghĩa Interface `SecretStore` & Cài đặt `KeyringAdapter`**:
+     - Tạo `infrastructure/secrets/keyring_adapter.py`: Sử dụng thư viện `keyring` của Python để lưu và đọc API Keys/Tokens từ Windows Credential Manager / macOS Keychain / Linux Secret Service.
+     - Thêm `tests/fakes/fake_keyring.py` để test môi trường CI không có UI desktop.
+  5. **R02-T05: Di Chuyển API Keys của Các Provider Sang `SecretStore`**:
+     - Xóa việc lưu plaintext `openai_api_key`, `anthropic_api_key`, `fpt_api_key` trong `config.json`.
+     - Tự động di chuyển (migrate) key cũ vào Keyring khi khởi động lần đầu.
+  6. **R02-T06: Chuẩn Hóa JSON Schema Versioning & Recovery Policy**:
+     - Bổ sung trường `schema_version` vào mọi file dữ liệu JSON (projects, tasks, routing assessment). Tự động chạy hàm migrate schema khi có phiên bản mới.
+
+---
+
+#### 🔹 R03: Model Providers & Routing (Hợp Nhất Nhà Cung Cấp & Bộ Định Tuyến Mô Hình)
+* **Ý nghĩa & Mục tiêu**: Xóa bỏ sự phân tán logic định tuyến (hiện đang lặp lại ở `ui/chat_panel.py#L638`, `ui/co4e_tab.py`, `ui/folder_tab.py`) thành một `RoutingApplicationService` duy nhất; chuẩn hóa danh mục nhà cung cấp mô hình qua `ProviderDescriptor`.
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì).
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R03**:
+  1. **R03-T01: Xây dựng Bộ Contract Tests Chuẩn Hóa cho Model Providers**:
+     - Tạo `tests/contracts/test_providers.py`: Kiểm thử hợp đồng cho mọi provider (OpenAI, Anthropic, Ollama, FPT Gateway) để đảm bảo cùng tuân thủ interface `generate()`, `stream()`, `count_tokens()`.
+  2. **R03-T02: Định nghĩa `ProviderDescriptor` & Xây dựng `ProviderRegistry`**:
+     - Tạo `domain/models/provider_descriptor.py`: Dataclass định nghĩa metadata nhà cung cấp (id, name, models list, context length, pricing, required auth).
+     - Tạo `infrastructure/providers/provider_registry.py`: Registry đăng ký tập trung tất cả providers, hỗ trợ tra cứu động theo model ID.
+  3. **R03-T03: Xây dựng Dịch Vụ Định Tuyến `RoutingApplicationService` (Pure Python)**:
+     - Tạo `application/model_routing/routing_application_service.py` từ `core/routing/`: Điều phối 4 chế độ định tuyến (Off, Auto/Cost-effective, Manual, Fallback).
+     - Độc lập 100% với PySide6 UI, cho phép kiểm thử tự động toàn bộ rule routing mà không cần bật màn hình.
+  4. **R03-T04: Hợp Nhất Luồng Định Tuyến từ `ui/chat_panel.py#L638`**:
+     - Xóa bỏ logic routing sao chép trong `ui/chat_panel.py`, chuyển sang gọi trực tiếp qua `RoutingApplicationService`.
+  5. **R03-T05: Hợp Nhất Luồng Định Tuyến từ `ui/co4e_tab.py` & `ui/folder_tab.py`**:
+     - Chuyển đổi mọi lời gọi định tuyến mô hình trong Co4E Node Execution và AI File Editor sang dùng chung `RoutingApplicationService`.
+  6. **R03-T06: Tách Bóc Telemetry & Token Usage Thành `UsageEventSink`**:
+     - Tạo `infrastructure/telemetry/usage_sink.py`: Tách logic ghi nhận số lượng token và chi phí ra khỏi Provider, biến thành Event Subscriber lắng nghe sự kiện từ Application Service.
+
+---
+
+#### 🔹 R04: Agent Runtime & Conversation Application Service (Vòng Đời Turn Chat & Agent Engine)
+* **Ý nghĩa & Mục tiêu**: Tách toàn bộ vòng đời thực thi 1 lượt chat (Turn) ra khỏi PySide6 UI; đóng gói dữ liệu đầu vào thành snapshot bất biến `ConversationExecutionRequest` và trả về luồng sự kiện `AgentEvent` có định kiểu.
+* **Team chịu trách nhiệm**: 🔵 **Team Duy** (Chủ trì).
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R04**:
+  1. **R04-T01: Định nghĩa Immutable Snapshot `ConversationExecutionRequest`**:
+     - Tạo `domain/agents/conversation_execution_request.py`: Chứa đầy đủ context của 1 lượt chạy (turn id, session id, user prompt, attachments, model config, tool capability scope, instructions).
+     - Dữ liệu bất biến (frozen dataclass), bảo đảm trong khi agent đang chạy, người dùng có đổi lựa chọn trên UI thì turn cũng không bị ảnh hưởng.
+  2. **R04-T02: Chuẩn hóa Hệ Thống Sự Kiện Luồng `AgentEvent`**:
+     - Tạo `domain/agents/agent_event.py`: Định nghĩa các sự kiện có kiểu dữ liệu mạnh: `TextChunkEvent`, `ToolCallStartedEvent`, `ToolCallFinishedEvent`, `TurnCompletedEvent`, `ErrorEvent`.
+  3. **R04-T03: Xây dựng `ConversationApplicationService`**:
+     - Tạo `application/conversations/conversation_application_service.py`: Tách logic từ `core/chat_agent.py`. Điều phối toàn bộ vòng đời của turn: chuẩn bị prompt ➔ gọi provider ➔ lắng nghe stream ➔ dispatch tool call ➔ tổng hợp câu trả lời ➔ lưu lịch sử hội thoại.
+  4. **R04-T04: Chuyển đổi `ui/cowork_tab.py::build_job`**:
+     - Thay thế logic tạo job phức tạp trong UI bằng việc khởi tạo `ConversationExecutionRequest` và gửi tới `ConversationApplicationService`.
+  5. **R04-T05: Đồng Bộ Hóa `core/task_executors.py` sang dùng chung Runtime**:
+     - Đưa việc thực thi chat của Scheduled Task Runner về dùng chung `ConversationApplicationService`, xoá bỏ duplicate agent runner.
+
+---
+
+#### 🔹 R05: Tool, MCP & Connector Policy (Quản Lý Công Cụ, MCP & Cổng Kiểm Soát Quyền)
+* **Ý nghĩa & Mục tiêu**: Xóa bỏ giant if/elif dispatcher trong `core/tools.py`; đưa tất cả Built-in tools, MCP tools (`core/mcp_client.py`) và REST connectors (`core/ext_connectors.py`) qua cùng một cổng phân loại rủi ro (`ToolCapability`) và cổng phê duyệt bảo mật (`ToolPolicyGateway`).
+* **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Chủ trì) + Team Duy.
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R05**:
+  1. **R05-T01: Định nghĩa `ToolDescriptor`, `ToolCapability` & `ToolRegistry`**:
+     - Tạo `domain/tools/tool_descriptor.py`: Mô tả metadata công cụ (tên, mô tả, JSON Schema parameters, độ rủi ro READ / WRITE / EXECUTE / NETWORK).
+     - Tạo `domain/tools/tool_registry.py`: Kho đăng ký tập trung cho mọi công cụ hệ thống.
+  2. **R05-T02: Phân Rã Monolithic `core/tools.py` Thành Các Module Riêng Biệt**:
+     - Tạo `infrastructure/filesystem/file_tools.py` (read, write, edit, list_dir, grep).
+     - Tạo `infrastructure/filesystem/command_tools.py` (run_command, manage_task).
+     - Tạo `infrastructure/filesystem/fetch_tools.py` (read_url_content, search_web).
+  3. **R05-T03: Xây dựng Cổng Kiểm Soát Quyền `ToolPolicyGateway`**:
+     - Tạo `application/conversations/tool_policy_gateway.py`: Kiểm tra chính sách trước khi cho phép chạy tool (ALLOW, CONFIRM_REQUIRED, DENY). Khi cần xác nhận từ người dùng, phát tín hiệu yêu cầu phê duyệt thay vì gọi dialog trực tiếp trong hàm chạy ngầm.
+  4. **R05-T04: Chuẩn Hóa MCP Tools Qua `ToolPolicyGateway`**:
+     - Bọc các tool từ MCP Server (`core/mcp_client.py`) thành các `ToolDescriptor` tương thích để áp dụng cùng một chính sách an ninh như built-in tools.
+  5. **R05-T05: Xây dựng `McpToolSourceManager` Quản Lý Tiến Trình MCP**:
+     - Tạo `infrastructure/mcp/mcp_source_manager.py`: Quản lý vòng đời tiến trình MCP con (start, heartbeat, timeout, restart khi crash, graceful shutdown).
+
+---
+
+#### 🔹 R06: Workspace, Filesystem & History Isolation (Cô Lập Không Gian Làm Việc & Quản Lý Tệp)
+* **Ý nghĩa & Mục tiêu**: Loại bỏ biến toàn cục `active_project_id` trong `state.py` gây xung đột dữ liệu giữa các luồng chạy ngầm; đóng gói không gian làm việc thành `WorkspaceSession` bất biến theo turn; bảo vệ an toàn đường dẫn tệp.
+* **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Chủ trì).
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R06**:
+  1. **R06-T01: Định nghĩa `WorkspaceSession` Đóng Gói Ngữ Cảnh**:
+     - Tạo `domain/workspaces/workspace_session.py`: Đối tượng snapshot chứa `project_id`, `workspace_root_path`, `sandbox_dir`, `allowed_paths`. Đảm bảo agent chỉ được đọc/ghi trong thư mục được cấp phép.
+  2. **R06-T02: Xây dựng `WorkspaceRepository` & `ConversationRepository`**:
+     - Tạo `infrastructure/persistence/json/workspace_repository_impl.py`: Quản lý danh sách dự án, cấu hình dự án (`core/projects.py`) bằng `AtomicJsonFile`.
+     - Lưu trữ và phân trang lịch sử chat (`core/history.py`) độc lập với UI sidebar.
+  3. **R06-T03: Xây dựng `ExecutionWorkspace` Quản Lý Tệp Output/Scratch**:
+     - Tạo `infrastructure/filesystem/execution_workspace.py`: Tách biệt thư mục workspace chính và thư mục scratch/output tạm thời của từng turn chạy.
+  4. **R06-T04: Khắc phục Race Condition trong `WorkspaceTab`**:
+     - Viết lại hàm `_load_current` trong `ui/workspace_tab.py`: Đồng bộ dữ liệu bằng session id thay vì đọc biến toàn cục `AppContext`.
+  5. **R06-T05: Xây dựng `FileWorkspaceService` cho File Explorer & AI Editor**:
+     - Tạo `application/workspaces/file_workspace_service.py`: Cung cấp API đọc cây thư mục, xem trước file đa định dạng, áp dụng AI code diffs an toàn.
+
+---
+
+#### 🔹 R07: Scheduling & Workflow Runtime (Bộ Lập Lịch & Động Cơ Quy Trình)
+* **Ý nghĩa & Mục tiêu**: Tách biệt hoàn toàn tầng lưu trữ Task (`core/tasks.py`) và thuật toán tính toán lịch (`ScheduleCalculator`) khỏi `QTimer` trong `core/task_scheduler.py#L20`; xây dựng `TaskApplicationService` và `Co4EWorkflowService`.
+* **Team chịu trách nhiệm**: 🟢 **Team Hoa** (Task Scheduling) + 🟣 **Team Nam** (Co4E Workflows).
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R07**:
+  1. **R07-T01: Tách `TaskRepository` Lưu Trữ JSON Độc Lập**:
+     - Tạo `infrastructure/persistence/json/task_repository_impl.py`: Đọc/ghi danh sách công việc (`tasks.json`) qua `AtomicJsonFile` với locking bảo vệ khi nhiều luồng cùng truy cập.
+  2. **R07-T02: Xây dựng Thuật Toán Tính Lịch `ScheduleCalculator`**:
+     - Tạo `domain/tasks/schedule_calculator.py`: Tính toán thời điểm chạy kế tiếp cho các dạng lịch: One-time, Interval, Daily, Weekly, Monthly, Cron Expression. Hoàn toàn là Pure Python, có unit test bao phủ 100%.
+  3. **R07-T03: Xây dựng Adapter `QtSchedulerClock`**:
+     - Tạo `platform/qt/qt_scheduler_clock.py`: Bọc `QTimer` vào Clock Interface. Cho phép trong unit test có thể thay thế bằng `FakeClock` để tua nhanh thời gian mà không cần chờ đợi.
+  4. **R07-T04: Xây dựng `TaskApplicationService` (Pure Python)**:
+     - Tạo `application/scheduling/task_application_service.py`: Điều phối toàn bộ nghiệp vụ quản lý task: CRUD task, kích hoạt chạy ngay (`run_now`), sao chép task, tạm dừng, xóa hàng loạt.
+  5. **R07-T05: Xây dựng `AiTaskPlannerService` Tạo Task Tự Động**:
+     - Tạo `application/scheduling/ai_task_planner_service.py`: Phân tích câu lệnh tự nhiên của người dùng để sinh ra cấu hình task và lịch chạy tương ứng.
+  6. **R07-T06: Xây dựng `Co4EWorkflowService` Động Cơ Quy Trình Node**:
+     - Tạo `application/workflows/co4e_workflow_service.py`: Tách logic thực thi đồ thị node từ `core/co4e_run_manager.py`. Quản lý state của từng node, truyền dữ liệu giữa các node và xử lý retry/error.
+
+---
+
+#### 🔹 R08: UI/Application Separation (Phân Rã Toàn Diện Các God Widgets)
+* **Ý nghĩa & Mục tiêu**: Tách nhỏ toàn bộ các màn hình khổng lồ (>1.500 - 2.000 dòng) thành các widget con chuyên trách, đảm bảo mỗi file < 400 dòng và chỉ đảm nhận hiển thị / bắt sự kiện giao diện.
+* **Team chịu trách nhiệm**: **Cả 3 Team** (Mỗi team phụ trách phân hệ của mình):
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R08**:
+  1. **🔵 Team Duy – Tách `ChatPanel` (`ui/chat_panel.py` >1.800 dòng) thành 6 widgets con**:
+     - `R08-T01`: `presentation/chat/chat_history_widget.py` (Render bong bóng chat, streaming markdown, tool call cards).
+     - `R08-T02`: `presentation/chat/composer_widget.py` (Ô nhập liệu text, phím tắt Ctrl+Enter, auto-resize).
+     - `R08-T03`: `presentation/chat/attachment_picker.py` (Widget chọn file, ảnh, folder đính kèm).
+     - `R08-T04`: `presentation/chat/audio_recorder_widget.py` (Widget ghi âm giọng nói & chuyển thành văn bản).
+     - `R08-T05`: `presentation/chat/chat_output_panel.py` (Panel hiển thị file output sinh ra trong turn).
+     - `R08-T06`: `presentation/chat/chat_panel.py` (Shell container điều phối các widget con & `Floating HelpAgent`).
+  2. **🟣 Team Nam – Tách `SettingsDialog`, `MonitoringTab`, `Co4ETab` & Shell `MainWindow`**:
+     - `R08-T07`: `presentation/settings/` ➔ Tách thành `provider_settings_widget.py`, `connector_settings_widget.py`, `routing_settings_widget.py`, `general_settings_widget.py`.
+     - `R08-T08`: `presentation/monitoring/` ➔ Tách 8 tab con thành từng file: `overview_tab.py`, `sandbox_status_tab.py`, `security_events_tab.py`, `mcp_history_tab.py`, `action_logs_tab.py`, `agents_admin_tab.py`, `security_settings_tab.py`, `tools_admin_tab.py`.
+     - `R08-T09`: `presentation/co4e/` ➔ Tách thành `co4e_canvas_widget.py`, `node_property_panel.py`, `co4e_run_control_widget.py`, `co4e_chat_view.py`.
+     - `R08-T10`: `presentation/shell/` ➔ Xây dựng `bootstrap.py` (Composition Root) và tách `app.py::MainWindow` thành `main_window.py`, `tray_manager.py`, `lifecycle_coordinator.py`.
+  3. **🟢 Team Hoa – Tách `ScheduleTaskTab`, `FolderTab`, `DashboardTab` & `StructureGraphView`**:
+     - `R08-T11`: `presentation/scheduling/` ➔ Tách thành `kanban_board_widget.py` (7 cột kéo thả), `calendar_view_widget.py`, `ai_task_creator_dialog.py`, `ai_task_import_dialog.py`.
+     - `R08-T12`: `presentation/folder/` ➔ Tách thành `workspace_file_tree.py`, `document_preview_manager.py` (PDF/Word/Excel/Images), `ai_file_editor_dialog.py`.
+     - `R08-T13`: `presentation/dashboard/` ➔ Tách thành `token_usage_card_widget.py`, `usage_chart_widget.py`, `habits_widget.py`.
+     - `R08-T14`: `presentation/graph/` ➔ Tách thành `structure_graph_view.py` & `graph_qa_widget.py`.
+
+---
+
+#### 🔹 R09: Security Runtime, Sandbox & Observability (An Ninh Runtime, Sandbox & Giám Sát)
+* **Ý nghĩa & Mục tiêu**: Phân biệt rõ ràng giữa quy tắc bảo mật bắt buộc (Enforced Deterministic Rules) và các gợi ý bảo mật từ AI (Advisory Guardrails); loại bỏ circular imports; chuẩn hóa định dạng log kiểm toán canonical.
+* **Team chịu trách nhiệm**: 🟣 **Team Nam** (Chủ trì) + 🔵 **Team Duy**.
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R09**:
+  1. **R09-T01: Chuẩn Hóa Security Policy Model**:
+     - Tạo `docs/architecture/security-policy.md`: Phân định ranh giới giữa bộ lọc quy tắc cứng (regex cấm xóa tệp hệ thống, cấm truy cập thư mục ngoài sandbox) và bộ đánh giá rủi ro mềm từ LLM.
+  2. **R09-T02: Xử Lý Triệt Để Circular Import `model_pricing` ↔ `usage_tracker`**:
+     - Tách DTO giá mô hình (`ModelPricing`) vào `domain/models/` để cả `model_pricing.py` và `usage_tracker.py` cùng import xuôi mà không import vòng tròn.
+  3. **R09-T03: Xử Lý Triệt Để Circular Import `agent_security` ↔ `agent_security_alert`**:
+     - Tách các enum và event cảnh báo bảo mật (`SecurityAlertEvent`) sang `domain/security/` để xoá hoàn toàn import chéo.
+  4. **R09-T04: Xây Dựng `CanonicalAuditLogger` Thống Nhất Định Dạng Log**:
+     - Tạo `infrastructure/telemetry/audit_logger.py`: Chuẩn hóa schema nhật ký (timestamp UTC, actor, action, resource, outcome, latency) ghi ra file JSON Lines an toàn.
+  5. **R09-T05: Xây Dựng `MonitoringQueryService` Truy Vấn Dữ Liệu Read-Only**:
+     - Tạo `application/monitoring/monitoring_query_service.py`: Cung cấp API truy vấn log kiểm toán có phân trang, lọc theo thời gian, lọc theo mức độ nghiêm trọng (severity).
+  6. **R09-T06: Chuẩn Hóa Ma Trận Năng Lực Sandbox Trên Từng Hệ Điều Hành**:
+     - Tạo `infrastructure/sandbox/sandbox_capabilities.py`: Tách biệt cơ chế cách ly thực tế: Windows (Job Objects / AppContainer), Linux (Namespaces / Bubblewrap), macOS (Sandbox-exec).
+
+---
+
+#### 🔹 R10: Testing, Packaging & Contributor Experience (Hệ Thống Kiểm Thử & Tài Liệu Đóng Góp)
+* **Ý nghĩa & Mục tiêu**: Đây là **Task trọng tâm cốt lõi của Team Duy (Tech Lead)** nhằm thiết lập hệ thống bảo vệ toàn diện cho dự án: xây dựng tháp kiểm thử 4 tầng (Unit, Contract, Integration, E2E Smoke), cài đặt CI Quality Gate tự động, soạn thảo bộ công thức Contributor Recipes và thực hiện kiểm thử khói tổng thể trước khi release.
+* **Team chịu trách nhiệm**: 🔵 **Team Duy (Chủ Trì Chính - Task Trọng Tâm Của Team Duy)**.
+* **Chi Tiết Cụ Thể Các Task Cần Làm Trong R10**:
+  1. **R10-T01: Xây dựng Tháp Kiểm Thử Phân Tầng (Test Pyramid Architecture - `tests/`)**:
+     - `tests/unit/`: Kiểm thử các logic độc lập không I/O (Domain entities, `ScheduleCalculator`, `AtomicJsonFile`, parsing). Thời gian chạy: < 0.05s/test.
+     - `tests/contracts/`: Bộ test xác thực interface chuẩn của Provider API (`test_providers.py`) và Tool Handler (`test_tools.py`) để các provider mới chỉ cần pass contract là cắm vào được ngay.
+     - `tests/integration/`: Kiểm thử phối hợp nhiều tầng không cần UI (`test_chat_flow.py`, `test_workflow_execution.py`, `test_task_scheduling.py`).
+     - `tests/fakes/`: Thư viện test doubles tái sử dụng cho cả 3 team (`FakeProvider`, `FakeToolExecutor`, `FakeClock`, `FakeKeyringAdapter`).
+  2. **R10-T02: Xây Dựng Bộ Script CI Quality Gate Tự Động (`scripts/`)**:
+     - `scripts/check_imports.py`: Script phân tích AST kiểm tra chặn 100% import `PySide6` trong `domain/` và `application/`.
+     - `scripts/check_loc.py`: Script quét LOC tự động cảnh báo lỗi nếu có bất kỳ file nào > 400 dòng code.
+     - `scripts/audit_security.py`: Script quét phát hiện secret/API Key plaintext trong toàn bộ codebase.
+     - `scripts/run_quality_gate.py`: Script tổng hợp chạy 1 lệnh duy nhất để kiểm tra toàn bộ tiêu chí CASAN Gate trước khi merge PR.
+  3. **R10-T03: Cập Nhật Tài Liệu Dự Án & Hướng Dẫn Thiết Lập (`README.md`, `START_CONTRIBUTING.md`)**:
+     - Cập nhật sơ đồ kiến trúc 4 tầng chuẩn (Presentation ➔ Application ➔ Domain ➔ Infrastructure).
+     - Hướng dẫn cài đặt môi trường phát triển local, chạy test và cấu hình Git pre-commit hook để chạy script kiểm tra tự động.
+  4. **R10-T04: Soạn Thảo Bộ Contributor Recipes (`docs/governance/contributor-recipes.md`)**:
+     - Hướng dẫn mẫu từng bước kèm code mẫu:
+       - *Recipe 1*: "Cách thêm một Model Provider mới" (Khai báo `ProviderDescriptor`, tạo Adapter trong `infrastructure/providers/`, chạy Contract Test).
+       - *Recipe 2*: "Cách thêm một Built-in Tool hoặc MCP Tool mới" (Khai báo `ToolDescriptor`, đăng ký capability, cấu hình `ToolPolicyGateway`).
+       - *Recipe 3*: "Cách thêm một Màn hình / Sub-widget mới" (Tạo Widget trong `presentation/`, kết nối Application Service qua Qt Signals, tuân thủ giới hạn <400 LOC).
+  5. **R10-T05: Bộ Kiểm Thử Khói Phát Hành E2E (Release Smoke Test - `tests/e2e/test_smoke.py`)**:
+     - Khởi động ứng dụng qua `bootstrap.py` ở chế độ headless Qt offscreen và thực thi tự động 5 kịch bản chính:
+       1. Khởi tạo chat session, gửi tin nhắn và nhận stream event từ `FakeProvider`.
+       2. Tạo mới task trên Kanban, trigger chạy task và xác nhận ghi log.
+       3. Mở File Explorer, tạo file tạm trong `WorkspaceSession` và đọc nội dung an toàn.
+       4. Tạo workflow 2 node trên Co4E Studio và kích hoạt chạy thử.
+       5. Mở Settings Dialog, cấu hình mock provider API Key và kiểm tra lưu thành công vào `SecretStore`.
+     - Tiêu chí hoàn thành: 100% 5 kịch bản E2E pass, không xung đột luồng và ứng dụng thoát sạch sẽ.
+
+---
+
+## 📊 VII. BẢNG PHÂN CÔNG, KPI & QUY TRÌNH PHỐI HỢP LIÊN TEAM
+
+### 1. Bảng Phân Công & KPI Đo Lường Thành Công
+
+| Team | Phân Hệ Chính | Trách Nhiệm Cụ Thể | KPI Đo Lường Hoàn Thành |
+| :--- | :--- | :--- | :--- |
+| **🔵 Team Duy**<br>*(Tech Lead)* | **Core AI, Routing & Testing** | • R01 ADR & Runtime test doubles<br>• R03 Provider Registry & Unified Routing<br>• R04 ConversationApplicationService<br>• R08 Tách ChatPanel thành 5 sub-widgets<br>• **R10 Testing Pyramid, Contributor Recipes & Smoke Test**<br>• Chủ trì CASAN Check 3 | • 0 PySide6 import trong `application/conversations` và `application/model_routing`<br>• 0 file >400 dòng trong `presentation/chat/`<br>• Bộ test pyramid >81 tests pass 100%<br>• CASAN Check 3 PASS |
+| **🟣 Team Nam** | **Workflows & Governance** | • R02 Atomic Config & Keyring SecretStore<br>• R08 Tách Settings (4 sections) & Monitoring (7 tabs)<br>• R08 Tách Co4E Tab & Co4EWorkflowService<br>• Composition Root (`bootstrap.py`) & MainWindow Shell<br>• R09 Security Policy Model & Fix Circular Imports<br>• Chủ trì CASAN Check 1 | • 0 plaintext credential/API Key trong JSON<br>• 0 file >400 dòng trong `presentation/co4e/`, `monitoring/`, `settings/`<br>• CASAN Check 1 PASS |
+| **🟢 Team Hoa** | **Workspace & Tools** | • R05 ToolRegistry & phân rã `core/tools.py`<br>• R06 WorkspaceSession & isolation<br>• R07 TaskApplicationService & QtSchedulerClock<br>• R08 Tách FolderTab, ScheduleTaskTab, DashboardTab, Graph<br>• Chủ trì CASAN Check 2 | • 0 file >400 dòng trong `presentation/folder/`, `scheduling/`, `dashboard/`, `graph/`<br>• Task Scheduler chạy độc lập không phụ thuộc Qt GUI<br>• CASAN Check 2 PASS |
+
+---
+
+### 2. Quy Trình Phối Hợp & Phòng Ngừa Xung Đột (Collaboration Protocol)
+
+1. **Quy tắc Branching & PR:**
+   * Mỗi team làm việc trên prefix branch riêng biệt:
+     * Team Duy: `duy/chat-routing-tests-*`
+     * Team Nam: `nam/workflow-governance-*`
+     * Team Hoa: `hoa/workspace-tools-*`
+   * Mọi PR trước khi merge vào nhánh chung (`develop`/`main`) phải kèm theo unit tests và đảm bảo suite test hiện tại không bị regression.
+2. **Quy tắc Mocking liên team (Không chờ đợi):**
+   * Nếu Team Duy (Chat) cần kích hoạt task ➔ gọi qua interface `TaskApplicationService` (dùng `FakeTaskApplicationService` trong test do Team Hoa cung cấp DTO).
+   * Nếu Team Hoa (File Editor / Graph RAG) cần gọi model ➔ gọi qua `RoutingApplicationService` / `FakeProvider` do Team Duy chốt DTO từ Ngày 1.
+   * Nếu Team Nam (Co4E Runner) cần gọi Tool ➔ gọi qua `ToolPolicyGateway` do Team Hoa cung cấp.
+   * Không team nào được chặn (block) tiến độ của team khác.
+3. **Tiêu chuẩn hoàn thành PR (Definition of Done - DoD):**
+   * File mới hoặc sau refactor không vượt quá **400 dòng code**.
+   * Không import `PySide6` trong `domain/` và `application/`.
+   * Credentials/API Keys được lưu trữ qua `SecretStore` (Keyring), không lưu plaintext trong `config.json`.
+   * **Bắt buộc comment code bằng Tiếng Anh (English In-code Comments)**: Mỗi dòng hoặc khối code sửa đổi/thêm mới phải có chú thích bằng tiếng Anh giải thích rõ mục đích và lý do kỹ thuật.
+   * **Ghi nhận thời gian thực hiện (Task Start/End Timestamps)**: Mọi task khi bắt đầu phải log ngày giờ Start, khi xong phải log ngày giờ End vào `Refactoring_Checklist.md` và PR description.
+   * Chi tiết đối chiếu tại checklist `Refactoring_Checklist.md`.
+
+> [!IMPORTANT]
+> ### 📝 QUY ĐỊNH BẮT BUỘC KHI CODE & THEO DÕI TIẾN ĐỘ:
+> 1. **In-Code Comments in English**: Ở mỗi dòng hoặc đoạn code được chỉnh sửa/bóc tách, lập trình viên **bắt buộc phải viết comment bằng tiếng Anh** giải thích rõ logic xử lý và lý do kiến trúc (rationale). Ví dụ:
+>    ```python
+>    # Extract immutable snapshot request to decouple execution lifecycle from PySide6 UI
+>    request = ConversationExecutionRequest.from_composer_state(...)
+>    ```
+> 2. **Task Start/End Timestamps**: 
+>    - Khi bắt đầu task ➔ Ghi nhận thời gian: `Start: YYYY-MM-DD HH:mm`.
+>    - Khi hoàn tất & test pass ➔ Ghi nhận thời gian: `End: YYYY-MM-DD HH:mm`.
+>    - Ghi nhận đầy đủ vào checklist theo dõi tại `Refactoring_Checklist.md` để đảm bảo tính minh bạch và tiến độ của cả 3 team.
+
+
+
+## 🚫 VIII. NHỮNG GÌ KHÔNG LÀM (Anti-patterns)
+
+> [!WARNING]
+> Để tránh over-engineering và rewrite không kiểm soát, nhóm phải tuân thủ:
+
+- ❌ **Không di chuyển file ngay** trước khi có contract và test bảo vệ.
+- ❌ **Không dựng event bus toàn ứng dụng** hoặc DI framework phức tạp.
+- ❌ **Không bắt mọi class phải có interface** — chỉ introduce contract tại seam có nhiều caller.
+- ❌ **Không rewrite đồng thời** Cowork + Co4E + Folder + Scheduler trong 1 PR.
+- ❌ **Không gọi là "frontend/backend"** — đây là desktop single-process.
+- ❌ **Không unify Flow/Co4E** trước khi semantics được ghi rõ và có contract tests.
+- ❌ **Không xóa candidate dead code** (LoginDialog, account modules) trộn vào PR refactor — phải PR riêng.
+
+---
+
+## 🗺️ IX. BẢN ĐỒ DI CHUYỂN FUNCTION (FUNCTION MIGRATION MAP)
+
+> Dựa trực tiếp từ `function_list.md`. Mỗi function hiện tại được ánh xạ đến file mới sau khi chia nhỏ.
+> **Quy ước**: 🎨 = `presentation/` | 📋 = `application/` | 🧠 = `domain/` | 🔧 = `infrastructure/`
+
+### Dashboard (Section 1 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_refresh_cards()` | `presentation/dashboard/token_usage_card_widget.py` | 🎨 |
+| `_refresh_chart()`, `_chart_prev()`, `_chart_next()`, `_on_gran_changed()` | `presentation/dashboard/usage_chart_widget.py` | 🎨 |
+| `_refresh_budget()`, `_apply_budget()` | `presentation/dashboard/token_usage_card_widget.py` | 🎨 |
+| `_refresh_habits()` | `presentation/dashboard/habits_widget.py` | 🎨 |
+| `_ai_analyze()`, `_apply_saving_strategy()` | `application/monitoring/dashboard_query_service.py` | 📋 |
+| Currency Picker | `presentation/dashboard/token_usage_card_widget.py` | 🎨 |
+
+### Schedule Task (Section 2 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_build_kanban()`, `_render_kanban()`, `_on_task_dropped()` | `presentation/scheduling/kanban_board_widget.py` | 🎨 |
+| `_on_card_double_click()`, `_on_card_right_click()`, `_bulk_delete_menu()` | `presentation/scheduling/kanban_board_widget.py` | 🎨 |
+| `_search_tasks()`, `_filter_by_type()` | `presentation/scheduling/kanban_board_widget.py` | 🎨 |
+| `_run_now(task_id)`, `_duplicate_task()`, `_pause_task()`, `_delete_task()` | `application/scheduling/task_application_service.py` | 📋 |
+| `_view_logs(task_id)` | `presentation/scheduling/kanban_board_widget.py` → gọi MonitoringQueryService | 🎨 |
+| `_build_calendar()`, `_shift()`, `add_task_on_date()`, `edit_task()` | `presentation/scheduling/calendar_view_widget.py` | 🎨 |
+| `_open_add_dialog()` | `presentation/scheduling/schedule_task_tab.py` (container) | 🎨 |
+| `_ai_create_task()`, `_ai_pick_files()`, `_generate()`, `_on_planned()`, `_confirm()` | `presentation/scheduling/ai_task_creator_dialog.py` | 🎨 |
+| `_ai_import()`, `_ai_pick_import_files()`, `_generate_import()`, `_on_import_planned()` | `presentation/scheduling/ai_task_import_dialog.py` | 🎨 |
+| AI generation logic | `application/scheduling/ai_task_planner_service.py` | 📋 |
+
+### Workspace / Cowork Chat (Section 3.2.1 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `new_session()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `send_message()` → `_submit_message()` | `presentation/chat/composer_widget.py` (UI trigger) | 🎨 |
+| `_build_job()` → `ConversationExecutionRequest` | `application/conversations/conversation_application_service.py` | 📋 |
+| `_cleanup_turn()`, `_promote_turn_outputs()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `_refresh_outputs_from_disk()`, `_pick_output_folder()` | `presentation/chat/chat_output_panel.py` | 🎨 |
+| `_open_skills_manager()` | `presentation/chat/chat_panel.py` (container) | 🎨 |
+| `refresh_header()` | `presentation/chat/chat_panel.py` (container) | 🎨 |
+| `refresh_agents()` | `presentation/chat/chat_panel.py` (combo widget) | 🎨 |
+| `admin_agent_prompt()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `build_provider()` | `infrastructure/providers/provider_factory.py` | 🔧 |
+| `workspace_dir()` | `domain/workspaces/workspace_session.py` | 🧠 |
+| `_start_watching()`, `_on_file_changed()` | `presentation/chat/chat_output_panel.py` | 🎨 |
+| `_on_turn_started()`, `_on_turn_finished()`, `_on_event(ev)` | `presentation/chat/chat_history_widget.py` (event renderer) | 🎨 |
+| `_compress_messages()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `_apply_routing()` | `application/model_routing/routing_application_service.py` | 📋 |
+| `_on_agent_changed()`, `_note_agent_switch()` | `presentation/chat/chat_panel.py` | 🎨 |
+| `_ensure_conversation()`, `load_conversation()`, `_save_conversation()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `running_session_ids()`, `active_workers()` | `application/conversations/conversation_application_service.py` | 📋 |
+| `send()`, `attach_files()`, `attach_links()` | `presentation/chat/composer_widget.py` | 🎨 |
+| `has_any_queue()`, `_parse_directives()`, `_show_autocomplete()` | `presentation/chat/composer_widget.py` | 🎨 |
+
+### Co4E Workflow Studio (Section 3.2.2 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_build_sidebar()`, `_build_canvas()`, `_build_config_panel()`, `_toggle_config()` | `presentation/co4e/co4e_tab.py` (container) | 🎨 |
+| `_refresh_flows_list()`, `_create_flow()`, `_delete_flow()`, `_duplicate_flow()` | `application/workflows/co4e_workflow_service.py` | 📋 |
+| `_import_flow()`, `_export_flow()` | `application/workflows/co4e_workflow_service.py` | 📋 |
+| `_run_flow()`, `_stop_flow()` | `application/workflows/co4e_workflow_service.py` | 📋 |
+| `_open_flow()` | `presentation/co4e/co4e_tab.py` → gọi canvas | 🎨 |
+| `_refresh_agents_list()`, `_create_agent()`, `_edit_agent()`, `_delete_agent()`, `_toggle_agent_enabled()` | `presentation/co4e/agent_list_panel.py` | 🎨 |
+| `_refresh_skills_list()` | `presentation/co4e/skills_list_panel.py` | 🎨 |
+| `zoom_in()`, `zoom_out()`, `fit_view()` | `presentation/co4e/co4e_canvas_widget.py` | 🎨 |
+| `_add_node()`, `_delete_node()`, `_connect_nodes()`, `_drag_node()`, `_select_node()`, `_activate_node()` | `presentation/co4e/co4e_canvas_widget.py` | 🎨 |
+| `_set_run_mode()`, `_run_step()`, `_on_step_finished()`, `_render_plan()` | `presentation/co4e/co4e_run_control_widget.py` | 🎨 |
+| `_get_flow_chat()`, `_on_chat_event()` | `presentation/co4e/co4e_chat_view.py` | 🎨 |
+
+### Folder / File Explorer (Section 3.2.3 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `set_root()`, `_build_tree_view()` | `presentation/folder/workspace_file_tree.py` | 🎨 |
+| `_open_file()`, `_view_source()`, `_view_html_preview()`, `_view_office_doc()`, `_view_image()` | `presentation/folder/document_preview_manager.py` | 🎨 |
+| `_edit_file()`, `_save_file()`, `_preview_toggle()` | `presentation/folder/workspace_file_tree.py` | 🎨 |
+| `_create_new_file()`, `_create_new_folder()`, `_rename_item()`, `_delete_item()`, `_copy_item()`, `_paste_item()` | `presentation/folder/workspace_file_tree.py` | 🎨 |
+| `refresh_ai_models()` | `presentation/folder/folder_tab.py` (container) | 🎨 |
+| `_ai_send()`, `_ai_discard()`, `_reset_ai_conversation()` | `presentation/folder/ai_file_editor_dialog.py` | 🎨 |
+| `_ai_apply()` | `application/workspaces/file_workspace_service.py` | 📋 |
+| `_ai_apply_routing()` | `application/model_routing/routing_application_service.py` | 📋 |
+
+### Graph RAG (Section 3.2.4 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_build_graph()` | `application/workspaces/graph_index_service.py` | 📋 |
+| `_render_d3_graph()`, `_render_native_graph()`, `_auto_rotate()` | `presentation/graph/structure_graph_view.py` | 🎨 |
+| `_on_node_click()`, `_open_node_path()`, `_refresh_graph()` | `presentation/graph/structure_graph_view.py` | 🎨 |
+| `_search_graph()`, `_filter_by_kind()`, `_zoom_graph()` | `presentation/graph/structure_graph_view.py` | 🎨 |
+| `_ask_question()`, `_on_ask_event()`, `_on_ask_done()` | `presentation/graph/graph_qa_widget.py` | 🎨 |
+| `_candidate_file_paths()`, `_extract_tmp_dir()`, `_clear_extracts()` | `application/workspaces/graph_index_service.py` | 📋 |
+
+### Monitoring (Section 4 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_refresh_overview()`, `_refresh_usage_cards()`, `_refresh_resource_usage()`, `_refresh_recent_activity()` | `presentation/monitoring/overview_tab.py` | 🎨 |
+| `_refresh_sandbox_details()`, `_refresh_permissions()`, `_refresh_audit_log()` | `presentation/monitoring/sandbox_status_tab.py` | 🎨 |
+| `_refresh_budget()`, `_apply_budget()` | `presentation/monitoring/overview_tab.py` | 🎨 |
+| `_refresh_security_events()`, `_filter_security_events()`, `_sort_events()` | `presentation/monitoring/security_events_tab.py` | 🎨 |
+| `_refresh_mcp_calls()`, `_filter_mcp_calls()` | `presentation/monitoring/mcp_history_tab.py` | 🎨 |
+| `_refresh_action_logs()`, `_filter_action_logs()`, `_sort_action_logs()` | `presentation/monitoring/action_logs_tab.py` | 🎨 |
+| `_refresh_agent_status()` | `presentation/monitoring/agent_status_tab.py` | 🎨 |
+| `_toggle_sandbox()`, `_toggle_network_block()`, `_set_resource_limits()`, `_toggle_command_confirm()`, `_manage_permissions()` | `presentation/monitoring/security_settings_tab.py` | 🎨 |
+| Query/refresh data logic | `application/monitoring/monitoring_query_service.py` | 📋 |
+
+### Settings (Section 5 trong function_list.md)
+
+| Function Hiện Tại | File Mới | Tầng |
+| :--- | :--- | :--- |
+| `_on_provider_changed()`, `_load_models()`, `_test_connection()` | `presentation/settings/provider_settings_widget.py` | 🎨 |
+| `_stash_provider_fields()`, `_apply_provider_fields()`, Model List Widget | `presentation/settings/provider_settings_widget.py` | 🎨 |
+| `_add_mcp_server()`, `_edit_mcp_server()`, `_delete_mcp_server()`, `_test_mcp_connection()` | `presentation/settings/connector_settings_widget.py` | 🎨 |
+| MS365, CAD/CAE Connectors | `presentation/settings/connector_settings_widget.py` | 🎨 |
+| `routing_mode`, `routing_policy`, `routing_min_gain`, `routing_timeout`, `routing_interval`, `routing_concurrency`, `routing_judge` | `presentation/settings/routing_settings_widget.py` | 🎨 |
+| Language Picker, `tray_chk`, `notify_chk` | `presentation/settings/general_settings_widget.py` | 🎨 |
+| `_save()` | `application/settings/settings_application_service.py` | 📋 |
+| `attach_tokens`, `attach_files`, `struct_nodes`, `struct_edges` | `presentation/settings/general_settings_widget.py` | 🎨 |
+| Provider test connection (network call) | `infrastructure/providers/provider_factory.py` | 🔧 |
+| MCP test connection (network call) | `infrastructure/mcp/mcp_client.py` | 🔧 |
+
+---
+
+📄 Tài liệu này là bản hợp nhất chính thức. Cập nhật: **14/08/2026** (bổ sung Function Migration Map từ `function_list.md`).

docs/refactor/tin-gui-team-hoa.md

@@ -0,0 +1,68 @@
+# Tin nhắn gửi Team Hoa — 25/08/2026
+
+*Nam (Team Gamma) soạn. Hai việc, không cần trả lời, chỉ cần đọc trước khi
+bắt đầu R07-T03 và R06.*
+
+---
+
+Chào team Hoa,
+
+Có hai thứ trong nhánh `gamma/refactor` ảnh hưởng trực tiếp tới phần các bạn
+sắp làm. Gửi trước để khỏi mất thời gian truy lỗi.
+
+## 1. `platform/` đã đổi tên thành `adapters/` — plan.md ghi tên cũ
+
+Plan chỉ đích danh `platform/qt/qt_scheduler_clock.py` (R07-T03, dòng 407 và
+lịch 25/08 ở dòng 229). **Đừng tạo thư mục `platform/`.**
+
+Lý do: `platform` là tên một module trong thư viện chuẩn của Python. Tạo thư
+mục `platform/` ở gốc repo là nó che mất module chuẩn khi chạy từ chính thư
+mục gốc — mà đó là cách toàn bộ script trong `tools/` và `scripts/` đang chạy.
+Triệu chứng không hề chỉ về đúng chỗ:
+
+    AttributeError: module 'platform' has no attribute 'system'
+
+Ném ra từ `import keyring`, không liên quan gì tới file bạn vừa tạo.
+
+Tôi đã mắc đúng lỗi này hôm 21/08. Lúc thử thì đứng ở thư mục cha nên không
+tái hiện được, tưởng an toàn. Đổi tên thành `adapters/` và thêm
+`tests/test_no_stdlib_shadow.py` để lần sau đỏ ngay.
+
+**Việc cần làm**: tạo `adapters/qt/qt_scheduler_clock.py` thay vì
+`platform/qt/...`. Thư mục `adapters/qt/` đã có sẵn `__init__.py` trên nhánh
+`gamma/refactor`, kéo về là dùng được.
+
+## 2. `AtomicJsonFile` vừa vá một lỗi Windows — lấy bản mới trước khi dựng lên
+
+Plan giao các bạn hai repository ngồi trên `AtomicJsonFile`:
+
+* `infrastructure/persistence/json/task_repository_impl.py` (R07-T01, dòng 403)
+* `infrastructure/persistence/json/workspace_repository_impl.py` (R06, dòng 387)
+
+Và tiêu chí nghiệm thu **A** (dòng 244) bắt mọi thao tác ghi tệp phải đi qua nó.
+
+Hôm nay tôi bắt được lỗi thật trong đó:
+
+    PermissionError: [WinError 5] Access is denied
+      .dem.json.xxxxxxx.tmp -> dem.json
+
+`os.replace` trên Windows bị từ chối khi Defender hoặc Search Indexer đang giữ
+handle lên file vừa tạo — vài chục mili-giây rồi nhả. Đo được: hỏng 1 trong 7
+lượt chạy 20 lần ghi, tức **khoảng 1 trên 140 lần lưu**. Người dùng thỉnh
+thoảng bấm Lưu là văng lỗi và không tài nào tái hiện để báo.
+
+Đã thêm vòng thử lại (commit `9d6a7be`). Nếu các bạn dựng repository trên bản
+trước đó thì lưu task và lưu workspace cũng hỏng với tần suất y hệt — nhân lên
+ba nơi ghi file.
+
+**Việc cần làm**: `git pull` nhánh `gamma/refactor` (hoặc chờ nó vào `main`)
+trước khi bắt đầu R06/R07-T01.
+
+## Tiện thể
+
+`domain/security/tool_policy.py` là bản đề xuất DTO `ToolPolicyGateway` tôi
+viết hộ cho R05 của các bạn — ba trạng thái ALLOW/DENY/ASK, kèm fake và test
+contract. Không có gì của Gamma phụ thuộc vào nó, nên các bạn cứ sửa hoặc bỏ
+thoải mái, không phải giữ ý.
+
+Nam

docs/screens/manifest.json

@@ -0,0 +1,542 @@
+[
+  {
+    "slug": "dashboard",
+    "title": "Dashboard",
+    "theme": "dark",
+    "note": "ui/dashboard_tab.py:35",
+    "file": "screens/dashboard-dark.png",
+    "error": "",
+    "nav": "Dashboard",
+    "nav_expected": "Dashboard"
+  },
+  {
+    "slug": "schedule-kanban",
+    "title": "Schedule Task — Kanban",
+    "theme": "dark",
+    "note": "ui/schedule_task_tab.py:70",
+    "file": "screens/schedule-kanban-dark.png",
+    "error": "",
+    "nav": "Schedule Task",
+    "nav_expected": "Schedule Task"
+  },
+  {
+    "slug": "schedule-calendar",
+    "title": "Schedule Task — Calendar",
+    "theme": "dark",
+    "note": "ui/calendar_view.py:88",
+    "file": "screens/schedule-calendar-dark.png",
+    "error": "",
+    "nav": "Schedule Task",
+    "nav_expected": "Schedule Task"
+  },
+  {
+    "slug": "workspace-project",
+    "title": "Workspace ▸ Project",
+    "theme": "dark",
+    "note": "ui/workspace_tab.py:188",
+    "file": "screens/workspace-project-dark.png",
+    "error": "",
+    "nav": "Workspace",
+    "nav_expected": "Workspace"
+  },
+  {
+    "slug": "workspace-cowork",
+    "title": "Workspace ▸ Cowork",
+    "theme": "dark",
+    "note": "ui/cowork_tab.py:21",
+    "file": "screens/workspace-cowork-dark.png",
+    "error": "",
+    "nav": "Cowork",
+    "nav_expected": "Cowork"
+  },
+  {
+    "slug": "workspace-co4e",
+    "title": "Workspace ▸ Co4E",
+    "theme": "dark",
+    "note": "ui/co4e_tab.py:228",
+    "file": "screens/workspace-co4e-dark.png",
+    "error": "",
+    "nav": "Co4E",
+    "nav_expected": "Co4E"
+  },
+  {
+    "slug": "workspace-folder",
+    "title": "Workspace ▸ Folder",
+    "theme": "dark",
+    "note": "ui/folder_tab.py:238",
+    "file": "screens/workspace-folder-dark.png",
+    "error": "",
+    "nav": "Thư mục",
+    "nav_expected": "Thư mục"
+  },
+  {
+    "slug": "workspace-graphrag",
+    "title": "Workspace ▸ GraphRAG",
+    "theme": "dark",
+    "note": "ui/structure_graph_view.py:188",
+    "file": "screens/workspace-graphrag-dark.png",
+    "error": "",
+    "nav": "GraphRAG",
+    "nav_expected": "GraphRAG"
+  },
+  {
+    "slug": "monitoring-tổng-quan",
+    "title": "Monitoring ▸ Tổng quan",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-tổng-quan-dark.png",
+    "error": "",
+    "nav": "Tổng quan",
+    "nav_expected": "Tổng quan"
+  },
+  {
+    "slug": "monitoring-sự-kiện-bảo-mật",
+    "title": "Monitoring ▸ Sự kiện bảo mật",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-sự-kiện-bảo-mật-dark.png",
+    "error": "",
+    "nav": "Sự kiện bảo mật",
+    "nav_expected": "Sự kiện bảo mật"
+  },
+  {
+    "slug": "monitoring-lịch-sử-gọi-mcp",
+    "title": "Monitoring ▸ Lịch sử gọi MCP",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-lịch-sử-gọi-mcp-dark.png",
+    "error": "",
+    "nav": "Lịch sử gọi MCP",
+    "nav_expected": "Lịch sử gọi MCP"
+  },
+  {
+    "slug": "monitoring-nhật-ký-hành-động",
+    "title": "Monitoring ▸ Nhật ký hành động",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-nhật-ký-hành-động-dark.png",
+    "error": "",
+    "nav": "Nhật ký hành động",
+    "nav_expected": "Nhật ký hành động"
+  },
+  {
+    "slug": "monitoring-trạng-thái-agent",
+    "title": "Monitoring ▸ Trạng thái Agent",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-trạng-thái-agent-dark.png",
+    "error": "",
+    "nav": "Trạng thái Agent",
+    "nav_expected": "Trạng thái Agent"
+  },
+  {
+    "slug": "monitoring-agents-admin",
+    "title": "Monitoring ▸ Agents Admin",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-agents-admin-dark.png",
+    "error": "",
+    "nav": "Agents Admin",
+    "nav_expected": "Agents Admin"
+  },
+  {
+    "slug": "monitoring-công-cụ",
+    "title": "Monitoring ▸ Công cụ",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-công-cụ-dark.png",
+    "error": "",
+    "nav": "Công cụ",
+    "nav_expected": "Công cụ"
+  },
+  {
+    "slug": "monitoring-icon",
+    "title": "Monitoring ▸ Icon",
+    "theme": "dark",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-icon-dark.png",
+    "error": "",
+    "nav": "Icon",
+    "nav_expected": "Icon"
+  },
+  {
+    "slug": "dialog-settings",
+    "title": "Settings",
+    "theme": "dark",
+    "note": "ui/settings_dialog.py:26",
+    "file": "screens/dialog-settings-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-task-editor",
+    "title": "Task Editor",
+    "theme": "dark",
+    "note": "ui/task_editor_dialog.py:55",
+    "file": "screens/dialog-task-editor-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-skills",
+    "title": "Skills manager",
+    "theme": "dark",
+    "note": "ui/skills_dialog.py:108",
+    "file": "screens/dialog-skills-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-skill-edit",
+    "title": "Skill editor",
+    "theme": "dark",
+    "note": "ui/skills_dialog.py:23",
+    "file": "screens/dialog-skill-edit-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-file-edit",
+    "title": "File view & AI edit",
+    "theme": "dark",
+    "note": "ui/file_edit_dialog.py:50",
+    "file": "screens/dialog-file-edit-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-co4e-agent",
+    "title": "Co4E agent editor",
+    "theme": "dark",
+    "note": "ui/co4e_agent_dialog.py:23",
+    "file": "screens/dialog-co4e-agent-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-ext-connector",
+    "title": "External connector",
+    "theme": "dark",
+    "note": "ui/ext_connector_dialog.py:23",
+    "file": "screens/dialog-ext-connector-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-permission",
+    "title": "Permission request",
+    "theme": "dark",
+    "note": "ui/permission_dialog.py:13",
+    "file": "screens/dialog-permission-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-agent-edit",
+    "title": "Admin agent editor",
+    "theme": "dark",
+    "note": "ui/agents_admin_tab.py:35",
+    "file": "screens/dialog-agent-edit-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-login",
+    "title": "Login (dead screen — not wired)",
+    "theme": "dark",
+    "note": "ui/login_dialog.py:57",
+    "file": "screens/dialog-login-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "overlay-help-panel",
+    "title": "Help dock — expanded panel",
+    "theme": "dark",
+    "note": "ui/help_agent_widget.py:79",
+    "file": "screens/overlay-help-panel-dark.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dashboard",
+    "title": "Dashboard",
+    "theme": "light",
+    "note": "ui/dashboard_tab.py:35",
+    "file": "screens/dashboard-light.png",
+    "error": "",
+    "nav": "Dashboard",
+    "nav_expected": "Dashboard"
+  },
+  {
+    "slug": "schedule-kanban",
+    "title": "Schedule Task — Kanban",
+    "theme": "light",
+    "note": "ui/schedule_task_tab.py:70",
+    "file": "screens/schedule-kanban-light.png",
+    "error": "",
+    "nav": "Schedule Task",
+    "nav_expected": "Schedule Task"
+  },
+  {
+    "slug": "schedule-calendar",
+    "title": "Schedule Task — Calendar",
+    "theme": "light",
+    "note": "ui/calendar_view.py:88",
+    "file": "screens/schedule-calendar-light.png",
+    "error": "",
+    "nav": "Schedule Task",
+    "nav_expected": "Schedule Task"
+  },
+  {
+    "slug": "workspace-project",
+    "title": "Workspace ▸ Project",
+    "theme": "light",
+    "note": "ui/workspace_tab.py:188",
+    "file": "screens/workspace-project-light.png",
+    "error": "",
+    "nav": "Workspace",
+    "nav_expected": "Workspace"
+  },
+  {
+    "slug": "workspace-cowork",
+    "title": "Workspace ▸ Cowork",
+    "theme": "light",
+    "note": "ui/cowork_tab.py:21",
+    "file": "screens/workspace-cowork-light.png",
+    "error": "",
+    "nav": "Cowork",
+    "nav_expected": "Cowork"
+  },
+  {
+    "slug": "workspace-co4e",
+    "title": "Workspace ▸ Co4E",
+    "theme": "light",
+    "note": "ui/co4e_tab.py:228",
+    "file": "screens/workspace-co4e-light.png",
+    "error": "",
+    "nav": "Co4E",
+    "nav_expected": "Co4E"
+  },
+  {
+    "slug": "workspace-folder",
+    "title": "Workspace ▸ Folder",
+    "theme": "light",
+    "note": "ui/folder_tab.py:238",
+    "file": "screens/workspace-folder-light.png",
+    "error": "",
+    "nav": "Thư mục",
+    "nav_expected": "Thư mục"
+  },
+  {
+    "slug": "workspace-graphrag",
+    "title": "Workspace ▸ GraphRAG",
+    "theme": "light",
+    "note": "ui/structure_graph_view.py:188",
+    "file": "screens/workspace-graphrag-light.png",
+    "error": "",
+    "nav": "GraphRAG",
+    "nav_expected": "GraphRAG"
+  },
+  {
+    "slug": "monitoring-tổng-quan",
+    "title": "Monitoring ▸ Tổng quan",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-tổng-quan-light.png",
+    "error": "",
+    "nav": "Tổng quan",
+    "nav_expected": "Tổng quan"
+  },
+  {
+    "slug": "monitoring-sự-kiện-bảo-mật",
+    "title": "Monitoring ▸ Sự kiện bảo mật",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-sự-kiện-bảo-mật-light.png",
+    "error": "",
+    "nav": "Sự kiện bảo mật",
+    "nav_expected": "Sự kiện bảo mật"
+  },
+  {
+    "slug": "monitoring-lịch-sử-gọi-mcp",
+    "title": "Monitoring ▸ Lịch sử gọi MCP",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-lịch-sử-gọi-mcp-light.png",
+    "error": "",
+    "nav": "Lịch sử gọi MCP",
+    "nav_expected": "Lịch sử gọi MCP"
+  },
+  {
+    "slug": "monitoring-nhật-ký-hành-động",
+    "title": "Monitoring ▸ Nhật ký hành động",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-nhật-ký-hành-động-light.png",
+    "error": "",
+    "nav": "Nhật ký hành động",
+    "nav_expected": "Nhật ký hành động"
+  },
+  {
+    "slug": "monitoring-trạng-thái-agent",
+    "title": "Monitoring ▸ Trạng thái Agent",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-trạng-thái-agent-light.png",
+    "error": "",
+    "nav": "Trạng thái Agent",
+    "nav_expected": "Trạng thái Agent"
+  },
+  {
+    "slug": "monitoring-agents-admin",
+    "title": "Monitoring ▸ Agents Admin",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-agents-admin-light.png",
+    "error": "",
+    "nav": "Agents Admin",
+    "nav_expected": "Agents Admin"
+  },
+  {
+    "slug": "monitoring-công-cụ",
+    "title": "Monitoring ▸ Công cụ",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-công-cụ-light.png",
+    "error": "",
+    "nav": "Công cụ",
+    "nav_expected": "Công cụ"
+  },
+  {
+    "slug": "monitoring-icon",
+    "title": "Monitoring ▸ Icon",
+    "theme": "light",
+    "note": "ui/monitoring_tab.py:132",
+    "file": "screens/monitoring-icon-light.png",
+    "error": "",
+    "nav": "Icon",
+    "nav_expected": "Icon"
+  },
+  {
+    "slug": "dialog-settings",
+    "title": "Settings",
+    "theme": "light",
+    "note": "ui/settings_dialog.py:26",
+    "file": "screens/dialog-settings-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-task-editor",
+    "title": "Task Editor",
+    "theme": "light",
+    "note": "ui/task_editor_dialog.py:55",
+    "file": "screens/dialog-task-editor-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-skills",
+    "title": "Skills manager",
+    "theme": "light",
+    "note": "ui/skills_dialog.py:108",
+    "file": "screens/dialog-skills-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-skill-edit",
+    "title": "Skill editor",
+    "theme": "light",
+    "note": "ui/skills_dialog.py:23",
+    "file": "screens/dialog-skill-edit-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-file-edit",
+    "title": "File view & AI edit",
+    "theme": "light",
+    "note": "ui/file_edit_dialog.py:50",
+    "file": "screens/dialog-file-edit-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-co4e-agent",
+    "title": "Co4E agent editor",
+    "theme": "light",
+    "note": "ui/co4e_agent_dialog.py:23",
+    "file": "screens/dialog-co4e-agent-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-ext-connector",
+    "title": "External connector",
+    "theme": "light",
+    "note": "ui/ext_connector_dialog.py:23",
+    "file": "screens/dialog-ext-connector-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-permission",
+    "title": "Permission request",
+    "theme": "light",
+    "note": "ui/permission_dialog.py:13",
+    "file": "screens/dialog-permission-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-agent-edit",
+    "title": "Admin agent editor",
+    "theme": "light",
+    "note": "ui/agents_admin_tab.py:35",
+    "file": "screens/dialog-agent-edit-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "dialog-login",
+    "title": "Login (dead screen — not wired)",
+    "theme": "light",
+    "note": "ui/login_dialog.py:57",
+    "file": "screens/dialog-login-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  },
+  {
+    "slug": "overlay-help-panel",
+    "title": "Help dock — expanded panel",
+    "theme": "light",
+    "note": "ui/help_agent_widget.py:79",
+    "file": "screens/overlay-help-panel-light.png",
+    "error": "",
+    "nav": "",
+    "nav_expected": ""
+  }
+]