docs(refactor): merge Team Hoa R05/R06 and R07/R08 reports into one

Replaces BaoCao_TeamHoa_R05_R06.md and BaoCao_TeamHoa_R07_R08.md with a
single BaoCao_TeamHoa_R05_R08.md covering all 4 EPICs (19/19 tasks) in
Team Hoa's scope, and updates the checklist's report links accordingly.

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

app.py

@@ -23,13 +23,13 @@ from .state import AppContext
 from .ui.widgets import tidy_popup
 from .theme import current_palette, set_active_theme, stylesheet
 from .core.task_scheduler import TaskScheduler
+from .presentation.dashboard.dashboard_tab import DashboardTab
+from .presentation.graph.structure_graph_view import StructureGraphView
+from .presentation.scheduling.schedule_task_tab import ScheduleTaskTab
 from .ui.cowork_tab import CoworkTab
-from .ui.dashboard_tab import DashboardTab
 from .ui.monitoring_tab import MonitoringTab
-from .ui.schedule_task_tab import ScheduleTaskTab
 from .ui.settings_dialog import SettingsDialog
 from .ui.sidebar import HistorySidebar
-from .ui.structure_graph_view import StructureGraphView
 from .ui.workspace_tab import WorkspaceTab
 
 ASSETS = Path(__file__).resolve().parent / "assets"

application/__init__.py

@@ -0,0 +1,12 @@
+"""Application layer - pure Python use-case orchestration.
+
+Sits between ``presentation/`` (Qt widgets) and ``domain/`` (entities). A module
+here answers "what has to happen, in what order" for one use case - route a
+turn, run a conversation - without knowing whether a human, a scheduler or a
+test triggered it.
+
+Hard rule (ADR-001 I1/I3, enforced by ``scripts/check_imports.py``): no
+PySide6/PyQt imports and no reach into ``presentation/``/``ui/``. Results travel
+back up through plain-Python callbacks; turning those into Qt signals is the
+presentation layer's job.
+"""

application/conversations/__init__.py

@@ -0,0 +1,10 @@
+"""Conversation use case: the lifecycle of one agent turn (EPIC R04) and the
+tool approval policy every turn's tool calls go through (EPIC R05)."""
+
+from .conversation_application_service import (
+    ConversationApplicationService,
+    TurnResult,
+)
+from .tool_policy_gateway import ConfirmGate, ToolPolicyGateway
+
+__all__ = ["ConversationApplicationService", "TurnResult", "ToolPolicyGateway", "ConfirmGate"]

application/conversations/conversation_application_service.py

@@ -0,0 +1,328 @@
+"""ConversationApplicationService - the turn lifecycle, outside the widget (R04-T03).
+
+What this replaces
+------------------
+The lifecycle of one Cowork turn is currently spread across a closure inside
+``ui/cowork_tab.py::build_job`` and a second, near-identical assembly inside
+``core/task_executors.py::_run_agent``. Both:
+
+* read live UI/config state from a worker thread,
+* build the provider, the MCP tool set and the project context by hand,
+* call ``core.chat_agent.run_cowork`` with a dozen positional-ish arguments,
+* consume untyped event dicts.
+
+Two copies means a fix to one path (say, promoting output files on failure)
+silently misses the other. This service is the single implementation: it takes
+an immutable :class:`ConversationExecutionRequest`, runs the turn, and reports
+typed :class:`AgentEvent` objects.
+
+What it deliberately does NOT do
+--------------------------------
+It does not re-implement the agent loop. ``run_cowork`` stays the engine
+(strangler fig, ADR-001 section 4) and keeps its characterization tests
+(``tests/characterization/test_run_cowork.py``). This layer owns the parts that
+were tangled into the UI: assembling the call, translating events, and giving a
+turn a well-defined end.
+
+Pure Python: no Qt import, no config access. Everything it needs arrives through
+constructor callbacks, so the same service runs a turn from a chat panel, from
+the scheduler, or from a test.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from cowork_local.domain.agents.agent_event import (
+    AgentEvent,
+    ErrorEvent,
+    TurnCompletedEvent,
+    collect_text,
+    event_from_dict,
+)
+from cowork_local.domain.agents.conversation_execution_request import (
+    ConversationExecutionRequest,
+)
+
+logger = logging.getLogger("cowork_local.conversations")
+
+# Presentation/scheduler supplies these. Kept as plain callables (not objects)
+# so a test can wire the service with three lambdas.
+EventCallback = Callable[[AgentEvent], None]
+CancelFn = Callable[[], bool]
+ProviderFactory = Callable[[str, str], Any]          # (provider_id, model) -> Provider
+ToolSourceFactory = Callable[[], Tuple[Any, Any]]    # () -> (extra_tools, extra_executor)
+GateFactory = Callable[[ConversationExecutionRequest], Any]  # -> PermissionGate or None
+
+
+@dataclass
+class TurnResult:
+    """What a finished turn produced.
+
+    ``messages`` is the conversation AFTER the turn (system prompt inserted,
+    assistant and tool messages appended) - the caller persists this as the new
+    history. ``final_text`` is the visible answer, reasoning excluded.
+    """
+
+    request: ConversationExecutionRequest
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    events: List[AgentEvent] = field(default_factory=list)
+    final_text: str = ""
+    cancelled: bool = False
+    error: str = ""
+    # The original exception, kept alongside its message so a caller that needs
+    # to preserve legacy failure handling can re-raise the SAME object rather
+    # than a lookalike (SecurityBlocked, for instance, carries context that a
+    # re-wrapped RuntimeError would lose).
+    exception: Optional[BaseException] = None
+
+    @property
+    def ok(self) -> bool:
+        """True when the turn completed without an error and without a Stop."""
+        return not self.error and not self.cancelled
+
+    def raise_if_failed(self) -> None:
+        """Re-raise the turn's failure, if any.
+
+        Callers that already have failure handling built around an exception
+        (the Qt worker turns one into its ``failed`` signal) use this to keep
+        that path intact while still getting a TurnResult on success."""
+        if self.exception is not None:
+            raise self.exception
+
+    def output_dir(self) -> Optional[Path]:
+        """This turn's output folder, or None when it could not write files."""
+        return Path(self.request.output_dir) if self.request.output_dir else None
+
+
+class ConversationApplicationService:
+    """Runs one agent turn from an immutable request.
+
+    Args:
+        provider_factory: ``(provider_id, model) -> Provider``. Production passes
+            ``AppContext.build_provider_for``; tests pass a lambda returning a
+            :class:`FakeProvider`.
+        tool_source: ``() -> (extra_tools, extra_executor)`` for MCP/connector
+            tools. Optional - a turn with no external tools passes nothing.
+        gate_factory: ``(request) -> PermissionGate | None``, consulted when the
+            request asks to confirm commands. Optional for the same reason.
+        runner: the turn engine. Defaults to ``core.chat_agent.run_cowork``,
+            imported lazily so this module stays importable (and testable)
+            without pulling in the whole legacy tool stack.
+        security_config: the app config the security layers read. ``None``
+            disables them, which is what headless callers already rely on.
+    """
+
+    def __init__(
+        self,
+        provider_factory: ProviderFactory,
+        *,
+        tool_source: Optional[ToolSourceFactory] = None,
+        gate_factory: Optional[GateFactory] = None,
+        runner: Optional[Callable[..., Any]] = None,
+        security_config: Any = None,
+    ) -> None:
+        self._provider_factory = provider_factory
+        self._tool_source = tool_source
+        self._gate_factory = gate_factory
+        self._runner = runner
+        self._security_config = security_config
+
+    # -- main entry point -------------------------------------------------- #
+    def run_turn(
+        self,
+        request: ConversationExecutionRequest,
+        on_event: Optional[EventCallback] = None,
+        cancel: Optional[CancelFn] = None,
+    ) -> TurnResult:
+        """Execute one turn and return everything it produced.
+
+        Never raises: a provider or tool failure becomes an :class:`ErrorEvent`
+        plus ``TurnResult.error``. Callers run this on a worker thread and have
+        no good way to handle an exception crossing that boundary - today an
+        escaped error kills the worker and the UI just stops updating, with no
+        message shown.
+
+        Exactly one :class:`TurnCompletedEvent` is always emitted last, whether
+        the turn succeeded, failed or was cancelled. That is the end-of-turn
+        signal the legacy engine never had.
+        """
+        return self.execute_turn(self.begin_turn(request), on_event=on_event, cancel=cancel)
+
+    def begin_turn(self, request: ConversationExecutionRequest) -> TurnResult:
+        """Create the (still empty) result a turn will fill in.
+
+        Exposed separately from :meth:`run_turn` because some callers need the
+        LIVE message list while the turn is running, not only afterwards: the
+        scheduler re-saves the conversation to History after every assistant
+        message so a long unattended run shows live progress when reopened.
+        Handing them ``result.messages`` - the very list the engine appends to -
+        is what makes that possible without leaking the engine into the caller.
+        """
+        return TurnResult(request=request, messages=request.message_list())
+
+    def execute_turn(
+        self,
+        result: TurnResult,
+        on_event: Optional[EventCallback] = None,
+        cancel: Optional[CancelFn] = None,
+    ) -> TurnResult:
+        """Run a turn previously created by :meth:`begin_turn`. See
+        :meth:`run_turn` for the error/cancellation contract."""
+        request = result.request
+        emit = self._make_emitter(result, on_event)
+        cancel = cancel or (lambda: False)
+
+        try:
+            self._execute(request, result, emit, cancel)
+        except Exception as exc:  # noqa: BLE001 - see docstring
+            result.error = str(exc) or exc.__class__.__name__
+            result.exception = exc
+            logger.exception("turn %s failed", request.turn_id)
+            emit(ErrorEvent(message=result.error,
+                            recoverable=self._is_recoverable(exc)))
+
+        result.cancelled = bool(cancel())
+        result.final_text = collect_text(result.events) or self._last_assistant_text(result.messages)
+        emit(TurnCompletedEvent(content=result.final_text, cancelled=result.cancelled))
+        return result
+
+    # -- internals --------------------------------------------------------- #
+    def _execute(self, request: ConversationExecutionRequest, result: TurnResult,
+                 emit: Callable[[AgentEvent], None], cancel: CancelFn) -> None:
+        """Assemble the engine call from the request snapshot and run it."""
+        provider = self._provider_factory(request.provider, request.model)
+        extra_tools, extra_executor = self._resolve_tools()
+        gate = self._resolve_gate(request)
+
+        # The engine speaks untyped dicts; bridge them into typed events at this
+        # single point rather than at every consumer.
+        def legacy_emit(payload: Dict[str, Any]) -> None:
+            event = event_from_dict(payload)
+            if event is not None:
+                emit(event)
+
+        run = self._resolve_runner()
+        run(
+            provider,
+            result.messages,          # mutated in place by the engine, as before
+            self._output_dir(request),
+            legacy_emit,
+            cancel,
+            title=request.title,
+            extra_tools=extra_tools,
+            extra_executor=extra_executor,
+            project_context=request.project_context,
+            security_config=self._security_config,
+            gate=gate,
+            allowed_tools=list(request.allowed_tools) if request.allowed_tools is not None else None,
+            max_steps=request.max_steps,
+            run_to_completion=request.run_to_completion,
+            completion_max_steps=request.completion_max_steps,
+            enforce_rules=request.enforce_rules,
+            **self._role_kwargs(request),
+        )
+
+    @staticmethod
+    def _make_emitter(result: TurnResult,
+                      on_event: Optional[EventCallback]) -> Callable[[AgentEvent], None]:
+        """Record every event on the result AND forward it to the caller.
+
+        Recording is unconditional so a headless caller (the scheduler) can read
+        the full event list afterwards without having to supply a callback just
+        to collect it - which is exactly what task_executors does today with an
+        ad-hoc list.
+        """
+        def emit(event: AgentEvent) -> None:
+            result.events.append(event)
+            if on_event is None:
+                return
+            try:
+                on_event(event)
+            except Exception:  # noqa: BLE001
+                # A consumer that throws (a closing widget, say) must not abort
+                # the turn that is feeding it.
+                logger.debug("event consumer raised for %s", event.type, exc_info=True)
+        return emit
+
+    def _resolve_runner(self) -> Callable[..., Any]:
+        """The turn engine, imported lazily on first use."""
+        if self._runner is None:
+            from cowork_local.core.chat_agent import run_cowork
+
+            self._runner = run_cowork
+        return self._runner
+
+    def _resolve_tools(self) -> Tuple[Any, Any]:
+        """MCP/connector tools for this turn, or ``(None, None)``.
+
+        A failure here degrades to "no external tools" rather than failing the
+        turn: an MCP server that will not start must not stop the user from
+        chatting, which is the behaviour the chat panel already relies on.
+        """
+        if self._tool_source is None:
+            return None, None
+        try:
+            return self._tool_source()
+        except Exception:  # noqa: BLE001
+            logger.warning("tool source unavailable - running without external tools",
+                           exc_info=True)
+            return None, None
+
+    def _resolve_gate(self, request: ConversationExecutionRequest) -> Any:
+        """The permission gate, when this turn asked to confirm commands."""
+        if not request.confirm_commands or self._gate_factory is None:
+            return None
+        return self._gate_factory(request)
+
+    @staticmethod
+    def _output_dir(request: ConversationExecutionRequest) -> Path:
+        """The turn's output folder as a Path.
+
+        The request holds it as a string to stay serialisable; converting at the
+        single point of use keeps that decision from leaking into every caller.
+        """
+        return Path(request.output_dir) if request.output_dir else Path.cwd()
+
+    @staticmethod
+    def _role_kwargs(request: ConversationExecutionRequest) -> Dict[str, Any]:
+        """``agent_role`` only when the request set one.
+
+        Omitted otherwise so the engine applies its own default (the interactive
+        Cowork role) instead of being handed an empty string, which would land
+        in the audit log as an unattributed tool call.
+        """
+        return {"agent_role": request.agent_role} if request.agent_role else {}
+
+    @staticmethod
+    def _last_assistant_text(messages: List[Dict[str, Any]]) -> str:
+        """Fallback answer text when no text events were seen.
+
+        A turn whose whole answer arrived in one non-streamed message still has
+        to report a final answer - the scheduler writes it into output.md, and
+        an empty string there reads as "(no output)".
+        """
+        for message in reversed(messages):
+            if message.get("role") == "assistant" and (message.get("content") or "").strip():
+                return str(message["content"])
+        return ""
+
+    @staticmethod
+    def _is_recoverable(exc: Exception) -> bool:
+        """Whether the user can act on this failure themselves.
+
+        "Model not found" is the motivating case: the chat panel restores the
+        typed message into the composer so the user can switch model and resend
+        instead of retyping it (see providers/base.py::MODEL_NOT_FOUND_HINT).
+        """
+        try:
+            from cowork_local.providers.base import is_model_not_found_error
+
+            return bool(is_model_not_found_error(str(exc)))
+        except Exception:  # noqa: BLE001
+            return False
+
+
+__all__ = ["ConversationApplicationService", "TurnResult"]

application/conversations/tool_policy_gateway.py

@@ -0,0 +1,83 @@
+"""ToolPolicyGateway - one confirm/deny decision path for every tool call
+(R05-T03).
+
+Today "does this tool call need the user's OK first" is answered by a
+different hand-written check per engine:
+
+* ``core/chat_agent.py::run_cowork`` — ``name in ("run_command",
+  "install_package")``, a literal tuple.
+* ``core/code_agent.py::run_code`` — ``name in (WRITE_TOOLS | MS365_WRITE_TOOLS)``,
+  a set built from two other hand-maintained sets.
+* MCP/connector tools (``core/mcp_client.py``, ``core/ext_connectors.py``) —
+  no check at all; ``chat_agent.py`` calls ``extra_executor(name, args)``
+  directly.
+
+Three answers to the same question, and the third one is a real gap: an MCP
+tool that deletes files or calls an external API today runs with zero
+confirmation even when the user turned "confirm before running commands" on.
+
+This gateway answers the question from data (:class:`~domain.tools.tool_descriptor.ToolCapability`
+via a :class:`~domain.tools.tool_registry.ToolRegistry`) instead of a literal
+name list, so registering a tool with the right capability is what gates it -
+nothing to remember at each new call site. R05-T04 is what actually registers
+MCP/connector tools with a capability; this module only needs the mechanism
+to exist.
+
+Pure Python: no Qt, no direct dialog. The actual approval prompt stays exactly
+what it is today - a ``gate`` object with a ``.request(payload) -> bool``
+method, supplied by the presentation layer (Settings' "confirm before running
+commands" wires it up, or None for auto-run) - this module only decides
+WHEN to ask it, never how to render the question.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Protocol
+
+from cowork_local.domain.tools import ToolCapability, ToolRegistry
+
+
+class ConfirmGate(Protocol):
+    """Shape of the existing ``PermissionGate`` both engines already use."""
+
+    def request(self, payload: Dict[str, Any]) -> bool: ...
+
+
+class ToolPolicyGateway:
+    """Decides whether a tool call needs approval, for ONE calling surface.
+
+    ``gated_capabilities`` is what makes this per-surface: Cowork only ever
+    asked about ``run_command``/``install_package`` (capability ``EXECUTE``),
+    while the Code tab additionally confirms plain file writes (capability
+    ``WRITE``). Passing the wrong set here would silently change which tools
+    prompt for approval - see the callers in ``core/chat_agent.py`` and
+    ``core/code_agent.py`` for the exact sets that preserve today's behavior.
+    """
+
+    def __init__(self, registry: ToolRegistry, gated_capabilities: ToolCapability) -> None:
+        self._registry = registry
+        self._gated_capabilities = gated_capabilities
+
+    def requires_confirmation(self, name: str) -> bool:
+        """True when ``name``'s declared capabilities overlap this surface's
+        gated set. An unregistered tool never requires confirmation through
+        this path - callers that must fail safe on unknown tools check
+        ``name in registry`` themselves (see R05-T04's MCP wrapping, which
+        registers every tool it exposes before any call can reach here)."""
+        return bool(self._registry.capabilities_for(name) & self._gated_capabilities)
+
+    def allow(self, name: str, gate: Optional[ConfirmGate], payload: Dict[str, Any]) -> bool:
+        """True when the call may proceed.
+
+        ``gate is None`` preserves each engine's existing "no gate wired -
+        auto-run" behavior; a tool outside ``gated_capabilities`` is never
+        asked about, matching read-only tools "never confirm" today.
+        ``payload`` is whatever ``gate.request(...)`` already expects at that
+        call site (the two engines use slightly different dict shapes) - this
+        gateway only decides WHETHER to call it, never reshapes the payload.
+        """
+        if gate is None or not self.requires_confirmation(name):
+            return True
+        return bool(gate.request(payload))
+
+
+__all__ = ["ToolPolicyGateway", "ConfirmGate"]

application/model_routing/__init__.py

@@ -0,0 +1,12 @@
+"""Model routing use case: pick the best-fit model for one turn (EPIC R03)."""
+
+from .routing_application_service import (
+    RoutingApplicationService,
+    RoutingDecision,
+    RoutingMode,
+    is_valid_mode,
+    normalize_mode,
+)
+
+__all__ = ["RoutingApplicationService", "RoutingDecision", "RoutingMode",
+           "normalize_mode", "is_valid_mode"]

application/model_routing/routing_application_service.py

@@ -0,0 +1,353 @@
+"""RoutingApplicationService - one routing flow for every surface (R03-T03).
+
+Before this service, the same routing algorithm existed three times:
+
+* ``ui/chat_panel.py::_apply_routing``       (Cowork chat)
+* ``ui/co4e_tab.py::_apply_co4e_routing``    (Co4E studio)
+* ``ui/folder_tab.py::_ai_apply_routing``    (AI-Edit)
+
+The three copies had already drifted - each one resolves the "current model"
+differently and each one has its own private notion of what to do when the user
+declines - and every one of them lives inside a Qt widget, so none of the logic
+could be tested without building a window.
+
+This module is the single implementation. It is pure Python: no Qt import, no
+config access, no network. The presentation layer supplies a confirm callback
+and renders the notice; everything else happens here.
+
+Modes (:class:`RoutingMode`)
+----------------------------
+* ``OFF``      - never switch. The user's pinned model always wins.
+* ``AUTO``     - switch silently when the best candidate clears the gain threshold.
+* ``MANUAL``   - propose the switch and switch only if the confirm callback approves.
+* ``FALLBACK`` - never switch pre-emptively; switch only AFTER the current model
+  fails, to the next-best candidate. This is the mode a user wants when they
+  trust their own model choice but still want the turn to survive an outage.
+
+Migration note (ADR-001 section 4): the scoring/ranking engine is NOT rewritten.
+This service depends on the small :class:`RoutingPort` interface, and production
+wires the existing, already-tested ``core.routing.service.RoutingService`` into
+it. Tests wire a fake.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable, List, Optional, Protocol, Sequence, Tuple
+
+
+class RoutingMode(str, Enum):
+    """Per-surface routing behaviour.
+
+    The first three values match ``core.routing.models.SwitchMode`` string for
+    string, so a mode read from the existing config round-trips unchanged.
+    """
+
+    OFF = "off"
+    AUTO = "auto"
+    MANUAL = "manual"
+    FALLBACK = "fallback"
+
+    @classmethod
+    def parse(cls, raw: Any) -> "RoutingMode":
+        """Best-effort parse of a config value.
+
+        Unknown or empty values become ``OFF``: routing is an optimisation, and
+        the safe reading of a corrupt setting is "leave the user's model alone"
+        rather than "silently move their work to another model".
+        """
+        try:
+            return cls(str(raw or "off").strip().lower())
+        except ValueError:
+            return cls.OFF
+
+
+@dataclass(frozen=True)
+class RoutingDecision:
+    """The outcome of routing one turn - an immutable instruction for the caller.
+
+    ``provider``/``model`` are ALWAYS filled with what the turn should actually
+    run on, switched or not, so a call site never has to re-derive the fallback
+    itself (the bug that made the three UI copies diverge).
+    """
+
+    mode: RoutingMode
+    provider: str
+    model: str
+    switched: bool = False
+    task_type: str = ""
+    score_gain: float = 0.0
+    reason: str = ""
+    declined: bool = False  # Manual mode: a switch was offered and refused
+    # What the turn would have run on without routing. Carried so the Manual
+    # confirm dialog can show "from X to Y" without re-deriving the current
+    # model itself - re-deriving it differently per screen is exactly how the
+    # three legacy copies drifted apart.
+    previous_provider: str = ""
+    previous_model: str = ""
+
+    @property
+    def should_notify(self) -> bool:
+        """True when the UI should show the "switched model" notice - i.e. only
+        when a switch really happened."""
+        return self.switched
+
+    def target(self) -> Tuple[str, str]:
+        """``(provider, model)`` to run this turn on."""
+        return self.provider, self.model
+
+    @property
+    def from_model(self) -> str:
+        """Candidate key (``provider/model``) of the model being switched away
+        from, or "" when nothing was selected yet.
+
+        Named to match ``core.routing.models.SwitchDecision`` so the existing
+        Manual-mode dialog (``ui/routing_toggle.py::confirm_switch``) accepts
+        this object unchanged - the dialog moves to the new shape in EPIC R08.
+        """
+        if not self.previous_model:
+            return ""
+        return f"{self.previous_provider}/{self.previous_model}"
+
+    @property
+    def to_model(self) -> str:
+        """Candidate key (``provider/model``) of the model to run on. See
+        :attr:`from_model` for why the name matches the legacy decision."""
+        return f"{self.provider}/{self.model}" if self.model else ""
+
+
+def is_valid_mode(raw: Any) -> bool:
+    """True when ``raw`` names a mode the routing service understands.
+
+    Distinct from :func:`normalize_mode` because callers need to tell "the user
+    chose off" apart from "this stored value is unrecognised" - the per-workspace
+    lookup falls back to the global setting only in the second case.
+    """
+    try:
+        RoutingMode(str(raw or "").strip().lower())
+    except ValueError:
+        return False
+    return True
+
+
+def normalize_mode(raw: Any) -> str:
+    """Canonical mode string for persistence, or ``"off"`` when unrecognised.
+
+    Exists so the mode vocabulary is defined exactly once. It used to be
+    hard-coded as a ``("off", "auto", "manual")`` tuple in four separate places
+    (config.py twice, state.py twice); adding FALLBACK meant finding all four,
+    and missing one silently downgraded the user's choice back to "off".
+    """
+    return RoutingMode.parse(raw).value
+
+
+class RoutingPort(Protocol):
+    """The slice of the routing engine this service needs.
+
+    Declared as a Protocol so the application layer states its requirement
+    without importing the implementation - which is what lets the whole service
+    be tested against a 20-line fake, and lets ``core.routing`` be replaced later
+    without touching this file.
+    """
+
+    def route(self, surface: str, prompt: str, current_provider: str, current_model: str,
+              *, mode_override: Optional[str] = None,
+              required_capabilities: Optional[List[str]] = None,
+              task_type: Optional[Any] = None) -> Any:
+        """Return a route result exposing ``should_switch``, ``target()``,
+        ``task_type`` and ``decision``."""
+
+
+# Presentation supplies this to ask the human. Receives the proposal so the
+# dialog can explain it; returns True to approve. Manual mode only.
+ConfirmFn = Callable[[RoutingDecision], bool]
+
+
+class RoutingApplicationService:
+    """Decides which provider/model one turn runs on.
+
+    Args:
+        router: the scoring engine (see :class:`RoutingPort`).
+        mode_reader: ``surface -> mode string``; production passes the per-workspace
+            lookup ``AppContext.project_routing_mode``. Injected rather than read
+            from config here so this layer stays free of config plumbing that
+            EPIC R02 is rewriting in parallel.
+    """
+
+    def __init__(self, router: RoutingPort,
+                 mode_reader: Optional[Callable[[str], str]] = None) -> None:
+        self._router = router
+        self._mode_reader = mode_reader
+
+    # -- main entry point -------------------------------------------------- #
+    def route_turn(
+        self,
+        surface: str,
+        prompt: str,
+        current_provider: str,
+        current_model: str,
+        *,
+        mode: Optional[str] = None,
+        confirm: Optional[ConfirmFn] = None,
+        required_capabilities: Optional[Sequence[str]] = None,
+        task_type: Optional[Any] = None,
+    ) -> RoutingDecision:
+        """Decide what to run this turn on. Never raises.
+
+        A routing failure must never block a message: any unexpected error
+        degrades to "keep the current model", which is exactly what all three
+        legacy copies did with a bare ``except`` - made explicit and testable here.
+        """
+        resolved_mode = RoutingMode.parse(mode if mode is not None else self._read_mode(surface))
+        keep = self._keep(resolved_mode, current_provider, current_model,
+                          reason="routing off - keeping current model")
+
+        # An empty prompt carries no signal to classify, so routing cannot make a
+        # meaningful choice; the same guard exists in all three legacy copies.
+        if resolved_mode is RoutingMode.OFF or not (prompt or "").strip():
+            return keep
+
+        # FALLBACK never switches up front - it only reacts to a failure, which
+        # the caller reports through fallback_after_failure().
+        if resolved_mode is RoutingMode.FALLBACK:
+            return self._keep(resolved_mode, current_provider, current_model,
+                              reason="fallback mode - switching only after a failure")
+
+        try:
+            result = self._router.route(
+                surface, prompt, current_provider, current_model,
+                mode_override=resolved_mode.value,
+                required_capabilities=list(required_capabilities) if required_capabilities else None,
+                task_type=task_type,
+            )
+        except Exception:  # noqa: BLE001 - routing must never break a turn
+            return self._keep(resolved_mode, current_provider, current_model,
+                              reason="routing engine failed - keeping current model")
+
+        proposal = self._to_decision(result, resolved_mode, current_provider, current_model)
+        if not proposal.switched:
+            return proposal
+
+        # Manual mode: the proposal only becomes a switch once a human approves.
+        if resolved_mode is RoutingMode.MANUAL:
+            if confirm is None or not self._ask(confirm, proposal):
+                return self._keep(resolved_mode, current_provider, current_model,
+                                  reason="switch declined - keeping current model",
+                                  task_type=proposal.task_type, declined=True)
+        return proposal
+
+    # -- failure recovery -------------------------------------------------- #
+    def fallback_after_failure(
+        self,
+        surface: str,
+        prompt: str,
+        failed_provider: str,
+        failed_model: str,
+        *,
+        mode: Optional[str] = None,
+        required_capabilities: Optional[Sequence[str]] = None,
+        task_type: Optional[Any] = None,
+    ) -> Optional[RoutingDecision]:
+        """Pick a replacement after ``failed_provider/failed_model`` failed.
+
+        Returns None when there is nothing to fall back to, so the caller can
+        surface the original error instead of retrying forever. Available in
+        AUTO and FALLBACK; OFF and MANUAL keep the user's model on failure too,
+        because silently moving work to another model is exactly what those two
+        modes exist to prevent.
+        """
+        resolved_mode = RoutingMode.parse(mode if mode is not None else self._read_mode(surface))
+        if resolved_mode not in (RoutingMode.AUTO, RoutingMode.FALLBACK):
+            return None
+
+        try:
+            # Asked in AUTO so the engine ranks candidates rather than short-
+            # circuiting on FALLBACK's "never switch up front" rule; the failed
+            # model is passed as current so any positive gain beats it.
+            result = self._router.route(
+                surface, prompt, failed_provider, failed_model,
+                mode_override=RoutingMode.AUTO.value,
+                required_capabilities=list(required_capabilities) if required_capabilities else None,
+                task_type=task_type,
+            )
+        except Exception:  # noqa: BLE001 - a broken router must not mask the real error
+            return None
+
+        decision = self._to_decision(result, resolved_mode, failed_provider, failed_model)
+        # A "switch" back to the model that just failed would retry the outage.
+        if not decision.switched or (decision.provider, decision.model) == (failed_provider, failed_model):
+            return None
+        return RoutingDecision(
+            mode=resolved_mode, provider=decision.provider, model=decision.model,
+            switched=True, task_type=decision.task_type, score_gain=decision.score_gain,
+            reason=f"{failed_provider}/{failed_model} failed - falling back to "
+                   f"{decision.provider}/{decision.model}",
+            previous_provider=failed_provider, previous_model=failed_model,
+        )
+
+    # -- internals --------------------------------------------------------- #
+    def _read_mode(self, surface: str) -> str:
+        """Per-surface mode from the injected reader ('off' when none supplied)."""
+        if self._mode_reader is None:
+            return RoutingMode.OFF.value
+        try:
+            return self._mode_reader(surface) or RoutingMode.OFF.value
+        except Exception:  # noqa: BLE001 - a config read must not break a turn
+            return RoutingMode.OFF.value
+
+    @staticmethod
+    def _keep(mode: RoutingMode, provider: str, model: str, *, reason: str,
+              task_type: str = "", declined: bool = False) -> RoutingDecision:
+        """A no-switch decision that still names the model to run on."""
+        return RoutingDecision(mode=mode, provider=provider, model=model, switched=False,
+                               task_type=task_type, reason=reason, declined=declined,
+                               previous_provider=provider, previous_model=model)
+
+    @staticmethod
+    def _ask(confirm: ConfirmFn, proposal: RoutingDecision) -> bool:
+        """Run the confirm callback, treating any failure as "declined".
+
+        The callback opens a modal dialog in production; if that raises (window
+        already closing, for instance) the safe answer is to keep the user's own
+        model rather than to switch without consent.
+        """
+        try:
+            return bool(confirm(proposal))
+        except Exception:  # noqa: BLE001
+            return False
+
+    @staticmethod
+    def _to_decision(result: Any, mode: RoutingMode,
+                     current_provider: str, current_model: str) -> RoutingDecision:
+        """Translate the engine's route result into a :class:`RoutingDecision`.
+
+        Defensive about the result shape on purpose: this is the seam between the
+        new layer and a legacy module still under refactor, and a missing
+        attribute must degrade to "keep current model" instead of raising into
+        the middle of a chat turn.
+        """
+        inner = getattr(result, "decision", None)
+        task_type = getattr(getattr(result, "task_type", None), "value", "") or ""
+        gain = float(getattr(inner, "score_gain", 0.0) or 0.0)
+        reason = str(getattr(inner, "reason", "") or "")
+
+        target = None
+        if getattr(result, "should_switch", False):
+            getter = getattr(result, "target", None)
+            target = getter() if callable(getter) else None
+
+        if not target:
+            return RoutingDecision(mode=mode, provider=current_provider, model=current_model,
+                                   switched=False, task_type=task_type, score_gain=gain,
+                                   reason=reason or "no better model - keeping current",
+                                   previous_provider=current_provider,
+                                   previous_model=current_model)
+
+        provider, model = target
+        return RoutingDecision(mode=mode, provider=provider or current_provider, model=model,
+                               switched=True, task_type=task_type, score_gain=gain, reason=reason,
+                               previous_provider=current_provider, previous_model=current_model)
+
+
+__all__ = ["RoutingApplicationService", "RoutingDecision", "RoutingMode",
+           "RoutingPort", "normalize_mode", "is_valid_mode"]

application/monitoring/__init__.py

@@ -0,0 +1,18 @@
+"""Read-only query services for monitoring/dashboard screens (EPIC R08).
+
+⚠️ Ownership note (R08-T13): per ``docs/refactor/Feature_Architecture_
+Proposal.md``'s file-split diagram, ``dashboard_query_service.py`` lives
+under ``application/monitoring/`` alongside the Dashboard split — but the
+SAME document's "Ranh giới phân hệ" table assigns ``application/monitoring/``
+to Team Nam (R08-T07→T10, Monitoring's own 8-tab split). This directory did
+not exist yet when Team Hoa reached R08-T13, so creating it here does not
+collide with any file Team Nam has written — same situation R06-T02 flagged
+for ``infrastructure/persistence/json/atomic_write.py`` vs. Team Nam's
+planned ``atomic_json_file.py``. Team Nam should confirm when they start
+R08-T07→T10 whether ``DashboardQueryService`` belongs here permanently or
+should move once Monitoring's own query service exists.
+"""
+
+from .dashboard_query_service import DashboardQueryService
+
+__all__ = ["DashboardQueryService"]

application/monitoring/dashboard_query_service.py

@@ -0,0 +1,110 @@
+"""DashboardQueryService - read-only usage/cost queries for the Dashboard
+screen (R08-T13, extracted from ``ui/dashboard_tab.py::DashboardTab``, lines
+196-199/256-261/284-322 of the original 437-line file: ``_pricing``,
+``_period_range``'s date-math, and the ``period_totals``/``period_breakdown``
+calls ``_refresh_chart`` made directly).
+
+``ui/dashboard_tab.py`` called ``core/usage_tracker.py``/``core/model_
+pricing.py`` directly from FIVE different methods spread across what is now
+three widgets (``token_usage_card_widget.py``, ``usage_chart_widget.py``,
+``habits_widget.py``) — each recomputing the same merged pricing dict. This
+service is the one place that merge happens now; the three widgets share it
+instead of each calling ``core.usage_tracker``/``core.model_pricing`` on
+their own.
+
+Pure Python: no Qt. Wraps ``core/usage_tracker.py`` (a plain-Python module
+already) rather than reimplementing any of its date/cost math.
+"""
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Any, Dict, List, Tuple
+
+
+class DashboardQueryService:
+    """Usage/cost queries scoped to one ``AppContext``.
+
+    Args:
+        ctx: ``AppContext`` — read for ``ctx.config`` (pricing table,
+            currency, budget) and nothing else; this class does no I/O of
+            its own beyond what ``core.usage_tracker`` already does.
+    """
+
+    def __init__(self, ctx: Any) -> None:
+        self.ctx = ctx
+
+    def pricing(self) -> Dict[str, Any]:
+        """The merged price table (defaults + user overrides), synced from
+        Monitoring's model-pricing table first so cost figures always agree
+        between the two screens."""
+        from cowork_local.core import model_pricing as mp
+        from cowork_local.core import usage_tracker as ut
+
+        mp.sync_to_usage(self.ctx.config)
+        return {**ut.DEFAULT_PRICING, **(self.ctx.config.data.get("usage") or {})}
+
+    def period_range(self, granularity: str, offset: int) -> Tuple[date, date]:
+        """The SELECTED period as an inclusive ``(start, end)`` date range —
+        drives every widget on the screen (cards, chart, habits)."""
+        from cowork_local.core import usage_tracker as ut
+
+        start, end = ut.period_bounds(granularity, offset)
+        return start, end - timedelta(days=1)   # load_events end is inclusive
+
+    def summary(self, start: date, end: date) -> Dict[str, Any]:
+        """Everything the stat cards + habits panel need for one period:
+        the raw events, ``usage_tracker.summarize``'s aggregate stats, the
+        per-bucket costs, and their total — computed once so both widgets
+        read the same numbers instead of loading events twice."""
+        from cowork_local.core import usage_tracker as ut
+
+        events = ut.load_events(start, end)
+        pricing = self.pricing()
+        stats = ut.summarize(events)
+        costs = ut.cost_usd_events(events, pricing)
+        return {
+            "events": events,
+            "pricing": pricing,
+            "stats": stats,
+            "costs": costs,
+            "total_cost": sum(costs.values()),
+        }
+
+    def chart_series(self, granularity: str, offset: int, metric: str
+                     ) -> List[Tuple[str, float]]:
+        """``(label, value)`` points for the spline chart — WEEK -> 7 days,
+        MONTH -> weeks, YEAR -> 12 months, in whichever ``metric``
+        ("tokens" | "cost") was selected."""
+        from cowork_local.core import usage_tracker as ut
+
+        events = ut.load_events()   # all events; breakdown slices by period
+        pricing = self.pricing()
+        parts = ut.period_breakdown(events, granularity, pricing, offset=offset)
+        mi = 0 if metric == "tokens" else 1   # (label, tokens, cost) -> +1 for the value
+        return [(row[0], float(row[mi + 1])) for row in parts]
+
+    def period_totals(self, granularity: str, offset: int) -> Tuple[float, float]:
+        """``(tokens, cost)`` totals for one period — used to compute the
+        vs-previous-period delta the chart's reference line shows."""
+        from cowork_local.core import usage_tracker as ut
+
+        events = ut.load_events()
+        return ut.period_totals(events, granularity, self.pricing(), offset)
+
+    def period_range_label(self, granularity: str, offset: int) -> str:
+        from cowork_local.core import usage_tracker as ut
+
+        return ut.period_range_label(granularity, offset)
+
+    def budget_status(self):
+        from cowork_local.core import usage_tracker as ut
+
+        return ut.budget_status(self.ctx.config)
+
+    def set_budget(self, amount: float, currency: str) -> None:
+        from cowork_local.core import usage_tracker as ut
+
+        ut.set_budget(self.ctx.config, amount, currency)
+
+
+__all__ = ["DashboardQueryService"]

application/scheduling/__init__.py

@@ -0,0 +1,6 @@
+"""Application services for Schedule Task (EPIC R07)."""
+
+from .ai_task_planner_service import AiTaskPlannerService
+from .task_application_service import MoveResult, RunNowResult, TaskApplicationService
+
+__all__ = ["TaskApplicationService", "RunNowResult", "MoveResult", "AiTaskPlannerService"]

application/scheduling/ai_task_planner_service.py

@@ -0,0 +1,94 @@
+"""AiTaskPlannerService - AI-generate / import task lists, outside the widget
+(R07-T05).
+
+``ui/schedule_task_tab.py``'s ``_AiCreateDialog`` already delegates the
+actual planning to two existing pure functions —
+``core/ai_task_planner.py::plan_tasks`` (natural-language description ->
+task dicts, via the active provider) and
+``core/task_import.py::import_tasks`` (Excel/CSV/JSON -> task dicts) — so
+this service does not reimplement either. What it DOES own is one small
+piece of business logic that currently only exists inside the dialog's
+``AgentWorker`` job closure (``_generate``'s ``job()``): every AI-generated
+task must carry the SAME file/link attachments the user attached to the
+request, so they're available again at run time, not just visible to the
+planner while it drafts the task list. Leaving that step trapped in a Qt
+worker closure means it can only be exercised by driving the real dialog;
+here it's a plain, independently testable method.
+
+Pure Python: no Qt import. The provider is a constructor-injected factory
+(``() -> Provider``, no arguments — matches ``AppContext.build_active_
+provider``), the same dependency-inversion shape
+``application/conversations/conversation_application_service.py`` (R04-T03)
+uses for ITS provider factory.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+
+ProviderFactory = Callable[[], Any]
+CancelFn = Callable[[], bool]
+
+
+class AiTaskPlannerService:
+    """AI task generation + file/Excel/CSV/JSON import, for
+    ``presentation/scheduling/ai_task_creator_dialog.py`` and
+    ``ai_task_import_dialog.py`` (R08-T11) to call instead of importing
+    ``core.ai_task_planner``/``core.task_import`` directly.
+
+    Args:
+        provider_factory: ``() -> Provider``. Production passes
+            ``AppContext.build_active_provider``; tests pass a lambda
+            returning a :class:`FakeProvider`.
+    """
+
+    def __init__(self, provider_factory: Optional[ProviderFactory] = None) -> None:
+        self._provider_factory = provider_factory
+
+    def plan(
+        self,
+        description: str,
+        *,
+        file_paths: Sequence[str] = (),
+        links: Sequence[str] = (),
+        provider: Any = None,
+        cancel: Optional[CancelFn] = None,
+    ) -> List[Dict[str, Any]]:
+        """Turn ``description`` into a list of NOT-yet-saved task dicts.
+
+        ``provider`` overrides the constructor's factory for this one call
+        (useful for tests, or a caller that already resolved a provider);
+        omit it to use the injected factory. Raises ``RuntimeError`` when
+        no provider is available at all, or when the model's reply had no
+        parseable task list (same error ``core.ai_task_planner.plan_tasks``
+        already raises).
+        """
+        resolved = provider if provider is not None else self._resolve_provider()
+        from cowork_local.core.ai_task_planner import plan_tasks
+
+        planned = plan_tasks(resolved, description, cancel=cancel)
+        # Attachments apply to EVERY generated task so they're still there
+        # when the task actually runs, not just while the planner drafts it
+        # (see module docstring — this used to only happen inside the
+        # dialog's worker closure).
+        for task in planned:
+            task["input"]["file_paths"] = list(file_paths)
+            task["input"]["links"] = list(links)
+        return planned
+
+    def import_file(self, path: Union[str, Path]) -> List[Dict[str, Any]]:
+        """Excel/CSV/JSON -> NOT-yet-saved task dicts, auto-chained in file
+        order. Raises ``ValueError`` with a human-readable message on an
+        unusable/unsupported file (same contract
+        ``core.task_import.import_tasks`` already has)."""
+        from cowork_local.core.task_import import import_tasks
+
+        return import_tasks(path)
+
+    def _resolve_provider(self) -> Any:
+        if self._provider_factory is None:
+            raise RuntimeError("No provider available to plan tasks.")
+        return self._provider_factory()
+
+
+__all__ = ["AiTaskPlannerService"]

application/scheduling/task_application_service.py

@@ -0,0 +1,172 @@
+"""TaskApplicationService - task CRUD + dispatch, outside the widget (R07-T04).
+
+``ui/schedule_task_tab.py`` currently does all of this by importing
+``core/tasks.py`` module functions directly and calling
+``self.scheduler.run_now(...)`` inline inside Qt slot methods
+(``_run_now``, ``_context_menu``'s duplicate/pause/delete branches,
+``_on_task_dropped``'s per-lane business rules). None of it is Qt — it's
+plain CRUD plus a few small rules ("a manual task never auto-runs",
+"dropping a card on Done disables its schedule so it won't re-fire",
+"dropping on Scheduled with no time set needs the editor, not a silent
+no-op") — but it can only be exercised today by driving the real widget.
+
+This service is the seam ``presentation/scheduling/kanban_board_widget.py``
+(R08-T11) calls instead: same rules, same
+:class:`~infrastructure.persistence.json.task_repository_impl.TaskRepository`
+underneath, testable with no Qt at all.
+
+Pure Python: no Qt import. ``run_now`` dispatch is a plain injected callable
+(production wires ``TaskScheduler.run_now``; tests inject a stub), the same
+constructor-injection shape ``application/conversations/conversation_
+application_service.py`` (R04-T03) uses for its provider factory.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+# "TaskRepository" here is a Protocol-shaped name, not an import: this module
+# only calls .get/.save/.delete/.duplicate, so any object with that shape
+# (the real infrastructure.persistence.json.task_repository_impl.TaskRepository,
+# or a test double) works without this file importing infrastructure/ at
+# module scope.
+RunNowFn = Callable[[str], bool]
+
+
+@dataclass
+class RunNowResult:
+    """Outcome of asking a task to run immediately.
+
+    ``reason`` is one of ``""`` (ok), ``"not_found"``, ``"manual_task"``
+    (manual tasks never auto-run — spec: they exist to be run by a human),
+    ``"no_scheduler"`` (no ``run_now`` callable was wired in), or
+    ``"already_running"`` (the scheduler's own dedupe rejected it).
+    """
+
+    ok: bool
+    reason: str = ""
+
+
+@dataclass
+class MoveResult:
+    """Outcome of dropping a task card onto a Kanban lane
+    (``move_to_status``). The caller (kanban widget) uses the flags to decide
+    what to show — a full re-render, a "task is running" toast, or opening
+    the task editor — without re-deriving the business rule itself."""
+
+    task: Optional[Dict[str, Any]]
+    blocked: bool = False          # dropped while already running — ignored
+    ran_now: bool = False          # dropped on the Running lane — dispatched
+    run_now_result: Optional[RunNowResult] = None
+    needs_schedule: bool = False   # dropped on Scheduled with no run_at set — needs editing
+
+
+class TaskApplicationService:
+    """CRUD + dispatch for Schedule Task, backed by a ``TaskRepository``.
+
+    Args:
+        repository: a ``TaskRepository``-shaped object (``.get``, ``.save``,
+            ``.delete``, ``.duplicate``). Production passes
+            ``infrastructure.persistence.json.task_repository_impl.
+            TaskRepository()``; tests pass one scoped to a ``tmp_path``.
+        run_now: ``(task_id) -> bool``. Production passes
+            ``TaskScheduler.run_now``; ``None`` means no scheduler is wired
+            (matches the widget's own "no scheduler" guard today).
+    """
+
+    def __init__(self, repository: Any, run_now: Optional[RunNowFn] = None) -> None:
+        self._repository = repository
+        self._run_now = run_now
+
+    # -- single-task actions ------------------------------------------------ #
+    def run_now(self, task_id: str) -> RunNowResult:
+        """Dispatch ``task_id`` immediately. A "Run now" always counts as
+        manual approval (spec §13) — this is the ONE path that bypasses
+        ``execution.requires_approval``, same as the scheduler's own
+        ``run_now`` already does."""
+        task = self._repository.get(task_id)
+        if task is None:
+            return RunNowResult(False, "not_found")
+        if task.get("task_type") == "manual":
+            return RunNowResult(False, "manual_task")
+        if self._run_now is None:
+            return RunNowResult(False, "no_scheduler")
+        ok = self._run_now(task_id)
+        return RunNowResult(ok, "" if ok else "already_running")
+
+    def duplicate(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """A saved copy with a fresh identity — see
+        ``core/tasks.py::duplicate_task`` for what's preserved/reset."""
+        task = self._repository.get(task_id)
+        if task is None:
+            return None
+        dup = self._repository.duplicate(task)
+        self._repository.save(dup)
+        return dup
+
+    def toggle_pause(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """Pause a task, or resume a paused one back to Backlog (matches
+        ``ui/schedule_task_tab.py``'s context-menu action exactly — resuming
+        does NOT restore whatever status the task had before pausing, only
+        Backlog, so the user re-schedules explicitly rather than a stale
+        schedule silently re-firing)."""
+        task = self._repository.get(task_id)
+        if task is None:
+            return None
+        task["status"] = "backlog" if task.get("status") == "paused" else "paused"
+        self._repository.save(task)
+        return task
+
+    def delete(self, task_id: str) -> bool:
+        if self._repository.get(task_id) is None:
+            return False
+        self._repository.delete(task_id)
+        return True
+
+    def bulk_delete(self, task_ids: List[str]) -> int:
+        """Delete every id in ``task_ids``; returns how many actually
+        existed (mirrors ``_confirm_and_delete_selected``'s best-effort
+        loop — a stale id in the selection doesn't abort the rest)."""
+        return sum(1 for tid in task_ids if self.delete(tid))
+
+    # -- Kanban drag/drop ----------------------------------------------------- #
+    def move_to_status(self, task_id: str, new_status: str) -> Optional[MoveResult]:
+        """Apply the business rule behind dropping a card into a lane
+        (``ui/schedule_task_tab.py::_on_task_dropped``, moved here so it's
+        testable without a real ``QListWidget`` drag gesture):
+
+        * already running -> the drop is ignored (a running task can't be
+          re-filed by dragging it).
+        * dropped on Running -> runs it now (counts as manual approval).
+        * dropped on Done -> marks it done AND disables its schedule, so a
+          repeating task marked done by hand doesn't quietly re-fire later.
+        * dropped on Scheduled with no ``run_at`` set yet -> saved as-is but
+          flagged ``needs_schedule`` — the caller should open the editor
+          rather than leave a Scheduled card that will never actually run.
+        * anything else -> plain status change.
+        """
+        task = self._repository.get(task_id)
+        if task is None:
+            return None
+        if task.get("status") == "running":
+            return MoveResult(task=task, blocked=True)
+        if new_status == "running":
+            result = self.run_now(task_id)
+            return MoveResult(task=self._repository.get(task_id), ran_now=True, run_now_result=result)
+        if new_status == "done":
+            task["status"] = "done"
+            task["schedule"]["enabled"] = False
+            self._repository.save(task)
+            return MoveResult(task=task)
+        task["status"] = new_status
+        if new_status == "scheduled" and not task["schedule"].get("enabled"):
+            if task["schedule"].get("run_at"):
+                task["schedule"]["enabled"] = True
+            else:
+                self._repository.save(task)
+                return MoveResult(task=task, needs_schedule=True)
+        self._repository.save(task)
+        return MoveResult(task=task)
+
+
+__all__ = ["TaskApplicationService", "RunNowResult", "MoveResult"]

application/workspaces/__init__.py

@@ -0,0 +1,17 @@
+"""Workspace file operations for non-agent-loop callers (EPIC R06, R08)."""
+
+from .ai_edit_output import parse_ai_output, split_code_block
+from .file_preview_helpers import is_probably_text, pptx_available, read_text
+from .file_workspace_service import FileWorkspaceService
+from .graph_index_service import extract_file_contents, pdf_to_markdown
+
+__all__ = [
+    "FileWorkspaceService",
+    "read_text",
+    "is_probably_text",
+    "pptx_available",
+    "split_code_block",
+    "parse_ai_output",
+    "pdf_to_markdown",
+    "extract_file_contents",
+]

application/workspaces/ai_edit_output.py

@@ -0,0 +1,40 @@
+"""Parse an AI file-edit reply into its parts (R08-T12, moved out of
+``ui/folder_tab.py`` — that file's module-level ``_split_code_block``/
+``_parse_ai_output``, lines 1536-1562 of the original 1587-line file). Pure
+string parsing, no Qt — used by ``presentation/folder/ai_file_editor_dialog.py``
+to turn a model's raw reply into a proposed edit.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+
+def split_code_block(text: str) -> Tuple[Optional[str], str]:
+    """Split an AI reply into ``(file_content, summary)``. ``file_content``
+    is the first fenced code block (the edited file); ``summary`` is any
+    prose before it. Returns ``(None, text)`` when there's no code block."""
+    m = re.search(r"```[^\n]*\n(.*?)```", text or "", re.DOTALL)
+    if not m:
+        return None, (text or "")
+    return m.group(1), (text[:m.start()].strip())
+
+
+def parse_ai_output(text: str) -> Tuple[Optional[str], Optional[str], str, List[Tuple[str, str]]]:
+    """Parse an AI edit reply into ``(target, content, summary, image_gens)``.
+    ``FILE: <path>`` names a NEW file to create; ``IMAGE_GEN: <prompt> =>
+    <path>`` lines request generated illustration images (relative paths)."""
+    content, summary = split_code_block(text)
+    target = None
+    m = re.search(r"(?mi)^\s*FILE:\s*(.+?)\s*$", text or "")
+    if m:
+        target = m.group(1).strip().strip("`\"'")
+    image_gens = []
+    for gm in re.finditer(r"(?mi)^\s*IMAGE_GEN:\s*(.+?)\s*=>\s*(\S+)\s*$", text or ""):
+        image_gens.append((gm.group(1).strip(), gm.group(2).strip().strip("`\"'")))
+    # Strip the directive lines out of the shown summary.
+    summary = re.sub(r"(?mi)^\s*(FILE|IMAGE_GEN):\s*.+?$", "", summary).strip()
+    return target, content, summary, image_gens
+
+
+__all__ = ["split_code_block", "parse_ai_output"]

application/workspaces/file_preview_helpers.py

@@ -0,0 +1,54 @@
+"""Pure helpers for previewing a file (R08-T12, moved out of
+``ui/folder_tab.py`` — that file's module-level functions
+``_read_text``/``_is_probably_text``/``_pptx_available``, lines 1519-1533 and
+1565-1587 of the original 1587-line file). No Qt, no widget state — the
+"is this file text? is pptx editing available?" questions the preview
+manager asks before it decides how to render something.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+_PPTX_READY = None   # cached: pptx-editing library available (after auto-install)
+
+
+def pptx_available() -> bool:
+    """True when python-pptx is importable. If it's MISSING, auto-download &
+    install it (via deps.ensure_module) so pptx editing 'just works' — cached
+    so the (one-time) install is attempted only once."""
+    global _PPTX_READY
+    if _PPTX_READY is None:
+        try:
+            from cowork_local.core.deps import ensure_module
+
+            _PPTX_READY = ensure_module("pptx", "python-pptx") is not None
+        except Exception:  # noqa: BLE001
+            _PPTX_READY = False
+    return _PPTX_READY
+
+
+def read_text(path: str) -> str:
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return f"[could not read file: {exc}]"
+
+
+def is_probably_text(path: str) -> bool:
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(4096)
+    except OSError:
+        return False
+    if b"\x00" in chunk:
+        return False
+    try:
+        chunk.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        # Latin-ish text still edits fine via errors="replace"; only reject on
+        # a hard binary signal (NUL above), so most source files pass.
+        return True
+
+
+__all__ = ["pptx_available", "read_text", "is_probably_text"]

application/workspaces/file_workspace_service.py

@@ -0,0 +1,81 @@
+"""FileWorkspaceService - the safe file operations File Explorer and the AI
+File Editor need, outside the agent tool loop (R06-T05).
+
+``ui/folder_tab.py`` (File Explorer) and the AI File Editor dialog need the
+exact same guarantees the agent's tools already have — path containment
+inside the workspace, precise context-anchored edits, syntax warnings on a
+bad Python write — but today that logic only exists wired to a model's tool
+call (``core/tools.py::execute_tool``). A UI action that isn't a tool call
+(browsing the tree, applying an AI-suggested diff from a review dialog) has
+no equivalent entry point of its own.
+
+This service IS that entry point. It reuses ``core/tools.py::execute_tool``
+verbatim - same dispatch table, same ``ToolContext`` containment check, same
+audit-log entry, same Python-syntax warning on write/edit - rather than
+re-implementing any of it, so a fix to one path fixes both. It only adds the
+:class:`~domain.workspaces.workspace_session.WorkspaceSession` seam: which
+workspace root a call is scoped to is decided by the session, not by
+whichever folder a widget happens to have open.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+class FileWorkspaceService:
+    """File operations scoped to one :class:`WorkspaceSession`.
+
+    Read-only by name (``list_tree``/``read_preview``) vs. writing
+    (``write_file``/``apply_edit``) mirrors the same READ/WRITE split
+    ``domain/tools/tool_registry.py`` uses for the agent's own tools - a
+    caller that only wants to browse never accidentally has write access.
+    """
+
+    def __init__(self, session) -> None:  # WorkspaceSession - see module docstring
+        self._session = session
+
+    def list_tree(self, rel: str = ".") -> Dict[str, Any]:
+        """Entries at ``rel`` (default: the workspace root)."""
+        return self._execute("list_dir", {"path": rel})
+
+    def read_preview(self, rel: str) -> Dict[str, Any]:
+        """A text file's content (truncated by
+        ``infrastructure/filesystem/file_tools.py::MAX_READ_BYTES``, same as
+        the agent's ``read_file`` tool)."""
+        return self._execute("read_file", {"path": rel})
+
+    def write_file(self, rel: str, content: str) -> Dict[str, Any]:
+        """Create or fully overwrite ``rel``."""
+        return self._execute("write_file", {"path": rel, "content": content})
+
+    def apply_edit(self, rel: str, old_string: str, new_string: str,
+                   replace_all: bool = False) -> Dict[str, Any]:
+        """Replace an exact snippet in an existing file - the same
+        context-anchored algorithm the agent's ``edit_file`` tool uses, so an
+        AI-suggested diff applies with the same precision and the same
+        "old_string not found / ambiguous" failure messages either path
+        would give the caller."""
+        return self._execute("edit_file", {
+            "path": rel, "old_string": old_string, "new_string": new_string,
+            "replace_all": replace_all,
+        })
+
+    # -- internals --------------------------------------------------------- #
+    def _tool_context(self):
+        """A ``ToolContext`` scoped to this session's workspace root.
+        ``flatten_writes=False`` (unlike Cowork's agent context) - File
+        Explorer must preserve whatever subfolder structure the user is
+        actually browsing, not collapse every write into the root."""
+        from cowork_local.infrastructure.filesystem.tool_context import ToolContext
+
+        return ToolContext(self._session.workspace_root, flatten_writes=False)
+
+    def _execute(self, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Dispatch through ``core/tools.py::execute_tool`` - see the module
+        docstring for why this delegates instead of reimplementing."""
+        from cowork_local.core.tools import execute_tool
+
+        return execute_tool(self._tool_context(), name, args)
+
+
+__all__ = ["FileWorkspaceService"]

application/workspaces/graph_index_service.py

@@ -0,0 +1,91 @@
+"""Temporary file-content extraction for Graph-RAG Q&A (R08-T14, moved out
+of ``ui/structure_graph_view.py`` — that file's module-level
+``_pdf_to_markdown``/``_extract_file_contents``, lines 964-1034 of the
+original 1035-line file). Runs inside the ask worker's job function so the
+answer is synthesized from real file content, not just the graph structure.
+
+Pure Python: no Qt. Best-effort throughout (never raises) — a failed
+extraction degrades to "no content for this file", not a broken Q&A turn.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+def pdf_to_markdown(pdf_path: str, out_dir: str) -> Optional[str]:
+    """Convert a PDF to Markdown with opendataloader-pdf when available
+    (richer structure than a plain text dump). Best-effort — returns None
+    if the package isn't installed or the call fails, so the caller falls
+    back to ``core/doc_extract.py``."""
+    try:
+        import opendataloader_pdf  # optional; auto-installed elsewhere if present
+    except Exception:  # noqa: BLE001
+        try:
+            from cowork_local.core.deps import ensure_module
+            if ensure_module("opendataloader_pdf", "opendataloader-pdf") is None:
+                return None
+            import opendataloader_pdf  # noqa: F811
+        except Exception:  # noqa: BLE001
+            return None
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    for call in (
+        lambda: opendataloader_pdf.convert(input_path=[str(pdf_path)], output_dir=str(out),
+                                           generate_markdown=True),
+        lambda: opendataloader_pdf.convert(input_path=str(pdf_path), output_dir=str(out)),
+        lambda: opendataloader_pdf.convert(str(pdf_path), str(out)),
+    ):
+        try:
+            call()
+            break
+        except TypeError:
+            continue
+        except Exception:  # noqa: BLE001
+            return None
+    mds = list(out.rglob(Path(pdf_path).stem + "*.md")) or list(out.rglob("*.md"))
+    for md in mds:
+        try:
+            return md.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+    return None
+
+
+def extract_file_contents(paths: List[str], cache: Dict[str, str], tmp_dir: str,
+                          max_files: int = 15, max_total: int = 120_000
+                          ) -> Tuple[str, Dict[str, str]]:
+    """Read the ACTUAL content of ``paths`` (PDF -> markdown via
+    opendataloader when available, else ``doc_extract`` for office/pdf/
+    text). Returns ``(block, cache)`` — ``block`` is the concatenated
+    content for the prompt (bounded), ``cache`` maps path -> text for
+    reuse. Never raises."""
+    from cowork_local.core import doc_extract
+
+    cache = dict(cache or {})
+    parts, total = [], 0
+    for p in paths[:max_files]:
+        if total >= max_total:
+            break
+        text = cache.get(p)
+        if text is None:
+            try:
+                if Path(p).suffix.lower() == ".pdf":
+                    text = pdf_to_markdown(p, tmp_dir)
+                    if not text:
+                        text, _n = doc_extract.extract_text(p)
+                else:
+                    text, _n = doc_extract.extract_text(p)
+            except Exception:  # noqa: BLE001
+                text = ""
+            cache[p] = text or ""
+        text = cache.get(p) or ""
+        if not text:
+            continue
+        chunk = text[: max(0, max_total - total)]
+        total += len(chunk)
+        parts.append(f'--- {Path(p).name} ({p}) ---\n{chunk}')
+    return ("\n\n".join(parts), cache)
+
+
+__all__ = ["pdf_to_markdown", "extract_file_contents"]

config.py

@@ -105,7 +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,
-        "sandbox_pw": "",                  # set through COWORK_SANDBOX_PASSWORD
+        "sandbox_pw": "quandh14",          # default password to unlock sandbox settings
         "rulebase_path": "",               # custom RULEBASE.md — attached to every agent execution
     },
     # Legacy generic-MCP-server list. MERGED into ext_connectors["other"] as of
@@ -173,7 +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": {
-        "unlock_code": "",                # set through COWORK_MS365_UNLOCK_CODE
+        "unlock_code": "quandh14",
         "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
@@ -294,10 +294,6 @@ def _apply_env_overrides(data: Dict[str, Any]) -> Dict[str, Any]:
         data["active_provider"] = os.environ["COWORK_ACTIVE_PROVIDER"]
     if os.getenv("COWORK_CA_BUNDLE"):
         data["tls_ca_bundle"] = os.environ["COWORK_CA_BUNDLE"]
-    if os.getenv("COWORK_SANDBOX_PASSWORD"):
-        data["agent_security"]["sandbox_pw"] = os.environ["COWORK_SANDBOX_PASSWORD"]
-    if os.getenv("COWORK_MS365_UNLOCK_CODE"):
-        data["ms365"]["unlock_code"] = os.environ["COWORK_MS365_UNLOCK_CODE"]
     return data
 
 
@@ -556,19 +552,25 @@ class AppConfig:
         return d
 
     def routing_mode_for(self, surface: str) -> str:
-        """Effective Off/Auto/Manual mode for a chat surface.
+        """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``. The value is validated through
+        ``application.model_routing.normalize_mode`` so the accepted vocabulary
+        is defined in exactly one place (R03-T03) - it used to be a literal
+        tuple repeated here and in state.py, and adding a mode to one copy but
+        not the others silently downgraded the user's choice to "off"."""
+        from .application.model_routing import normalize_mode
 
-        A per-surface override ("auto"/"manual"/"off") wins; an empty override
-        falls back to the global ``switch_mode``."""
         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 normalize_mode(override or routing.get("switch_mode", "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"
-        self.routing.setdefault("surface_modes", {})[surface] = mode
+        """Persist a chat surface's routing toggle selection."""
+        from .application.model_routing import normalize_mode
+
+        self.routing.setdefault("surface_modes", {})[surface] = normalize_mode(mode)
         self.save()
 
     @property

core/chat_agent.py

@@ -11,6 +11,8 @@ import re
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from ..application.conversations.tool_policy_gateway import ToolPolicyGateway
+from ..domain.tools import ToolCapability, default_registry
 from ..providers.base import Provider, ToolSpec
 from . import agent_roles
 from . import agent_security
@@ -27,6 +29,13 @@ from .tools import TOOL_SPECS, ToolContext, _snapshot, describe_action, execute_
 # Generator / helper scripts — never a final deliverable in Cowork's output.
 _SCRIPT_EXTS = {".py", ".pyw", ".js", ".mjs", ".cjs", ".ts", ".sh", ".bat", ".ps1", ".rb", ".pl"}
 
+# R05-T03/T04: replaces the literal ``name in ("run_command",
+# "install_package")`` check below with a capability lookup — EXECUTE is
+# exactly the capability those two (and only those two) built-in tools carry
+# (see domain/tools/tool_registry.py::BUILT_IN_CAPABILITIES). Copied per-turn
+# into ``turn_tool_policy`` inside run_cowork() once extra_tools are known.
+_COWORK_TOOL_REGISTRY = default_registry(TOOL_SPECS)
+
 EmitFn = Callable[[Dict[str, Any]], None]
 CancelFn = Callable[[], bool]
 
@@ -388,6 +397,19 @@ def run_cowork(
                       jira=(security_config.data.get("jira") if security_config else None))
     extra_tools = extra_tools or []
     extra_names = {t.name for t in extra_tools}
+    # R05-T04: MCP servers (core/mcp_client.py) and unified connectors
+    # (core/ext_connectors.py) — everything that arrives here as extra_tools —
+    # advertise no standard risk metadata, so each is tagged with the same
+    # conservative default (WRITE|EXECUTE|NETWORK) domain/tools/tool_registry.py
+    # uses for any unclassified tool. Copying the built-in registry per turn
+    # (cheap - under 20 entries) rather than mutating the shared module-level
+    # one keeps different turns' extra_tools from leaking into each other.
+    from ..domain.tools import ToolDescriptor, ToolRegistry
+    from ..domain.tools.tool_registry import UNKNOWN_SOURCE_CAPABILITIES
+    _turn_registry = ToolRegistry(_COWORK_TOOL_REGISTRY.all())
+    for _spec in extra_tools:
+        _turn_registry.register(ToolDescriptor.from_spec(_spec, UNKNOWN_SOURCE_CAPABILITIES))
+    turn_tool_policy = ToolPolicyGateway(_turn_registry, ToolCapability.EXECUTE)
     # update_plan drives the Plan panel (above Output); it produces no file.
     # Built-in tools the admin disabled (Monitoring → Tools) are filtered out.
     from .tools import enabled_tool_specs
@@ -489,6 +511,18 @@ def run_cowork(
                     preview = {"kind": "info", "title": name, "text": str(args)}
                     emit({"type": "tool_proposed", "id": tc_id, "name": name, "args": args,
                           "preview": preview})
+                    # R05-T04: MCP/connector tools used to run with NO permission
+                    # check at all — this is what closes that gap. Same policy,
+                    # same gate object as the built-in tools below.
+                    if not turn_tool_policy.allow(
+                        name, gate, {"name": name, "args": args, "preview": preview}
+                    ):
+                        result = {"ok": False, "output": "Rejected by user."}
+                        emit({"type": "tool_result", "id": tc_id, "name": name,
+                              "ok": False, "output": result["output"]})
+                        messages.append({"role": "tool", "tool_call_id": tc_id, "name": name,
+                                         "content": result["output"]})
+                        continue
                     result = extra_executor(name, args)
                     emit({"type": "tool_result", "id": tc_id, "name": name,
                           "ok": result.get("ok", False), "output": result.get("output", "")})
@@ -528,16 +562,18 @@ def run_cowork(
                 # Permission Management (Sandbox Security Layer) — only when a
                 # gate was actually supplied (Settings: "confirm before running
                 # commands"); None preserves the pre-existing auto-run behavior.
-                if gate is not None and name in ("run_command", "install_package"):
-                    approved = gate.request({"name": name, "args": args, "preview": preview})
-                    if not approved:
-                        result = {"ok": False, "output": "Rejected by user."}
-                        evt = {"type": "tool_result", "id": tc_id, "name": name,
-                              "ok": False, "output": result["output"]}
-                        emit(evt)
-                        messages.append({"role": "tool", "tool_call_id": tc_id,
-                                        "name": name, "content": result["output"]})
-                        continue
+                # R05-T03: gating is now capability-driven (see
+                # turn_tool_policy above) instead of a literal name tuple.
+                if not turn_tool_policy.allow(
+                    name, gate, {"name": name, "args": args, "preview": preview}
+                ):
+                    result = {"ok": False, "output": "Rejected by user."}
+                    evt = {"type": "tool_result", "id": tc_id, "name": name,
+                          "ok": False, "output": result["output"]}
+                    emit(evt)
+                    messages.append({"role": "tool", "tool_call_id": tc_id,
+                                    "name": name, "content": result["output"]})
+                    continue
 
                 if name == "save_file":
                     result = _do_save_file(output_dir, title, args)

core/code_agent.py

@@ -12,6 +12,8 @@ import re
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from ..application.conversations.tool_policy_gateway import ToolPolicyGateway
+from ..domain.tools import ToolCapability, ToolDescriptor, ToolRegistry
 from ..providers.base import Provider
 from . import agent_roles
 from . import agent_security
@@ -225,6 +227,14 @@ def run_code(
     # read/list ms365 tools count as "read-only, never confirm". Names are
     # the MCP-qualified "ms365__*" form the agent sees (see ms365_tools.py).
     gated_tools = WRITE_TOOLS | MS365_WRITE_TOOLS
+    # R05-T03/T04: ``gated_tools`` stays the authoritative name set (unchanged),
+    # but the actual confirm decision now goes through the same
+    # ToolPolicyGateway class run_cowork uses, instead of a separate
+    # hand-rolled ``if name in gated_tools`` + direct ``gate.request(...)``.
+    code_tool_policy = ToolPolicyGateway(
+        ToolRegistry(ToolDescriptor(n, "", {}, ToolCapability.WRITE) for n in gated_tools),
+        ToolCapability.WRITE,
+    )
     # In PLAN mode, don't advertise write/run tools (analysis only).
     advertised = [t for t in all_tools if t.name not in gated_tools] if plan else all_tools
     has_memory = any(t.name.startswith("cmem_") for t in extra_tools)
@@ -297,10 +307,11 @@ def run_code(
             agent_security.enforce_command(provider, name, args, security_config, emit,
                                            agent_kind="code")
 
-            if name in gated_tools:
-                approved = gate.request({"id": tc_id, "name": name, "args": args, "preview": preview})
-            else:
-                approved = True  # read-only tools (incl. codebase memory) never confirm
+            # read-only tools (incl. codebase memory) never consult the gate —
+            # code_tool_policy.requires_confirmation(name) is False for them.
+            approved = code_tool_policy.allow(
+                name, gate, {"id": tc_id, "name": name, "args": args, "preview": preview}
+            )
 
             if cancel():
                 return messages

core/history.py

@@ -66,7 +66,9 @@ def save_conversation(
         "outputs": list(outputs or []),
         "messages": messages,
     }
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    # R06-T02: atomic write - see infrastructure/persistence/json/atomic_write.py.
+    from ..infrastructure.persistence.json.atomic_write import write_json
+    write_json(path, payload)
     return path
 
 
@@ -78,15 +80,19 @@ def delete_conversation(path) -> None:
 
 
 def rename_conversation(path, new_title: str) -> None:
+    from ..infrastructure.persistence.json.atomic_write import write_json
+
     data = load_conversation(path)
     data["title"] = new_title
-    Path(path).write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    write_json(Path(path), data)
 
 
 def set_pinned(path, pinned: bool) -> None:
+    from ..infrastructure.persistence.json.atomic_write import write_json
+
     data = load_conversation(path)
     data["pinned"] = bool(pinned)
-    Path(path).write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    write_json(Path(path), data)
 
 
 def load_conversation(path: Path) -> Dict[str, Any]:

core/mcp_client.py

@@ -106,6 +106,13 @@ class McpServerConnection:
         if self._thread is not None:
             self._thread.join(timeout=5)
 
+    def is_alive(self) -> bool:
+        """True while the connection's background thread (and therefore its
+        event loop and subprocess) is still running — used by
+        ``infrastructure/mcp/mcp_source_manager.py`` (R05-T05) to tell a live
+        cached connection from one whose subprocess already died."""
+        return self._thread is not None and self._thread.is_alive()
+
     # ---- tools -----------------------------------------------------------
     def list_tool_specs(self) -> List[ToolSpec]:
         """The server's tools, wrapped as :class:`ToolSpec` — the same shape

core/projects.py

@@ -116,10 +116,12 @@ def new_project(name: str, description: str = "", instructions: str = "",
 
 def save_project(project: Project, directory: Path = None) -> Path:
     directory = directory or PROJECTS_DIR
-    directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{project.project_id}.json"
-    path.write_text(json.dumps(asdict(project), ensure_ascii=False, indent=2),
-                    encoding="utf-8")
+    # R06-T02: atomic write — a crash/kill between truncate and write used to
+    # leave a half-written project.json that load_project() then silently
+    # treats as "missing" (see infrastructure/persistence/json/atomic_write.py).
+    from ..infrastructure.persistence.json.atomic_write import write_json
+    write_json(path, asdict(project))
     return path
 
 

core/task_executors.py

@@ -248,9 +248,34 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
         "'error' (not silently skip it) if it genuinely can't be completed.\n\n"
         f"{prompt}"
     )
-    messages = [{"role": "user", "content": prompt}]
+    # One immutable snapshot of this run, then the shared turn service (R04-T05).
+    # The Schedule Task path used to assemble the run_cowork call itself, in
+    # parallel with ui/cowork_tab.py doing the same thing slightly differently -
+    # so a fix to one path silently missed the other. Both now go through
+    # ConversationApplicationService.
+    from ..application.conversations import ConversationApplicationService
+    from ..domain.agents import ConversationExecutionRequest
+
     session_id = new_session_id()
     project_id = project.project_id if project is not None else ""
+    project_context = projects.project_context_text(project)
+    conversation_service = ConversationApplicationService(
+        # The provider was already resolved above (admin agent / per-task
+        # override / machine default), so the factory just hands it back.
+        lambda _provider_id, _model: provider,
+        security_config=ctx.config,
+    )
+    turn = conversation_service.begin_turn(ConversationExecutionRequest.create(
+        prompt, [{"role": "user", "content": prompt}],
+        output_dir=str(out_dir), session_id=session_id, surface="task",
+        title=title, project_id=project_id, project_context=project_context,
+        # Tags every tool call in the audit log as a scheduled task rather than
+        # as the interactive Cowork tab.
+        agent_role=agent_roles.TASK,
+    ))
+    # The LIVE list the engine appends to - History is re-saved from it after
+    # every assistant message so a long run shows progress when reopened.
+    messages = turn.messages
     _save_history_session(ctx, task_type, title, messages, session_id, project_id)
     # Tell the scheduler the session now genuinely EXISTS on disk — it
     # refreshes History on this, not on the earlier "task_started" signal
@@ -269,14 +294,21 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
         elif ev.get("type") == "plan_set":
             last_plan_steps[:] = ev.get("steps") or []
 
-    project_context = projects.project_context_text(project)
     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)
+            # Typed events are rendered back into the legacy dict shape this
+            # module's autosave/plan tracking already consumes; it moves to
+            # AgentEvent directly once the scheduler UI migrates (EPIC R07/R08).
+            result = conversation_service.execute_turn(
+                turn,
+                on_event=lambda event: emit_and_autosave(event.to_dict()),
+                cancel=watched_cancel,
+            )
+            # This module's callers handle a failed run through an exception
+            # (execute_task writes error.txt from it), so re-raise the ORIGINAL
+            # error rather than reporting a silently empty answer.
+            result.raise_if_failed()
         else:
             from .code_agent import run_code
             limits, block_network = agent_security.sandbox_settings(ctx.config)

core/task_scheduler.py

@@ -17,7 +17,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Dict, Optional
 
-from PySide6.QtCore import QCoreApplication, QObject, QTimer, Signal
+from PySide6.QtCore import QObject, Signal
 
 from .tasks import (
     advance_after_run, chain_action, dependencies_met, due_tasks, format_run_at,
@@ -39,22 +39,32 @@ class TaskScheduler(QObject):
     # which fires before the worker thread has even begun).
     history_ready = Signal(str)        # task_id
 
-    def __init__(self, ctx, tasks_dir: Optional[Path] = None, parent=None):
+    def __init__(self, ctx, tasks_dir: Optional[Path] = None, parent=None, clock=None):
         super().__init__(parent)
         self.ctx = ctx
         self.tasks_dir = tasks_dir            # None → default TASKS_DIR
         self._workers: Dict[str, AgentWorker] = {}   # task_id → running worker
         self._retries: Dict[str, int] = {}
         self._session_ids: Dict[str, str] = {}       # task_id → its run's History session id
-        self._timer = QTimer(self)
-        self._timer.setInterval(TICK_MS)
-        self._timer.timeout.connect(self.tick)
+        # R07-T03: the QTimer this class used to own directly is now behind a
+        # small clock interface (start/stop/pump) — see
+        # platform/qt/qt_scheduler_clock.py::QtSchedulerClock. Defaulting to a
+        # real one here keeps every existing production call site (which
+        # never passes `clock=`) unchanged; tests inject
+        # tests/fakes/fake_clock.py::FakeClock to control ticks by hand with
+        # no Qt event loop running. Imported lazily so importing core.tasks/
+        # core.task_scheduler for the Qt-free logic doesn't require the Qt
+        # adapter module to even exist in a headless test context.
+        if clock is None:
+            from ..infrastructure.qt.qt_scheduler_clock import QtSchedulerClock
+            clock = QtSchedulerClock(self)
+        self._clock = clock
 
     # ---- lifecycle ----------------------------------------------------
     def start(self) -> None:
         self._recover_orphans()
         self.tick()          # catch up overdue tasks right at app start
-        self._timer.start()
+        self._clock.start(TICK_MS, self.tick)
 
     def stop(self) -> None:
         """Request every running worker to stop, then WAIT (bounded) for them
@@ -67,15 +77,15 @@ class TaskScheduler(QObject):
         ``_on_done`` (the only place that writes the run into the task's
         history) never runs. The task's real output can already be sitting on
         disk while its history stays stuck on "running" forever. Pumping
-        ``processEvents()`` here lets that queued signal actually get
-        delivered before the app finishes quitting.
+        the clock here lets that queued signal actually get delivered before
+        the app finishes quitting.
         """
-        self._timer.stop()
+        self._clock.stop()
         deadline = time.monotonic() + STOP_WAIT_SECS
         while self._workers and time.monotonic() < deadline:
             for w in list(self._workers.values()):
                 w.request_stop()
-            QCoreApplication.processEvents()
+            self._clock.pump()
             for w in list(self._workers.values()):
                 w.wait(50)
         # Anything still alive past the deadline is abandoned here;

core/tasks.py

@@ -151,7 +151,14 @@ def save_task(task: Dict[str, Any], directory: Path = None) -> Path:
     directory.mkdir(parents=True, exist_ok=True)
     task["updated_at"] = datetime.now().isoformat(timespec="seconds")
     path = task_path(task["task_id"], directory)
-    path.write_text(json.dumps(task, ensure_ascii=False, indent=2), encoding="utf-8")
+    # R07-T01: atomic write — same class of bug already fixed in
+    # core/projects.py and core/history.py at R06-T02 (plain write_text has a
+    # gap between truncate and write; a crash there leaves a half-written
+    # tasks/<id>.json that load_task() then silently treats as "missing",
+    # dropping the task). Lazy import to match the existing call sites and
+    # avoid a core -> infrastructure import at module load time.
+    from ..infrastructure.persistence.json.atomic_write import write_json
+    write_json(path, task)
     return path
 
 
@@ -287,36 +294,32 @@ def chain_error(tasks: List[Dict[str, Any]], task_id: str,
 
 
 # ---- schedule math --------------------------------------------------------
-def _is_excluded_day(dt: datetime, sched: Dict[str, Any]) -> bool:
-    """True when ``dt`` falls on a day this schedule must skip: a weekend
-    (working_days_only) or a public holiday of the configured country."""
-    if sched.get("working_days_only") and dt.weekday() >= 5:   # 5=Sat, 6=Sun
-        return True
-    if sched.get("skip_holidays"):
+# R07-T02: the actual date/cron math now lives in
+# domain/tasks/schedule_calculator.py::ScheduleCalculator (pure Python, unit
+# tested on its own — see tests/unit/test_schedule_calculator.py). Everything
+# below is a thin wrapper kept for backward compatibility: task_scheduler.py,
+# task_executors.py and ui/task_editor_dialog.py all still import these
+# module-level names from core.tasks, and core/holiday_calendar.py::is_holiday
+# / core/cron.py::Cron are only wired in HERE (lazily, matching the previous
+# lazy-import style) — domain/ is not allowed to import core/ (ADR-001 I2).
+_calculator: Optional[Any] = None
+
+
+def _get_calculator():
+    global _calculator
+    if _calculator is None:
+        from .cron import Cron
         from .holiday_calendar import is_holiday
+        from ..domain.tasks.schedule_calculator import ScheduleCalculator
 
-        if is_holiday(dt.date(), sched.get("holiday_country", "")):
-            return True
-    return False
-
-
-def _add_month(dt: datetime) -> datetime:
-    import calendar
-
-    year = dt.year + (1 if dt.month == 12 else 0)
-    month = 1 if dt.month == 12 else dt.month + 1
-    day = min(dt.day, calendar.monthrange(year, month)[1])
-    return dt.replace(year=year, month=month, day=day)
+        _calculator = ScheduleCalculator(is_holiday=is_holiday, make_cron=Cron)
+    return _calculator
 
 
 def shift_off_excluded_days(dt: datetime, sched: Dict[str, Any]) -> datetime:
     """Push ``dt`` forward one day at a time until it lands on an allowed day
     (same time of day) — used for one-time schedules set on a weekend/holiday."""
-    guard = 0
-    while _is_excluded_day(dt, sched) and guard < 400:
-        dt += timedelta(days=1)
-        guard += 1
-    return dt
+    return _get_calculator().shift_off_excluded_days(dt, sched)
 
 
 def compute_next_run(task: Dict[str, Any], after: datetime) -> Optional[datetime]:
@@ -324,57 +327,12 @@ def compute_next_run(task: Dict[str, Any], after: datetime) -> Optional[datetime
     (daily / weekly / monthly / cron), or None for one-shot schedules.
     Occurrences on excluded days (weekends with working_days_only, public
     holidays with skip_holidays+holiday_country) are skipped forward."""
-    sched = task.get("schedule", {})
-    repeat = sched.get("repeat_type", "none")
-
-    if repeat == "cron":
-        from .cron import Cron, CronError
-
-        try:
-            cron = Cron(sched.get("cron_expression") or "")
-        except CronError:
-            return None
-        nxt = cron.next_after(after)
-        guard = 0
-        while nxt is not None and _is_excluded_day(nxt, sched) and guard < 400:
-            nxt = cron.next_after(nxt)
-            guard += 1
-        return nxt
-
-    base = parse_run_at(sched.get("run_at"))
-    if base is None:
-        return None
-    if repeat == "daily":
-        advance = lambda d: d + timedelta(days=1)          # noqa: E731
-    elif repeat == "weekly":
-        advance = lambda d: d + timedelta(weeks=1)         # noqa: E731
-    elif repeat == "monthly":
-        advance = _add_month
-    else:
-        return None
-    nxt = base
-    while nxt <= after:
-        nxt = advance(nxt)
-    guard = 0
-    while _is_excluded_day(nxt, sched) and guard < 400:
-        nxt = advance(nxt)
-        guard += 1
-    return nxt
+    return _get_calculator().compute_next_run(task, after)
 
 
 def due_tasks(tasks: List[Dict[str, Any]], now: datetime) -> List[Dict[str, Any]]:
     """Tasks that should start now: Scheduled + schedule enabled + run_at due."""
-    due = []
-    for t in tasks:
-        if t.get("status") != "scheduled":
-            continue
-        sched = t.get("schedule", {})
-        if not sched.get("enabled"):
-            continue
-        run_at = parse_run_at(sched.get("run_at"))
-        if run_at is not None and run_at <= now:
-            due.append(t)
-    return due
+    return _get_calculator().due_tasks(tasks, now)
 
 
 # ---- post-run bookkeeping (pure; scheduler applies + saves) ---------------

core/tools.py

@@ -3,79 +3,29 @@
 Every path is resolved relative to the working directory and must stay inside
 it (path-traversal is rejected). ``run_command`` executes inside the workdir
 with a timeout and captured output.
+
+R05-T02: the actual handlers (``read_file``/``list_dir``/``write_file``/
+``edit_file``/``run_command``/``install_package``/``fetch_url``/
+``jira_search``/``jira_get_issue``) now live in
+``infrastructure/filesystem/{file_tools,command_tools,fetch_tools}.py``, split
+out of what used to be one big if/elif chain here. This module is the
+strangler-fig shim (ADR-001 section 4): it re-exports ``ToolContext``/
+``ToolError`` (actually defined in
+``infrastructure/filesystem/tool_context.py`` now) so every existing
+``from .tools import ToolContext`` keeps working, and ``execute_tool``
+dispatches through a small ``{name: handler}`` table built from the moved
+modules instead of the chain itself.
 """
 from __future__ import annotations
 
-import ast
 import difflib
-import os
-from dataclasses import dataclass
-from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from ..infrastructure.filesystem import command_tools, fetch_tools, file_tools
+from ..infrastructure.filesystem.command_tools import _snapshot  # noqa: F401 - re-export, core/chat_agent.py imports this name
+from ..infrastructure.filesystem.tool_context import CancelFn, ToolContext, ToolError  # noqa: F401 - re-export
 from ..providers.base import ToolSpec
 
-CancelFn = Callable[[], bool]
-
-MAX_READ_BYTES = 200_000
-COMMAND_TIMEOUT = 120  # seconds
-
-
-class ToolError(Exception):
-    pass
-
-
-def _flatten_rel(rel: str) -> str:
-    """Collapse a sub-folder path down to a bare filename so the file lands in the
-    workdir root — EXCEPT the ``.scratch`` sandbox subtree, which is preserved.
-
-    Used by the Cowork agent (flatten_writes=True) so it can never create a
-    per-session / per-chat / per-task output sub-folder: every deliverable stays
-    directly in the single configured Output folder."""
-    parts = Path(rel).parts
-    if parts and parts[0] == ".scratch":
-        return rel  # temporary sandbox is allowed (and cleaned up afterwards)
-    return Path(rel).name or rel
-
-
-@dataclass
-class ToolContext:
-    workdir: Path
-    flatten_writes: bool = False  # Cowork: force every write into the workdir root
-    sandbox: bool = False  # Code tab: isolate run_command/install_package into <workdir>/.venv
-    # Sandbox Security Layer — Settings' "Resource Limits" (cpu_percent/memory_mb/
-    # disk_mb), applied to every run_command/install_package this context runs.
-    # None (default) = no limits, matching pre-existing behavior.
-    resource_limits: Optional[Dict[str, float]] = None
-    # Sandbox Security Layer — Settings' "Block network for agent commands"
-    # (policy-level, see deps.py::network_blocked_env). False (default) =
-    # unrestricted, matching pre-existing behavior.
-    block_network: bool = False
-    # Whether the fetch_url tool may read URLs — SEPARATE from block_network
-    # (reading a web page/share link for info is safe; running networked shell
-    # commands is the risk). Defaults True; set from agent_security.allow_url_fetch.
-    allow_url_fetch: bool = True
-    # Jira read connector config (base_url/email/api_token) — None disables the
-    # jira_* tools' ability to connect. Populated from config.data["jira"].
-    jira: Optional[Dict[str, Any]] = None
-
-    def resolve(self, rel: str) -> Path:
-        """Resolve ``rel`` inside the workdir, rejecting escapes."""
-        if rel in ("", "."):
-            return self.workdir
-        candidate = (self.workdir / rel).expanduser()
-        try:
-            resolved = candidate.resolve()
-        except OSError as exc:
-            raise ToolError(f"Invalid path: {rel} ({exc})")
-        root = self.workdir.resolve()
-        if resolved != root and root not in resolved.parents:
-            raise ToolError(
-                f"Refused: '{rel}' is outside the working folder ({root})."
-            )
-        return resolved
-
-
 # --------------------------------------------------------------------------
 # Tool specs advertised to the model
 # --------------------------------------------------------------------------
@@ -192,6 +142,23 @@ TOOL_SPECS: List[ToolSpec] = [
 # Actions gated by the permission gate in confirm mode (auto-approved in Auto-run).
 WRITE_TOOLS = {"write_file", "edit_file", "run_command", "install_package"}
 
+# name -> handler(ctx, args[, cancel, on_output]) — built once from the split
+# infrastructure modules. Replaces the if/elif chain execute_tool used to be.
+_HANDLERS: Dict[str, Callable[..., Dict[str, Any]]] = {
+    "read_file": file_tools.read_file,
+    "list_dir": file_tools.list_dir,
+    "write_file": file_tools.write_file,
+    "edit_file": file_tools.edit_file,
+    "run_command": command_tools.run_command,
+    "install_package": command_tools.install_package,
+    "fetch_url": fetch_tools.fetch_url,
+    "jira_search": fetch_tools.jira_search,
+    "jira_get_issue": fetch_tools.jira_get_issue,
+}
+# Handlers that accept the long-running (cancel, on_output) signature — every
+# other handler takes just (ctx, args).
+_CANCELLABLE = {"run_command", "install_package"}
+
 
 def enabled_tool_specs(security_config=None) -> List[ToolSpec]:
     """The built-in TOOL_SPECS minus any the admin turned OFF in Monitoring →
@@ -301,27 +268,14 @@ def execute_tool(ctx: ToolContext, name: str, args: Dict[str, Any],
     labels WHICH agent role made it."""
     from . import audit_log
 
+    handler = _HANDLERS.get(name)
     try:
-        if name == "read_file":
-            result = _read_file(ctx, args)
-        elif name == "list_dir":
-            result = _list_dir(ctx, args)
-        elif name == "write_file":
-            result = _write_file(ctx, args)
-        elif name == "edit_file":
-            result = _edit_file(ctx, args)
-        elif name == "run_command":
-            result = _run_command(ctx, args, cancel, on_output)
-        elif name == "install_package":
-            result = _install_package(ctx, args, cancel, on_output)
-        elif name == "fetch_url":
-            result = _fetch_url(ctx, args)
-        elif name == "jira_search":
-            result = _jira_search(ctx, args)
-        elif name == "jira_get_issue":
-            result = _jira_get_issue(ctx, args)
-        else:
+        if handler is None:
             result = {"ok": False, "output": f"Tool not found: {name}"}
+        elif name in _CANCELLABLE:
+            result = handler(ctx, args, cancel, on_output)
+        else:
+            result = handler(ctx, args)
     except ToolError as exc:
         result = {"ok": False, "output": str(exc)}
     except Exception as exc:  # defensive: a tool must never crash the agent
@@ -331,234 +285,6 @@ def execute_tool(ctx: ToolContext, name: str, args: Dict[str, Any],
     return result
 
 
-def _fetch_url(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    """Fetch a URL's text content (web page / online document / SharePoint-
-    OneDrive share link) via link_fetch — the same parser task-link attachments
-    use. Honors the Sandbox Security Layer's "Block network" policy."""
-    url = str(args.get("url", "")).strip()
-    if not url:
-        return {"ok": False, "output": "fetch_url: 'url' is required."}
-    if not url.lower().startswith(("http://", "https://")):
-        return {"ok": False, "output": f"fetch_url: not an http(s) URL: {url}"}
-    if not ctx.allow_url_fetch:
-        return {"ok": False,
-                "output": ("fetch_url: URL fetching is turned off in Settings → Security "
-                           "(\"Allow the agent to fetch URLs\").")}
-    # A pasted Jira issue link on the CONNECTED Jira host is read via the
-    # authenticated API (so private issues resolve, not a login page). Public
-    # links / any other URL fall through to the normal fetcher below.
-    from . import jira_tool
-    if jira_tool.is_jira_issue_url(ctx.jira, url):
-        return {"ok": True, "output": jira_tool.get_issue_by_url(ctx.jira, url)}
-    from .link_fetch import fetch_link_preview
-
-    return {"ok": True, "output": fetch_link_preview(url)}
-
-
-def _jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    from . import jira_tool
-
-    out = jira_tool.search(ctx.jira, str(args.get("jql", "")),
-                           int(args.get("max_results", 25) or 25))
-    return {"ok": not out.lower().startswith(("jira is not configured", "jira search failed")),
-            "output": out}
-
-
-def _jira_get_issue(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    from . import jira_tool
-
-    out = jira_tool.get_issue(ctx.jira, str(args.get("key", "")))
-    return {"ok": not out.lower().startswith(("jira is not configured", "could not fetch")),
-            "output": out}
-
-
-def _read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    target = ctx.resolve(str(args.get("path", "")))
-    if not target.exists():
-        return {"ok": False, "output": f"File not found: {args.get('path')}"}
-    data = target.read_bytes()[:MAX_READ_BYTES]
-    text = data.decode("utf-8", errors="replace")
-    return {"ok": True, "output": text}
-
-
-def _list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    rel = str(args.get("path", ".") or ".")
-    target = ctx.resolve(rel)
-    # A missing/not-yet-created path is NOT a tool failure — report it as an
-    # ordinary result so the agent can create it or pick another path and keep
-    # going. Returning ok=False here surfaced a false "tool failed: list_dir" in
-    # Co4E flows and could stall a step on a recoverable situation.
-    if not target.exists():
-        return {"ok": True, "output": f"(path '{rel}' does not exist yet — create it or use another path)"}
-    if target.is_file():
-        return {"ok": True, "output": f"('{rel}' is a file, not a directory)"}
-    entries = []
-    for child in sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower())):
-        marker = "/" if child.is_dir() else ""
-        entries.append(f"{child.name}{marker}")
-    return {"ok": True, "output": "\n".join(entries) or "(empty folder)"}
-
-
-def _check_python_syntax(target: Path, content: str) -> str:
-    """Return a short warning if ``content`` is invalid Python, else ''.
-
-    Catches syntax errors the instant a .py file is written/edited — before the
-    agent wastes a whole run_command round-trip just to get the same error back
-    from a traceback."""
-    if target.suffix.lower() not in (".py", ".pyw"):
-        return ""
-    try:
-        ast.parse(content, filename=str(target))
-        return ""
-    except SyntaxError as exc:
-        return f"\n⚠ Syntax error at line {exc.lineno}: {exc.msg} — fix this before running the file."
-
-
-def _write_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    rel = str(args.get("path", ""))
-    if ctx.flatten_writes:
-        rel = _flatten_rel(rel)
-    target = ctx.resolve(rel)
-    content = str(args.get("content", ""))
-    target.parent.mkdir(parents=True, exist_ok=True)
-    # A .xlsx is a binary package — build a REAL workbook from the content
-    # (CSV/TSV/Markdown-table/JSON) rather than writing raw text (which corrupts it).
-    if target.suffix.lower() in (".xlsx", ".xlsm"):
-        from . import xlsx_write
-        if xlsx_write.build_xlsx_from_text(target, content):
-            return {"ok": True, "path": str(target),
-                    "output": f"Wrote spreadsheet {rel} ({target.name})."}
-        return {"ok": False, "output": "Could not build the .xlsx (openpyxl unavailable) — "
-                "write a .csv instead, or use a generator script."}
-    target.write_text(content, encoding="utf-8")
-    warning = _check_python_syntax(target, content)
-    return {"ok": True, "path": str(target),
-            "output": f"Wrote {len(content)} chars to {rel}.{warning}"}
-
-
-def _edit_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
-    """Replace an exact snippet inside an existing file (precise patch edit)."""
-    rel = str(args.get("path", ""))
-    if ctx.flatten_writes:
-        rel = _flatten_rel(rel)
-    target = ctx.resolve(rel)
-    if not target.exists():
-        return {"ok": False,
-                "output": f"File not found: {rel} — use write_file to create it."}
-    old = str(args.get("old_string", ""))
-    new = str(args.get("new_string", ""))
-    replace_all = bool(args.get("replace_all", False))
-    if not old:
-        return {"ok": False, "output": "old_string is empty — provide the exact text to replace."}
-    try:
-        text = target.read_text(encoding="utf-8", errors="replace")
-    except OSError as exc:
-        return {"ok": False, "output": f"Could not read file: {exc}"}
-    count = text.count(old)
-    if count == 0:
-        return {"ok": False, "output": ("old_string not found. Read the file and copy the exact "
-                                        "text to replace, including indentation/whitespace.")}
-    if count > 1 and not replace_all:
-        return {"ok": False, "output": (f"old_string appears {count} times — add surrounding "
-                                        "context to make it unique, or set replace_all=true.")}
-    updated = text.replace(old, new) if replace_all else text.replace(old, new, 1)
-    target.write_text(updated, encoding="utf-8")
-    n = count if replace_all else 1
-    warning = _check_python_syntax(target, updated)
-    return {"ok": True,
-            "output": f"Edited {args.get('path')} ({n} replacement{'' if n == 1 else 's'}).{warning}"}
-
-
-def _sandbox_python(ctx: ToolContext, cancel: Optional[CancelFn] = None,
-                     on_output: Optional[Callable[[str], None]] = None) -> Optional[str]:
-    """Lazily create/reuse this ctx's project sandbox venv (Code tab only —
-    ``ctx.sandbox``); returns its python path, or None to use the app's own."""
-    if not ctx.sandbox:
-        return None
-    from .deps import ensure_project_venv
-
-    py = ensure_project_venv(ctx.workdir, cancel=cancel, on_output=on_output)
-    return str(py) if py else None
-
-
-def _install_package(ctx: ToolContext, args: Dict[str, Any], cancel: Optional[CancelFn] = None,
-                      on_output: Optional[Callable[[str], None]] = None) -> Dict[str, Any]:
-    from .deps import pip_install
-
-    package = str(args.get("package", "")).strip()
-    if not package:
-        return {"ok": False, "output": "No package specified."}
-    python = _sandbox_python(ctx, cancel, on_output)
-    ok, detail = pip_install(package, cancel=cancel, on_output=on_output, python=python)
-    head = f"Installed {package}." if ok else f"Could not install {package}."
-    return {"ok": ok, "output": f"{head}\n{detail}"}
-
-
-_SNAPSHOT_SKIP = {".git", "__pycache__", "node_modules", ".scratch", ".venv",
-                  ".idea", ".mypy_cache", ".pytest_cache"}
-
-
-def _snapshot(workdir: Path) -> Dict[str, Any]:
-    """Map of file path -> (mtime, size) under the workdir (noise dirs skipped)."""
-    snap: Dict[str, Any] = {}
-    try:
-        for dirpath, dirnames, filenames in os.walk(str(workdir)):
-            dirnames[:] = [d for d in dirnames if d not in _SNAPSHOT_SKIP]
-            for fn in filenames:
-                full = os.path.join(dirpath, fn)
-                try:
-                    st = os.stat(full)
-                    snap[full] = (st.st_mtime_ns, st.st_size)
-                except OSError:
-                    pass
-            if len(snap) > 5000:
-                return snap
-    except OSError:
-        pass
-    return snap
-
-
-def _run_command(ctx: ToolContext, args: Dict[str, Any],
-                  cancel: Optional[CancelFn] = None,
-                  on_output: Optional[Callable[[str], None]] = None) -> Dict[str, Any]:
-    from .deps import network_blocked_env, run_cancellable, sandbox_env
-    from .sandbox_manager import SandboxManager, ExecutionConfig
-    from ..security.command_risk_classifier import classify_command
-
-    command = str(args.get("command", "")).strip()
-    if not command:
-        return {"ok": False, "output": "Empty command."}
-
-    # --- Security validation pipeline ---
-    risk = classify_command(command, is_cowork_mode=ctx.flatten_writes)
-    if risk.blocked:
-        denial = "Command blocked by security policy: " + "; ".join(risk.reasons)
-        return {"ok": False, "output": denial}
-
-    # Route through SandboxManager for risk-based isolation
-    mgr = SandboxManager(ExecutionConfig(
-        enabled=True,
-        block_network_by_default=ctx.block_network,
-        is_cowork_mode=ctx.flatten_writes,
-    ))
-    sandbox_result = mgr.run(
-        command=command,
-        workdir=str(ctx.workdir),
-        block_network=ctx.block_network,
-        timeout_sec=COMMAND_TIMEOUT,
-        cancel=cancel,
-    )
-    # Sandbox ALWAYS executes (never double-run). Return its result directly.
-    if sandbox_result.get("sandbox") == "blocked":
-        return {"ok": False, "output": sandbox_result.get("stderr", "Command blocked")}
-    out = sandbox_result.get("stdout", "").strip() or "(no output)"
-    err = sandbox_result.get("stderr", "")
-    rc = sandbox_result.get("returncode", -1)
-    if err:
-        out = f"{out}\n{err}" if out else err
-    return {"ok": sandbox_result.get("ok", False), "output": f"[exit {rc}]\n{out}"}
-
-
 def _short_json(obj: Any, limit: int = 500) -> str:
     import json
     text = json.dumps(obj, ensure_ascii=False, indent=2)

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

@@ -0,0 +1,156 @@
+# ADR-001: Kiến Trúc 4 Tầng (Layered / Clean Architecture)
+
+* **Status**: Accepted
+* **Date**: 2026-08-21
+* **EPIC / Task**: R01-T01
+* **Owner**: 🔵 Team Duy (Tech Lead)
+* **Áp dụng cho**: toàn bộ mã nguồn mới của `cowork_local` (3 team)
+
+---
+
+## 1. Context (Bối cảnh)
+
+`cowork_local` hiện là một ứng dụng PySide6 desktop local-first ~55.000 dòng Python,
+được phát triển nhanh theo hướng feature-first. Hệ quả đo được tại thời điểm viết ADR:
+
+| Vấn đề | Bằng chứng cụ thể trong repo |
+| :--- | :--- |
+| **God widget** | `ui/co4e_tab.py` 2.089 dòng, `ui/chat_panel.py` 1.795 dòng, `ui/folder_tab.py` 1.590 dòng |
+| **Business logic nằm trong widget** | Vòng đời turn chat, quyết định routing, ghép prompt đều nằm trong `ui/chat_panel.py` |
+| **Logic trùng lặp 3 nơi** | `ui/chat_panel.py::_apply_routing`, `ui/co4e_tab.py::_apply_co4e_routing`, `ui/folder_tab.py::_ai_apply_routing` là ba bản sao gần như y hệt của cùng một thuật toán |
+| **Không test được nếu không có Qt** | Muốn test một quyết định routing phải dựng widget → không chạy được headless, không chạy được nhanh |
+| **Side-effect ẩn trong tầng hạ tầng** | Provider tự gọi `core.usage_tracker.record()` ngay trong vòng lặp stream (`providers/openai_compat.py::_record_usage`) |
+
+Ba team (Duy / Nam / Hoa) sẽ sửa song song trên cùng codebase trong 10 ngày. Nếu
+không có một ranh giới phụ thuộc được **kiểm chứng tự động**, các thay đổi song song
+sẽ hội tụ về đúng cấu trúc rối như cũ.
+
+## 2. Decision (Quyết định)
+
+Mã nguồn mới được tổ chức thành **4 tầng**, với **chiều phụ thuộc một chiều** như sau:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  presentation/            PySide6 widgets, Qt signals/slots  │
+│  (chat, co4e, workspace…) Chỉ dựng UI và phát/nhận signal    │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ gọi xuống (được phép)
+┌───────────────────────────▼─────────────────────────────────┐
+│  application/             Pure Python orchestration          │
+│  (conversations,          Điều phối use-case, không biết Qt  │
+│   model_routing…)         và không biết HTTP/đĩa cụ thể      │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ gọi xuống (được phép)
+┌───────────────────────────▼─────────────────────────────────┐
+│  domain/                  Pure Python entities & events      │
+│  (agents, models…)        Frozen dataclass, enum, quy tắc    │
+│                           nghiệp vụ thuần. KHÔNG import gì   │
+│                           từ 3 tầng còn lại.                 │
+└───────────────────────────▲─────────────────────────────────┘
+                            │ implement interface của domain
+┌───────────────────────────┴─────────────────────────────────┐
+│  infrastructure/          Adapters: network, keyring, đĩa,   │
+│  (providers, telemetry…)  process, Qt-free I/O               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.1 Quy tắc bất biến (Invariants)
+
+| # | Quy tắc | Được kiểm bởi |
+| :--- | :--- | :--- |
+| **I1** | `domain/` và `application/` là **100% pure Python** — cấm import `PySide6`, `PyQt5`, `PyQt6`, `shiboken6` | `scripts/check_imports.py` (R01-T03) |
+| **I2** | `domain/` **không import** `application/`, `infrastructure/`, `presentation/`, `ui/` | `scripts/check_imports.py` |
+| **I3** | `application/` **không import** `presentation/` hay `ui/` | `scripts/check_imports.py` |
+| **I4** | Không file production nào vượt **400 dòng** | `scripts/check_loc.py` (R10-T02) |
+| **I5** | `presentation/` **không** gọi thẳng provider/HTTP/đĩa — phải đi qua một application service | Code review + I1–I3 |
+| **I6** | Mọi input của một use-case được đóng gói thành **snapshot bất biến** (`frozen dataclass`) trước khi rời UI thread | Code review + unit test |
+
+### 2.2 Chiều phụ thuộc được phép
+
+| Từ tầng | Được import | Bị cấm |
+| :--- | :--- | :--- |
+| `presentation/` | `application/`, `domain/`, PySide6 | — (nên tránh gọi thẳng `infrastructure/`) |
+| `application/` | `domain/`, interface do `domain/` định nghĩa | `presentation/`, `ui/`, PySide6 |
+| `domain/` | chỉ stdlib | tất cả các tầng khác, PySide6 |
+| `infrastructure/` | `domain/`, thư viện ngoài (requests, keyring…) | `presentation/`, `ui/`, PySide6 |
+
+### 2.3 Cách tầng dưới "nói chuyện ngược" lên UI
+
+`application/` **không được** giữ tham chiếu tới widget. Việc trao đổi ngược chiều
+đi qua **callback thuần Python nhận một `AgentEvent` có kiểu**
+(`domain/agents/agent_event.py`, R04-T02):
+
+```python
+# application layer — pure Python, không biết Qt tồn tại
+service.run_turn(request, on_event=my_callback)
+
+# presentation layer — chuyển event sang Qt signal ở ranh giới duy nhất này
+def my_callback(event: AgentEvent) -> None:
+    self.agent_event.emit(event)   # Qt signal → cập nhật UI trên main thread
+```
+
+Đây là **seam** duy nhất giữa hai thế giới: dưới seam là Python thuần test được
+offline, trên seam là Qt. Mọi cập nhật UI phải xảy ra qua Qt signal/slot, không
+bao giờ gọi trực tiếp từ worker thread.
+
+## 3. Vị trí sở hữu theo team
+
+| Tầng / thư mục | Team | EPIC |
+| :--- | :--- | :--- |
+| `presentation/chat/`, `application/conversations/`, `application/model_routing/`, `domain/agents/`, `domain/models/`, `infrastructure/providers/`, `infrastructure/telemetry/`, `tests/`, `scripts/` | 🔵 Duy | R01, R03, R04, R08, R10 |
+| `presentation/co4e/`, `monitoring/`, `settings/`, `shell/`, `application/workflows/`, `infrastructure/config/`, `secrets/`, `sandbox/` | 🟣 Nam | R02, R08, R09 |
+| `presentation/workspace/`, `folder/`, `scheduling/`, `application/workspaces/`, `scheduling/`, `domain/tools/`, `domain/tasks/`, `infrastructure/filesystem/`, `mcp/`, `persistence/` | 🟢 Hoa | R05, R06, R07, R08 |
+
+## 4. Chiến lược di trú (Strangler Fig, không big-bang)
+
+Code cũ trong `core/`, `ui/`, `providers/` **không bị xoá ngay**. Ta bọc dần:
+
+1. **Tạo seam mới** ở tầng đúng (ví dụ `RoutingApplicationService`).
+2. **Chuyển call site** cũ sang gọi seam mới (`ui/*.py` chỉ còn vài dòng adapter).
+3. **Giữ module cũ làm implementation detail** phía sau seam (ví dụ
+   `application/model_routing/` vẫn gọi xuống `core/routing/` để dùng lại
+   scorer/selector đã có test).
+4. Chỉ khi mọi call site đã đi qua seam mới → cân nhắc gỡ code cũ.
+
+Nhờ vậy `pytest` luôn xanh giữa các bước, và một team có thể merge mà không chờ
+team khác refactor xong.
+
+## 5. Consequences (Hệ quả)
+
+### Tích cực
+
+* Test một quyết định routing / một vòng đời turn chat **không cần Qt, không cần mạng** → suite unit chạy < 1 giây.
+* Ba bản sao logic routing hội tụ về một nơi duy nhất → sửa một lần, cả 3 màn hình cùng đúng.
+* Người mới có thể thêm một provider mà chỉ chạm `infrastructure/providers/` + `domain/models/`.
+* Vi phạm kiến trúc bị chặn ở CI thay vì phát hiện lúc review.
+
+### Tiêu cực / chi phí phải chấp nhận
+
+* Nhiều file nhỏ hơn thay vì vài file lớn → tăng số lần "nhảy file" khi đọc code.
+* Tồn tại **hai đường** trong giai đoạn di trú (code cũ + seam mới) cho tới khi call site cuối cùng chuyển xong.
+* Phải viết DTO/snapshot rõ ràng thay vì truyền thẳng `self` của widget — tốn thêm code, đổi lại được thread-safety.
+
+## 6. Alternatives considered (Phương án đã cân nhắc)
+
+| Phương án | Lý do loại |
+| :--- | :--- |
+| **Giữ nguyên, chỉ tách file cho ngắn** | Giải quyết được I4 (LOC) nhưng không giải quyết được nguyên nhân gốc: logic vẫn dính Qt nên vẫn không test được offline. |
+| **MVVM/MVP thuần Qt** | Vẫn buộc business logic phụ thuộc vòng đời Qt object; không chạy được trong scheduler headless và trong task nền. |
+| **Hexagonal đầy đủ (port/adapter cho mọi thứ)** | Đúng về lý thuyết nhưng quá tốn cho 10 ngày và cho một app desktop 1 process; 4 tầng là điểm cân bằng. |
+| **Big-bang rewrite** | Rủi ro hồi quy quá cao khi 3 team sửa song song và không có bộ test bảo vệ đầy đủ. |
+
+## 7. Enforcement (Thực thi)
+
+```bash
+python scripts/check_imports.py      # I1, I2, I3 — quét AST
+python scripts/check_loc.py          # I4 — giới hạn 400 dòng
+python scripts/run_quality_gate.py   # chạy toàn bộ CASAN Gate + pytest
+```
+
+CASAN Verification Gate phải PASS trước khi merge bất kỳ PR nào vào `main`.
+
+## 8. Tài liệu liên quan
+
+* `docs/refactor/Feature_Architecture_Proposal.md` — thiết kế tổng thể 10 EPIC
+* `docs/refactor/Refactoring_Checklist.md` — bảng tiến độ theo task
+* `docs/architecture/dormant-code.md` — danh mục code không còn hoạt động (R01-T05)

docs/architecture/dormant-code.md

@@ -0,0 +1,85 @@
+# Dormant / Dead Code Inventory (R01-T05)
+
+* **Task**: R01-T05 — Phân loại và cô lập mã nguồn cũ
+* **Owner**: 🔵 Team Duy
+* **Ngày quét**: 2026-08-21
+* **Phạm vi quét**: toàn bộ `*.py` production (loại trừ `tests/`, `assets/`, `docs/`, `.git/`)
+
+---
+
+## 1. Mục đích
+
+Trước khi 3 team refactor song song, cần biết **file nào thật sự đang chạy**. Refactor
+một module đã chết là lãng phí; xoá nhầm một module chỉ được gọi động là gây sự cố
+runtime. Tài liệu này phân loại từng ứng viên, kèm **bằng chứng** và **hành động đề xuất**.
+
+## 2. Phương pháp
+
+Quét AST toàn repo, dựng đồ thị import, tìm module **không có module nào khác import**.
+Kết quả thô: **43 module**. Sau đó xác minh thủ công từng ứng viên, vì phân tích tĩnh
+không thấy 3 kiểu tham chiếu:
+
+| Kiểu tham chiếu ẩn | Ví dụ thật trong repo |
+| :--- | :--- |
+| Chạy như subprocess | `state.py:285` gọi `python -m cowork_local.mcp_servers.ms365_server` |
+| Entry point của gói | `__main__.py` (chạy bằng `python -m cowork_local`) |
+| Script chạy tay | `tools/check_*.py`, `scripts/*.py` |
+
+> ⚠️ **Kết luận quan trọng**: 43 module "không ai import" **KHÔNG** đồng nghĩa 43 module chết.
+> Sau xác minh, chỉ còn **6 hạng mục (~1.887 dòng)** là dormant thật.
+
+## 3. Phân loại kết quả
+
+### 🟥 A. DORMANT THẬT — không có đường nào chạy tới (ứng viên xoá)
+
+| Module | LOC | Bằng chứng | Rủi ro khi xoá | Hành động |
+| :--- | ---: | :--- | :--- | :--- |
+| `ui/accounts_tab.py` | 700 | Chỉ xuất hiện trong comment của `i18n.py:92`; không widget nào khởi tạo `AccountsTab` | Thấp — panel Monitoring → Accounts hiện không có đường vào | Cô lập, chờ xác nhận PO rồi xoá |
+| `ui/flow_dialog.py` | 596 | Chỉ được nhắc trong docstring `ui/agent_manager_tab.py:4` và comment `i18n.py:2124` | Trung bình — Flow Manager có thể là tính năng tạm ẩn | **Hỏi PO trước**, chưa xoá |
+| `security/` (cả package) | 296 | `prompt_validator`, `action_validator`, `attachment_validator`, `audit_logger`, `command_risk_classifier` — không file nào ngoài package tự import. Chức năng **trùng** `core/agent_security.py` + `core/security_rules.py` (đang chạy thật) | Trung bình — dễ nhầm đây là lớp bảo mật đang hoạt động | ⚠️ Ưu tiên cao: xoá hoặc hợp nhất trong **R09 (Team Nam)** |
+| `core/codebase_memory_ui.py` | 123 | Không nơi nào import; `core/codebase_memory.py` (bản không-UI) mới là bản đang dùng | Thấp | Xoá |
+| `core/graph_server.py` | 115 | Docstring nói phục vụ build không có QtWebEngine, nhưng **không có call site nào**; `ui/structure_graph_view.py` không gọi | Trung bình — có thể là fallback cho bản .exe chưa nối dây | Xác minh với bản đóng gói PyInstaller trước khi xoá |
+| `ui/mcp_servers_dialog.py` | 57 | Không import; MCP settings hiện nằm trong `ui/settings_dialog.py` | Thấp | Xoá |
+
+**Tổng: ~1.887 dòng (≈ 3,4% codebase).**
+
+### 🟨 B. KHÔNG CHẾT — chạy qua đường ẩn (giữ nguyên)
+
+| Module | Vì sao phân tích tĩnh báo nhầm |
+| :--- | :--- |
+| `__main__.py` | Entry point `python -m cowork_local` |
+| `mcp_servers/ms365_server.py` | Chạy như tiến trình con — `state.py:285` |
+| `core/routing/__init__.py` | Được import qua đường dẫn con (`from .routing.service import RoutingService`), heuristic theo tên lá không thấy |
+| `tools/check_*.py` (34 file, 6.608 dòng) | Bộ smoke-test UI chạy tay: `python tools/check_nav.py`. Là **dev tooling**, không phải code chết |
+| `scripts/bootstrap_gitea_repo.py`, `scripts/check_imports.py` | Script CLI chạy tay / chạy trong CI |
+
+### 🟩 C. CODE SỐNG NHƯNG "ĐÓNG BĂNG" — đụng vào phải cẩn thận
+
+| Module | LOC | Ghi chú cho người refactor |
+| :--- | ---: | :--- |
+| `core/chat_agent.py::run_cowork` | 580 | Đang có **characterization test** (`tests/characterization/test_run_cowork.py`, R01-T04). Mọi thay đổi hành vi phải làm cùng lúc với cập nhật snapshot |
+| `providers/base.py` | 401 | Là contract chung của mọi provider; đổi chữ ký = vỡ cả 3 team. Đã có contract test (R03-T01) |
+| `core/routing/*` | 2.263 | Đã có 79 test đang xanh. R03 **bọc** chứ không viết lại: `application/model_routing/` gọi xuống đây |
+
+## 4. Quy tắc xử lý (bắt buộc)
+
+1. **Không xoá trong cùng PR với refactor.** Xoá code chết là một commit riêng, để `git revert` được độc lập khi có sự cố.
+2. **Cô lập trước, xoá sau.** Đánh dấu module bằng docstring cảnh báo, chạy 1 vòng release; không ai báo lỗi mới xoá.
+3. **Hạng mục 🟥 A cần một người xác nhận** (PO hoặc chủ tính năng) trước khi xoá — trừ khi rõ ràng là bản trùng lặp (`codebase_memory_ui`, `mcp_servers_dialog`).
+4. **Không refactor code trong nhóm 🟥 A.** Nếu một file trong danh sách này >400 dòng, nó **không** tính vào CASAN Check 2 — vì đường đi đúng là xoá, không phải tách nhỏ.
+
+## 5. Việc cần bàn giao
+
+| Hạng mục | Team nhận | EPIC |
+| :--- | :--- | :--- |
+| `security/` trùng lặp với `core/agent_security.py` | 🟣 Nam | R09 |
+| `ui/accounts_tab.py`, `ui/flow_dialog.py`, `ui/mcp_servers_dialog.py` | 🟣 Nam (sở hữu `presentation/shell/`, `settings/`) | R08 |
+| `core/graph_server.py`, `core/codebase_memory_ui.py` | 🟢 Hoa (sở hữu `presentation/graph/`) | R06 |
+
+## 6. Cách chạy lại lần quét này
+
+```bash
+python scripts/check_imports.py       # ranh giới kiến trúc (R01-T03)
+# Bản quét đồ thị import dùng cho tài liệu này sẽ được đóng gói thành
+# scripts/find_dormant.py trong R10-T02 (Testing & Governance tooling).
+```

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

@@ -1,58 +0,0 @@
-# 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/refactor/BaoCao_TeamDuy_R01_R03_R04.md

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

docs/refactor/BaoCao_TeamHoa_R05_R08.md

@@ -0,0 +1,238 @@
+# BÁO CÁO KẾT QUẢ — TEAM HOA: EPIC R05, R06, R07, R08 (phần Team Hoa)
+
+* **Dự án**: Cowork Local (Cowork-Local BamBOO)
+* **Team**: 🟢 Team Hoa — Workspace, Filesystem, Scheduling & Tool Registry
+* **Nhánh**: `feature/teamhoa/r05-r08` (tạo từ `origin/feature/deltateam/refactor-plan`, có sẵn nền R01/R03/R04 của Team Duy; đổi tên từ `feature/teamhoa/r05-r06` sau khi gộp thêm R07/R08)
+* **Thời gian thực hiện**: 21/08/2026 21:40 → 27/08/2026 20:52
+* **Ngày báo cáo**: 27/08/2026 (bản gộp, thay thế `BaoCao_TeamHoa_R05_R06.md` và `BaoCao_TeamHoa_R07_R08.md`)
+* **Tài liệu gốc**: `Feature_Architecture_Proposal.md`, `Refactoring_Checklist.md`, `plan.md`
+
+---
+
+## 1. Tóm tắt điều hành
+
+Hoàn tất **toàn bộ 19/19 task thuộc phạm vi Team Hoa** trên 4 EPIC: **R05** (Tool, MCP & Connector Policy), **R06** (Workspace, Filesystem & History Isolation), **R07** (Scheduling & Workflow Runtime), **R08** (UI/Application Separation — phần Team Hoa, T11→T14).
+
+| Chỉ số | Kết quả |
+| :--- | :--- |
+| Task hoàn thành | **19/19** (R05: 5, R06: 5, R07: 5, R08: 4 — không tính R07-T06/R08-T01→T10 thuộc Team Duy/Team Nam) |
+| File thay đổi | 92+ (phần lớn file mới) |
+| Test cuối cùng | **377 pass / 4 fail** (xem tiến trình chi tiết ở mục 4) |
+| CASAN Check 3 (`scripts/check_imports.py`) | **PASS** — 0 Qt import trong `domain/`, `application/` |
+| File production > 400 dòng (file mới) | **0** — lớn nhất `presentation/graph/graph_renderer.py` 391 dòng |
+| `python -c "import cowork_local.app"` | **OK** sau mọi task |
+
+**3 lỗi thật phát hiện và sửa**, **1 quyết định kiến trúc đổi so với plan gốc (xác nhận bằng thực nghiệm)** — chi tiết mục 5.
+
+---
+
+## 2. Kết quả theo từng EPIC
+
+### 🔹 EPIC R05 — Tool, MCP & Connector Policy (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R05-T01/T02 | `domain/tools/{tool_descriptor,tool_registry}.py`, `infrastructure/filesystem/{file_tools,command_tools,fetch_tools}.py` | Tách if/elif dispatcher của `core/tools.py`; `core/tools.py` còn lại là shim strangler-fig (re-export `ToolContext`/`ToolError`, dispatch qua dict), 566 ➔ 291 dòng. |
+| R05-T03 | `application/conversations/tool_policy_gateway.py::ToolPolicyGateway` | Thay 2 chỗ check hardcode riêng biệt (`chat_agent.py`, `code_agent.py`) bằng 1 lookup capability chung. |
+| R05-T04 | Sửa `core/chat_agent.py`, `core/mcp_client.py` | **Thay đổi hành vi có chủ đích** — xem mục 5, Lỗi 1. |
+| R05-T05 | `infrastructure/mcp/mcp_source_manager.py::McpToolSourceManager` | Tách lifecycle connection MCP khỏi `state.py::AppContext`. |
+
+### 🔹 EPIC R06 — Workspace, Filesystem & History Isolation (5/5)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R06-T01 | `domain/workspaces/workspace_session.py::WorkspaceSession` | Snapshot bất biến (project_id/workspace_root/sandbox_dir/allowed_paths) + `is_allowed(path)`. |
+| R06-T02 | `infrastructure/persistence/json/{atomic_write,workspace_repository_impl,conversation_repository_impl}.py` | **Sửa bug thật** — xem mục 5, Lỗi 2. |
+| R06-T03 | `infrastructure/filesystem/execution_workspace.py::ExecutionWorkspace` | Đặt tên cho quy ước `.scratch` đã có sẵn. |
+| R06-T04 | Sửa `ui/chat_panel.py` | **Sửa race condition thật** — xem mục 5, Lỗi 3. |
+| R06-T05 | `application/workspaces/file_workspace_service.py::FileWorkspaceService` | Seam cho File Explorer/AI Editor gọi `execute_tool` giống agent — **chưa có call site thật lúc R06 xong; đã nối dây ở R08-T12** (xem mục 5). |
+
+### 🔹 EPIC R07 — Scheduling & Workflow Runtime (5/5, phạm vi Team Hoa)
+
+| Task | Sản phẩm | Ghi chú |
+| :--- | :--- | :--- |
+| R07-T01 | `infrastructure/persistence/json/task_repository_impl.py::TaskRepository` | Bọc CRUD của `core/tasks.py`. **Sửa bug thật**: `save_task` trước đây ghi không atomic — cùng lớp bug đã sửa ở R06-T02. |
+| R07-T02 | `domain/tasks/schedule_calculator.py::ScheduleCalculator` | Tách "schedule math" (cron/interval/daily/weekly/monthly + holiday exclusion) thành pure Python, trước đây **0 test**, giờ có 14 test. |
+| R07-T03 | `infrastructure/qt/qt_scheduler_clock.py::QtSchedulerClock` | Bọc `QTimer` sau 1 interface nhỏ, inject qua `clock=`. **Đổi vị trí so với plan gốc** — xem mục 5. |
+| R07-T04 | `application/scheduling/task_application_service.py::TaskApplicationService` | Gom CRUD + luật kéo-thả Kanban (`move_to_status`). |
+| R07-T05 | `application/scheduling/ai_task_planner_service.py::AiTaskPlannerService` | Seam cho `plan_tasks`/`import_tasks`. |
+
+*(R07-T06 `Co4EWorkflowService` là việc Team Nam — không đụng.)*
+
+### 🔹 EPIC R08 — UI/Application Separation (4/4, phạm vi Team Hoa: T11→T14)
+
+`presentation/` **chưa tồn tại** trước task này — Team Hoa tạo cấu trúc lần đầu.
+
+| Task | God file gốc | Tách thành |
+| :--- | :--- | :--- |
+| R08-T11 | `ui/schedule_task_tab.py` (795 dòng) | `presentation/scheduling/{kanban_board_widget,calendar_view_widget,ai_task_creator_dialog,ai_task_import_dialog,run_history_dialog}.py` + shell |
+| R08-T12 | `ui/folder_tab.py` (1587 dòng — lớn nhất) | `presentation/folder/{workspace_file_tree,document_preview_manager,code_editor,office_document_renderer,ai_file_editor_dialog,ai_edit_model_resolver,ai_edit_pipeline}.py` + shell |
+| R08-T13 | `ui/dashboard_tab.py` (437 dòng) | `presentation/dashboard/{token_usage_card_widget,usage_chart_widget,habits_widget}.py` + shell, `application/monitoring/dashboard_query_service.py` |
+| R08-T14 | `ui/structure_graph_view.py` (1035 dòng) | `presentation/graph/{graph_scene_items,graph_renderer,graph_messages_view,graph_qa_widget}.py` + shell |
+
+*(R08-T01→T10 thuộc Team Duy/Team Nam — không đụng.)* Mỗi god-file cũ chỉ có 1-2 nơi khởi tạo thật (`app.py`, `ui/workspace_tab.py`) nên đã **sửa thẳng import site** và **xoá hẳn file `ui/*.py` cũ** thay vì giữ shim (khác `core/tools.py` ở R05, có hàng chục call site).
+
+---
+
+## 3. Kiến trúc sau refactor
+
+```text
+presentation/            (MỚI ở R08 — Team Hoa tạo cấu trúc lần đầu)
+      scheduling/  {kanban_board_widget, calendar_view_widget,
+                    ai_task_creator_dialog, ai_task_import_dialog,
+                    run_history_dialog, schedule_task_tab}.py
+      folder/      {workspace_file_tree, document_preview_manager, code_editor,
+                    office_document_renderer, ai_file_editor_dialog,
+                    ai_edit_model_resolver, ai_edit_pipeline, folder_tab}.py
+      dashboard/   {token_usage_card_widget, usage_chart_widget,
+                    habits_widget, dashboard_tab}.py
+      graph/       {graph_scene_items, graph_renderer, graph_messages_view,
+                    graph_qa_widget, structure_graph_view}.py
+      shared/      web_engine_support.py (HAS_WEB_ENGINE dùng chung)
+      │
+      ▼
+application/   conversations/tool_policy_gateway.py        ← ALLOW/CONFIRM cho mọi tool call (R05)
+               workspaces/{file_workspace_service, file_preview_helpers,
+                           ai_edit_output, graph_index_service}.py         (R06, R08)
+               scheduling/{task_application_service, ai_task_planner_service}.py   (R07)
+               monitoring/dashboard_query_service.py                       (R08)
+      │        (100% pure Python — check_imports.py chặn import Qt)
+      ▼
+domain/        tools/{tool_descriptor,tool_registry}.py     ← capability + catalogue (R05)
+               workspaces/workspace_session.py              ← snapshot workspace bất biến (R06)
+               tasks/schedule_calculator.py                 ← due-time/cron math thuần Python (R07)
+      ▲
+infrastructure/ filesystem/{file_tools,command_tools,fetch_tools,tool_context,execution_workspace}.py  (R05/R06)
+                mcp/mcp_source_manager.py                   ← lifecycle connection MCP (R05)
+                persistence/json/{atomic_write,workspace_repository_impl,
+                                   conversation_repository_impl,task_repository_impl}.py  (R06/R07)
+                qt/qt_scheduler_clock.py                    ← QTimer đằng sau 1 interface nhỏ (R07)
+```
+
+**Nguyên tắc di trú xuyên suốt cả 4 EPIC (ADR-001 mục 4, tiếp nối cách Team Duy làm ở R04)**: **không viết lại engine**. `core/tools.py::execute_tool`, `core/chat_agent.py::run_cowork`, `core/tasks.py`, `core/task_scheduler.py`, `core/task_executors.py` vẫn là engine bên dưới — tầng mới chỉ sở hữu phần từng nằm rải rác/hardcode trong widget hoặc dispatcher. `pytest` xanh liên tục giữa các bước, chạy full suite sau MỖI task.
+
+**Riêng ở R08**: khi 1 file bị tách vượt 400 dòng dù đã theo đúng mapping gốc, đã tách thêm file phụ theo kiểu **composition** (class phụ nhận `owner` là widget chính) thay vì service riêng — ví dụ `run_history_dialog.py`, `office_document_renderer.py`, `ai_edit_pipeline.py`, `ai_edit_model_resolver.py`, `graph_messages_view.py`. Đây là split kỹ thuật để đạt giới hạn LOC, không phải ranh giới tầng kiến trúc.
+
+---
+
+## 4. Bằng chứng kiểm thử
+
+### Tiến trình test qua từng EPIC
+
+| Mốc | Tổng pass | Ghi chú |
+| :--- | ---: | :--- |
+| Sau R05+R06 | 283 (/287, 4 fail) | +41 unit test + 2 integration test (Qt offscreen thật) |
+| Sau R07 | 328 | +45 test mới (task repo, schedule calculator, Qt clock, task/AI-planner services) |
+| Sau R08 | **377** | +49 test mới (4 widget split, mỗi cái có unit + integration Qt offscreen) |
+
+**4 fail cuối cùng — cùng 1 baseline có sẵn từ trước, xuyên suốt cả 4 EPIC, không phải do Team Hoa**:
+* `tests/test_config_security.py` × 2 (EPIC R02/Team Nam — `config.py` hardcode `sandbox_pw`)
+* `tests/unit/test_routing_wiring.py` × 2 (môi trường máy này có Ollama/llama3.1 thật, khác giả định "fresh install" của test)
+
+### Đối chiếu Definition of Done
+
+| # | Tiêu chí | Kết quả |
+| :--- | :--- | :--- |
+| 1 | Mọi file mới < 400 dòng | ✅ Lớn nhất: `presentation/graph/graph_renderer.py` 391 dòng |
+| 2 | 0 import Qt trong `domain/`, `application/` | ✅ `check_imports.py` PASS |
+| 3 | Comment tiếng Anh giải thích lý do ở mọi khối sửa/mới | ✅ |
+| 4 | Có unit/contract/integration test, verify bằng chạy thật | ✅ +90 test mới sau R05/R06 lên tới 377; mọi widget Qt test bằng offscreen thật, không double |
+| 5 | Không hồi quy | ✅ 377/381 pass — 4 fail cùng 1 baseline có sẵn, không đổi qua 4 EPIC |
+| 6 | Ghi Start/End vào Checklist | ✅ 19 task đã tick kèm mốc thời gian thật |
+| 7 | Cổng CASAN (`run_quality_gate.py`, R10-T02) | ⚠️ Chưa viết (thuộc R10, chưa tới lượt) — Check 3 đã PASS |
+
+---
+
+## 5. Lỗi thật phát hiện & quyết định kiến trúc
+
+### 🔴 Lỗi 1 (R05-T04) — Tool MCP/Connector chạy hoàn toàn không qua permission gate
+
+`core/chat_agent.py::run_cowork` có 2 nhánh dispatch tool call: built-in đi qua gate xác nhận khi Settings bật "confirm before running commands"; nhánh `extra_tools` (mọi tool từ MCP server hoặc Connector) gọi thẳng `extra_executor(name, args)` **không qua bước xác nhận nào**. Đây không phải khác biệt thiết kế — không có ghi chú, không có toggle riêng.
+
+*Sửa*: mọi `extra_tools` gắn `ToolCapability` mặc định bảo toàn (`WRITE|EXECUTE|NETWORK`), đi qua CÙNG `ToolPolicyGateway` với built-in tools. **Thay đổi hành vi người dùng sẽ thấy**: tool MCP/connector giờ hỏi xác nhận khi "confirm before running commands" bật. Test: `tests/unit/test_cowork_extra_tool_policy.py`.
+
+### 🟠 Lỗi 2 (R06-T02, R07-T01) — Ghi file không atomic ở 3 nơi
+
+`core/projects.py::save_project`, `core/history.py::save_conversation/rename_conversation/set_pinned` (R06), và `core/tasks.py::save_task` (R07) đều từng dùng `path.write_text(json.dumps(...))` trần — crash giữa lúc ghi để lại file JSON hỏng, và hàm `load_*` tương ứng coi file hỏng như "không tồn tại" → **mất project/hội thoại/task âm thầm, không báo lỗi**. Cả 4 điểm ghi giờ qua `infrastructure/persistence/json/atomic_write.py::write_json` (temp file + `os.replace`). Có test giả lập crash giữa lúc ghi xác nhận file cũ không bị hỏng, cho cả 2 đợt sửa.
+
+### 🟡 Lỗi 3 (R06-T04) — Turn chạy ngầm lưu nhầm lịch sử vào project khác
+
+`ui/chat_panel.py::_persist_session` gọi `save_conversation(self.ctx.config.history_dir(), ...)`, đọc `config._project_history_dir` — field dùng chung bị `ui/workspace_tab.py::_load_current` ghi đè mỗi lần đổi project. Một turn chạy ngầm ở project A hoàn tất SAU khi user đã chuyển sang project B thì bị lưu nhầm vào lịch sử của B.
+
+*Sửa*: thêm `"home_history_dir"` vào dict `ctx` mỗi turn, chụp giá trị tại lúc submit thay vì đọc sống lúc lưu. Test Qt offscreen thật: `tests/integration/test_history_dir_race.py`.
+
+### 🔵 Quyết định kiến trúc (R07-T03) — `platform/qt/` đè lên module chuẩn `platform` của Python
+
+Plan gốc đặt tên `platform/qt/qt_scheduler_clock.py`. Thực nghiệm trước khi viết:
+
+```bash
+cd <repo_root> && python -c "import cowork_local; import platform; print(platform.system())"
+```
+
+Sau khi tạo `platform/__init__.py`, lệnh trên báo lỗi `AttributeError: module 'platform' has no attribute 'system'` — bất cứ khi nào repo root nằm trực tiếp trên `sys.path` (không qua `__main__.py`'s parent-dir fixup), `import platform` phân giải nhầm vào package cục bộ. `core/windows_sandbox_vm.py`/`core/appcontainer_sandbox.py` đều `import platform`.
+
+*Sửa*: chuyển sang `infrastructure/qt/qt_scheduler_clock.py` (không tạo package `platform/` mới) — đúng layer, cùng cấp `infrastructure/{filesystem,mcp,persistence,providers,telemetry}/`. Verify lại: PASS.
+
+### Nối dây `FileWorkspaceService` (R06-T05 → R08-T12)
+
+Báo cáo R06 để lại nợ: `FileWorkspaceService` (R06-T05) chưa có call site thật. Xác nhận lại bằng grep trước R08-T12: đúng 0 occurrence trong `ui/folder_tab.py`. Khi tách `document_preview_manager.py` (R08-T12), mọi điểm ghi text thuần (`save`, `create_new_file`, `write_content`) chuyển sang gọi `FileWorkspaceService.write_file` — dùng `WorkspaceSession.unscoped(...)` vì Folder Explorer duyệt bất kỳ thư mục nào, không giới hạn 1 project sandbox. Nhánh ghi `.pptx` (binary) vẫn giữ nguyên đường cũ.
+
+**Tác dụng phụ có lợi**: `infrastructure/filesystem/file_tools.py::write_file` đã có sẵn cảnh báo cú pháp Python và tự build `.xlsx` thật từ text — 2 hành vi này **trước đây không tồn tại** trên đường ghi cũ của `folder_tab.py`, giờ được hưởng miễn phí.
+
+---
+
+## 6. Cải thiện phụ (không nằm trong yêu cầu task)
+
+| Cải thiện | Ảnh hưởng |
+| :--- | :--- |
+| `McpServerConnection.is_alive()` (R05, `core/mcp_client.py`) | Cho `McpToolSourceManager` biết một connection cached đã chết để khởi động lại. |
+| `domain/tasks/schedule_calculator.py` có bộ test riêng (R07) | `core/tasks.py` tự nhận "Qt-free, unit-testable" nhưng **0 test tồn tại** cho cron/interval/holiday-exclusion trước R07-T02. Giờ 14 test. |
+| `AiEditModelResolver.routed_provider`/`.routed_model` (R08-T12, property public mới) | Cần thêm để giữ `tests/integration/test_routing_surfaces.py`'s 2 test AI-Edit routing sau khi lớp routing chuyển từ `FolderTab` sang `AiEditModelResolver` — tránh hồi quy 1 test có từ EPIC R03. |
+
+---
+
+## 7. Còn nợ & cần quyết định
+
+| # | Nội dung | Người quyết |
+| :--- | :--- | :--- |
+| 1 | **Xung đột quy hoạch thư mục `infrastructure/persistence/json/atomic_write.py`** (R06) với `atomic_json_file.py` do Team Nam quy hoạch ở R02-T01 — chưa có xung đột file thật, cần xác nhận hợp nhất hay giữ 2 module song song. | Team Nam |
+| 2 | **Xung đột quy hoạch thư mục `application/monitoring/`** (R08-T13, `dashboard_query_service.py`) — quy hoạch cho Team Nam ở R08-T07→T10, nhưng plan gốc lại đặt file Dashboard vào đúng thư mục này. Chưa có xung đột file thật (thư mục trống trước đó). | Team Nam |
+| 3 | **`WorkspaceRepository`/`ConversationRepository` (R06) vẫn chưa có call site sản xuất thật** — R08-T12 chỉ nối `FileWorkspaceService`, chưa đụng 2 repository kia. | Chưa có EPIC nào nhận |
+| 4 | **AI-Edit pipeline (`ai_edit_pipeline.py`) và Graph Q&A ask-flow (`graph_qa_widget.py::_ask`) chưa có test end-to-end thật** — cả 2 chạy trên `AgentWorker` (QThread) thật, và **vốn dĩ đã không có test nào trước khi refactor** (xác nhận bằng grep). | Có thể thuộc phạm vi R10 Testing Pyramid |
+| 5 | **Dev tooling chưa cập nhật đường dẫn cũ**: `tools/check_controls_alive.py`, `tools/capture_screens.py`, `tools/build_audit_page.py`, `docs/screens/*.json`, `docs/ui-audit*.html` vẫn tham chiếu `ui/schedule_task_tab.py`/`ui/folder_tab.py`/`ui/dashboard_tab.py`/`ui/structure_graph_view.py` (không còn tồn tại). Không nằm trong `tests/`, không ảnh hưởng CI. | Chưa quyết định người phụ trách |
+
+---
+
+## 8. Phạm vi chưa kiểm thử
+
+* **R05-T04 (gate cho MCP/connector) chưa test với MCP server thật** — dùng `ToolSpec` giả, chưa thử `core/mcp_client.py::McpServerConnection` chạy subprocess thật.
+* **`McpToolSourceManager` (R05-T05) chưa test với subprocess MCP thật** — dùng `_FakeConnection`.
+* **`presentation/folder/ai_edit_pipeline.py`** (toàn bộ luồng plan → edit → apply/discard qua `AgentWorker` streaming) — chỉ verify bằng import/construction, chưa gửi instruction qua worker thật.
+* **`presentation/graph/graph_qa_widget.py::_ask`** — tương tự, chỉ test phần không cần AgentWorker thật.
+* **`office_document_renderer.py`'s PDF/LibreOffice conversion path** — chưa xác nhận kịch bản fallback trên máy không có QtPdf/LibreOffice bằng test thật.
+* **Đã mở app thật bằng `python -c "import cowork_local.app"` sau mỗi task** để xác nhận không lỗi import — **chưa** mở app GUI thật, thao tác tay qua toàn bộ 4 màn hình đã tách để xác nhận trải nghiệm người dùng cuối.
+
+---
+
+## 9. Việc kế tiếp của Team Hoa
+
+Toàn bộ 4 EPIC thuộc phạm vi Team Hoa (R05, R06, R07, R08 phần T11→T14) đã **hoàn tất**. Các bước còn lại không thuộc EPIC riêng của Team Hoa nữa:
+
+| Việc | Điều kiện |
+| :--- | :--- |
+| Checkpoint 2 (Services & Sub-widgets, 28/08) | Cần Team Duy (R08-T01→T06) và Team Nam (R08-T07→T10) xong phần UI split của họ |
+| CASAN Check 2 (Modularity/LOC, Team Hoa chủ trì, 30/08) | `scripts/check_loc.py` chưa tồn tại (thuộc R10-T02, Team Duy) |
+| Giải quyết mục 7 #1, #2 | Khi Team Nam bắt đầu R02-T01 và R08-T07→T10 |
+| R10 (Testing, Packaging & Contributor Experience) | Team Duy chủ trì, chờ 3 team hoàn tất |
+
+---
+
+## 10. Lịch sử commit
+
+| Commit | Nội dung |
+| :--- | :--- |
+| `ae4fe72` | feat(R05): tool capability registry, unified policy gateway, MCP lifecycle manager |
+| `cf542b7` | feat(R06): workspace session snapshot, atomic persistence, history-dir race fix |
+| `69ab8e1` | feat(R07): task repository, schedule calculator, Qt clock adapter, task/AI-planner services |
+| `0e51356` | feat(R08): split ScheduleTaskTab, FolderTab, DashboardTab, StructureGraphView |
+| *(gộp báo cáo)* | docs(refactor): merge Team Hoa reports R05→R08 into one; rename branch to `feature/teamhoa/r05-r08` |

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/Refactoring_Checklist.md

@@ -0,0 +1,417 @@
+# 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]`.
+
+---
+
+## 📊 TIẾN ĐỘ THỰC TẾ — TEAM DUY (cập nhật `2026-08-21 10:55`)
+
+> [!NOTE]
+> ### ✅ ĐÃ HOÀN TẤT: 16/16 task của **R01, R03, R04** — đã commit & push lên nhánh `feature/deltateam/refactor-plan`
+>
+> | EPIC | Task | Trạng thái |
+> | :--- | :--- | :--- |
+> | **R01** Architecture Foundation | T01 → T05 | ✅ 5/5 |
+> | **R03** Providers & Routing | T01 → T06 | ✅ 6/6 |
+> | **R04** Agent Runtime & Conversation | T01 → T05 | ✅ 5/5 |
+>
+> **Kiểm chứng (chạy thật, không phải ước lượng):**
+> * `pytest tests/` ➔ **243 pass / 2 fail** trong 44s
+> * Suite nhanh (`unit + contracts + characterization + routing`) ➔ **218 pass trong 1,16s** (đạt yêu cầu CASAN "A – Automated Tests < 1s cho unit")
+> * `python scripts/check_imports.py` ➔ **PASS** (0 Qt import trong `domain/`, `application/`)
+> * Mọi file production mới **< 400 dòng** (lớn nhất: `routing_application_service.py` 353 dòng)
+> * 2 test fail là **lỗi có sẵn từ trước**, thuộc EPIC **R02**: `config.py` vẫn hardcode `sandbox_pw = "quandh14"` ➔ `tests/test_config_security.py` đỏ
+>
+> ### 📍 PHẠM VI TEAM DUY & PHẦN CÒN LẠI
+> Theo `Feature_Architecture_Proposal.md` (dòng 7) và `DeltaTeam_prompt.md` (dòng 17), Team Duy chủ trì **R01, R03, R04, R08 (phân hệ Chat UI), R10**.
+> * ✅ **R01, R03, R04** — xong 16/16 task, đã push.
+> * ⬜ **R08 (R08-T01 ➔ R08-T06)** — chưa bắt đầu: tách `ui/chat_panel.py` (1.795 dòng) thành 6 widget < 400 dòng.
+> * ⬜ **R10** — làm sau cùng, chờ 3 team hoàn tất.
+> * **R02 thuộc 🟣 Team Nam** (xem mục EPIC R02 bên dưới) — đây là nguyên nhân 2 test đỏ ở trên, không phải việc của Team Duy.
+>
+> ### 📄 BÁO CÁO CHI TIẾT
+> Xem `docs/refactor/BaoCao_TeamDuy_R01_R03_R04.md` — kết quả từng EPIC, bằng chứng kiểm thử, 3 lỗi thật đã phát hiện, và phạm vi **chưa** kiểm thử.
+>
+> ### 📌 CÒN NỢ / CẦN QUYẾT ĐỊNH
+> 1. `ProviderRegistry` **chưa nối** vào `state.build_provider_for` (vẫn dùng `providers/factory.py`). Nối vào sẽ sửa luôn lỗi: usage của `ollama`/`github_copilot`/`codex` hiện bị ghi nhận nhầm thành `openai_compat` trên Dashboard — nhưng làm vậy sẽ **đổi cách gom dữ liệu lịch sử**.
+> 2. Mode `fallback` đã hỗ trợ ở config + service nhưng **chưa có trên toggle UI** (thuộc R08).
+> 3. Đã sửa 2 dòng trong `config.py` (`routing_mode_for` / `set_routing_mode_for`) để dùng chung một bộ từ vựng mode — **cần báo Team Nam** vì file này đang được refactor ở R02.
+> 4. Circular import `core/model_pricing.py` ↔ `core/usage_tracker.py` **chưa xử lý** (task ngày 28/08).
+> 5. Việc kế tiếp của Team Duy là **R08 phân hệ Chat UI** (6 widget con), rồi **R10** sau cùng.
+
+---
+
+## 📊 TIẾN ĐỘ THỰC TẾ — TEAM HOA (cập nhật `2026-08-21 22:57`)
+
+> [!NOTE]
+> ### ✅ ĐÃ HOÀN TẤT: 10/10 task của **R05 + R06** — branch `feature/teamhoa/r05-r06` (tạo từ `origin/feature/deltateam/refactor-plan`, có sẵn nền R01/R03/R04)
+>
+> | EPIC | Task | Trạng thái |
+> | :--- | :--- | :--- |
+> | **R05** Tool, MCP & Connector Policy | T01 → T05 | ✅ 5/5 |
+> | **R06** Workspace, Filesystem & History Isolation | T01 → T05 | ✅ 5/5 |
+>
+> **Kiểm chứng (chạy thật):**
+> * `pytest tests/` ➔ **283 pass / 4 fail** (+41 test mới cho R05+R06, gồm 2 test Qt offscreen thật trong `tests/integration/test_history_dir_race.py`)
+> * 4 fail là **lỗi có sẵn từ trước**, không liên quan R05/R06: 2 trong `test_config_security.py` (EPIC R02, đã ghi nhận bởi Team Duy) + 2 trong `test_routing_wiring.py` (môi trường máy này có Ollama/llama3.1 thật + config routing cục bộ khác "fresh install").
+> * `python scripts/check_imports.py` ➔ **PASS** (0 Qt import trong `domain/`, `application/`)
+> * Mọi file mới **< 400 dòng** (lớn nhất: `domain/tools/tool_registry.py` 125 dòng). `core/tools.py` giảm từ 566 ➔ 291 dòng.
+>
+> ### 📄 BÁO CÁO CHI TIẾT
+> Xem `docs/refactor/BaoCao_TeamHoa_R05_R08.md` (báo cáo gộp R05→R08) — kết quả từng EPIC, bằng chứng kiểm thử, 2 lỗi thật đã phát hiện (permission gate bị bỏ qua cho MCP tools, race condition lưu nhầm lịch sử), và phạm vi **chưa** kiểm thử.
+>
+> ### 🔧 TÓM TẮT R06
+> * **R06-T01**: `domain/workspaces/workspace_session.py::WorkspaceSession` — snapshot bất biến (project_id, workspace_root, sandbox_dir, allowed_paths) + `is_allowed(path)`.
+> * **R06-T02**: `infrastructure/persistence/json/{workspace_repository_impl,conversation_repository_impl}.py` bọc `core/projects.py`/`core/history.py`. **Đã sửa bug thật**: `save_project`/`save_conversation`/`rename_conversation`/`set_pinned` trước đây `path.write_text()` không atomic (crash giữa lúc ghi = file JSON hỏng, `load_project`/`load_conversation` coi file hỏng như "không tồn tại" — mất project/hội thoại âm thầm). Giờ cả 4 hàm ghi qua `infrastructure/persistence/json/atomic_write.py::write_json` (temp file + `os.replace`). Có test giả lập crash giữa lúc ghi xác nhận file cũ không bị hỏng.
+> * **R06-T03**: `infrastructure/filesystem/execution_workspace.py::ExecutionWorkspace` — đặt tên cho quy ước `.scratch` đã có sẵn (không đổi vị trí file).
+> * **R06-T04**: Sửa race trong `ui/chat_panel.py` (không phải trực tiếp `_load_current`, xem "còn nợ" #2). `ChatPanel._persist_session` (lưu hội thoại của turn CHẠY NGẦM, không phải conversation đang xem) trước đây gọi `self.ctx.config.history_dir()` SỐNG tại thời điểm turn xong — nếu user đổi project khi turn còn chạy (`_load_current` ghi `config._project_history_dir`), turn nền lưu nhầm vào thư mục lịch sử của project MỚI. Fix: thêm `"home_history_dir"` vào dict `ctx` per-turn đã có sẵn (cùng quy ước với `home_id`/`home_messages`/`home_title`), chụp tại lúc submit. Test thật bằng Qt offscreen: `tests/integration/test_history_dir_race.py`.
+> * **R06-T05**: `application/workspaces/file_workspace_service.py::FileWorkspaceService` — cho File Explorer/AI Editor gọi `execute_tool` (list_dir/read_file/write_file/edit_file) giống agent, không tự viết lại logic.
+>
+> ### 🔧 TÓM TẮT R05
+> * **R05-T01/T02**: `core/tools.py`'s if/elif dispatcher tách thành `infrastructure/filesystem/{file_tools,command_tools,fetch_tools,tool_context}.py` + `domain/tools/{tool_descriptor,tool_registry}.py`. `core/tools.py` còn lại là shim strangler-fig (re-export `ToolContext`/`ToolError`, dispatch qua dict).
+> * **R05-T03**: `application/conversations/tool_policy_gateway.py::ToolPolicyGateway` — thay `if gate is not None and name in ("run_command","install_package")` (chat_agent.py) và `if name in (WRITE_TOOLS|MS365_WRITE_TOOLS)` (code_agent.py) bằng một lookup capability chung. Đã verify bằng test: đúng 2 tool cũ vẫn được gate, không tool nào khác bị ảnh hưởng.
+> * **R05-T04 — ⚠️ THAY ĐỔI HÀNH VI CÓ CHỦ ĐÍCH**: trước đây MCP/connector/ext-connector tools (`core/mcp_client.py`, `core/ext_connectors.py`) chạy qua `extra_executor(name, args)` **không hề qua permission gate**. Giờ mọi `extra_tools` được gắn capability mặc định (`WRITE|EXECUTE|NETWORK`, vì MCP không có chuẩn khai báo rủi ro) và đi qua CÙNG `ToolPolicyGateway` như built-in tools. Khi Settings có "confirm before running commands" bật, tool MCP/connector giờ sẽ hỏi xác nhận — người dùng SẼ thấy thêm prompt so với trước. Test: `tests/unit/test_cowork_extra_tool_policy.py`.
+> * **R05-T05**: `infrastructure/mcp/mcp_source_manager.py::McpToolSourceManager` — tách lifecycle connection (cache/lock/start-or-skip) ra khỏi `state.py::AppContext` (trước đây inline trong `_mcp_connections`/`_conn_lock`). `AppContext` giờ chỉ gọi `self._mcp_manager.ensure/stop/stop_all`. `_ext_connections` (Connectors CAD/CAE/MS365/Other) KHÔNG thuộc phạm vi T05, vẫn giữ `_conn_lock` riêng như cũ.
+>
+> ### 📌 CÒN NỢ / CẦN QUYẾT ĐỊNH
+> 1. **Xung đột file với EPIC R02 (Team Nam)**: R02-T01 giao `infrastructure/persistence/json/atomic_json_file.py` cho Team Nam. R06-T02 cần atomic write NGAY (bug thật, không chờ được) nên đã tạo `infrastructure/persistence/json/atomic_write.py` — tên khác, cùng thư mục, không đụng file của Team Nam. `core/projects.py`/`core/history.py` đang dùng module này trực tiếp. **Cần Team Nam xác nhận khi bắt đầu R02-T01**: nên hợp nhất `atomic_write.py` vào `atomic_json_file.py` (Team Hoa đổi 4 import) hay giữ 2 module riêng (rủi ro trôi giữa 2 cách ghi atomic).
+> 2. **`WorkspaceRepository`/`ConversationRepository`/`FileWorkspaceService` chưa có nơi gọi thật** — giống tình trạng `ProviderRegistry` của Team Duy ở R03. Mọi call site sản xuất (`ui/workspace_tab.py`, `ui/folder_tab.py`, `state.py`, task executors) vẫn dùng trực tiếp `core/projects.py`/`core/history.py`/`core/tools.py::execute_tool` — các class mới là seam cho tầng application ở EPIC sau (R07/R08), chưa nối dây.
+> 3. **R06-T04 phạm vi thực tế khác một chút so với mô tả gốc**: bug không nằm ở `ui/workspace_tab.py::_load_current` (hàm đó chỉ *set* `config._project_history_dir`, không tự đọc lại nó) mà ở `ui/chat_panel.py::_persist_session` — nơi một turn chạy ngầm đọc SỐNG giá trị đó lúc turn xong. Đã sửa đúng điểm đọc, có test Qt offscreen thật (`tests/integration/test_history_dir_race.py`), nhưng chưa đổi kiến trúc `_load_current` như plan gốc gợi ý (dùng session id thay biến toàn cục) — việc đó cần tách `ChatPanel`/`WorkspaceTab` sâu hơn, thuộc phạm vi R08 (UI/Application Separation).
+> 4. R05/R06 xong toàn bộ — Team Hoa chờ chỉ đạo cho **R07** (Scheduling & Workflow Runtime, phối hợp Team Nam) hoặc merge/review trước khi tiếp tục.
+
+---
+
+## 📊 TIẾN ĐỘ THỰC TẾ — TEAM HOA, R07 + R08 (cập nhật `2026-08-27 20:52`)
+
+> [!NOTE]
+> ### ✅ ĐÃ HOÀN TẤT: 9/9 task phạm vi Team Hoa của **R07 + R08** — cùng branch `feature/teamhoa/r05-r06`
+>
+> | EPIC | Task (phạm vi Team Hoa) | Trạng thái |
+> | :--- | :--- | :--- |
+> | **R07** Scheduling & Workflow Runtime | T01 → T05 | ✅ 5/5 (T06 Co4EWorkflowService là Team Nam) |
+> | **R08** UI/Application Separation | T11 → T14 | ✅ 4/4 (T01-T10 là Team Duy/Team Nam) |
+>
+> **Kiểm chứng (chạy thật):**
+> * `pytest tests/` ➔ **377 pass / 4 fail** (+94 test mới cho R07+R08 — 328 sau R07, 377 sau R08)
+> * 4 fail là **lỗi có sẵn từ trước**, giống hệt baseline đã ghi nhận ở R05/R06 (2× `test_config_security.py` EPIC R02, 2× `test_routing_wiring.py` môi trường máy)
+> * `python scripts/check_imports.py` ➔ **PASS** (0 Qt import trong `domain/`, `application/`)
+> * Mọi file mới **< 400 dòng** (lớn nhất: `presentation/graph/graph_renderer.py` 391 dòng)
+> * `python -c "import cowork_local.app"` ➔ OK sau mỗi task (app khởi động được với toàn bộ import mới)
+>
+> ### 📄 BÁO CÁO CHI TIẾT
+> Xem `docs/refactor/BaoCao_TeamHoa_R05_R08.md` (báo cáo gộp R05→R08) — kết quả từng task, 1 quyết định kiến trúc đổi so với plan gốc (đã thực nghiệm xác nhận), việc "nối dây" `FileWorkspaceService` (nợ từ R06-T05), và phạm vi **chưa** kiểm thử.
+>
+> ### 📌 CÒN NỢ / CẦN QUYẾT ĐỊNH
+> 1. **`application/monitoring/` mới tạo ở R08-T13** (`dashboard_query_service.py`) nhưng thư mục này được quy hoạch cho Team Nam (R08-T07→T10). Chưa có xung đột file thật (thư mục trống trước đó) nhưng **cần Team Nam xác nhận** khi bắt đầu phần Monitoring của họ — xem chi tiết trong báo cáo.
+> 2. **R07-T03 đổi vị trí so với plan gốc**: `platform/qt/qt_scheduler_clock.py` ➔ `infrastructure/qt/qt_scheduler_clock.py`, sau khi xác nhận bằng thực nghiệm rằng một package `platform/` ở top-level đè lên module chuẩn `platform` của Python.
+> 3. **AI-Edit pipeline (`presentation/folder/ai_edit_pipeline.py`) và Q&A ask-flow (`presentation/graph/graph_qa_widget.py::_ask`) chưa có test end-to-end** — cả hai chạy trên `AgentWorker` (QThread) thật và **vốn đã không có test nào từ trước khi refactor** (xác nhận bằng grep). Phạm vi test của R08-T12/T14 tập trung vào phần có thể test không cần thread thật (wiring, containment, rendering) — xem mục "Phạm vi chưa kiểm thử" trong báo cáo.
+> 4. Chưa `git push` — nhánh cục bộ vẫn chưa lên được Gitea, giống tình trạng đã ghi nhận ở báo cáo R05/R06 mục 7-#1.
+
+---
+
+## 📌 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 09:56` | End: `2026-08-21 10:00`*
+- [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 10:00` | End: `2026-08-21 10:02`*
+- [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 09:58` | End: `2026-08-21 10:05`*
+- [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 10:02` | End: `2026-08-21 10:04`*
+- [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 10:04` | End: `2026-08-21 10:05`*
+
+---
+
+### 🔹 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-21 10:10` | End: `2026-08-21 10:12`*
+- [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-21 10:06` | End: `2026-08-21 10:10`*
+- [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-21 10:12` | End: `2026-08-21 10:15`*
+- [x] **R03-T04 (Team Duy)**: Di chuyển luồng gọi routing từ `ui/chat_panel.py#L638` sang `RoutingApplicationService`  
+  *Start: `2026-08-21 10:17` | End: `2026-08-21 10:20`*
+- [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-21 10:20` | End: `2026-08-21 10:22`*
+- [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-21 10:15` | End: `2026-08-21 10:17`*
+
+---
+
+### 🔹 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-21 10:23` | End: `2026-08-21 10:25`*
+- [x] **R04-T02 (Team Duy)**: Chuẩn hóa các sự kiện `AgentEvent` (TextChunk, ToolCallStarted, ToolCallResult, Error) ➔ `domain/agents/agent_event.py`  
+  *Start: `2026-08-21 10:22` | End: `2026-08-21 10:23`*
+- [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`  
+  *Start: `2026-08-21 10:25` | End: `2026-08-21 10:27`*
+- [x] **R04-T04 (Team Duy)**: Di chuyển `ui/cowork_tab.py::build_job` sang sử dụng `ConversationExecutionRequest`  
+  *Start: `2026-08-21 10:27` | End: `2026-08-21 10:31`*
+- [x] **R04-T05 (Team Duy)**: Di chuyển `core/task_executors.py` sang dùng chung `ConversationApplicationService`  
+  *Start: `2026-08-21 10:28` | End: `2026-08-21 10:30`*
+
+---
+
+### 🔹 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.
+
+- [x] **R05-T01 (Team Hoa)**: Định nghĩa `ToolDescriptor`, `ToolCapability` (read/write/execute/network) ➔ `domain/tools/tool_descriptor.py` & `domain/tools/tool_registry.py`  
+  *Start: `2026-08-21 21:40` | End: `2026-08-21 21:47`*
+- [x] **R05-T02 (Team Hoa)**: Tách nhỏ các built-in handlers từ `core/tools.py` ➔ `infrastructure/filesystem/file_tools.py`, `command_tools.py`, `fetch_tools.py`  
+  *Start: `2026-08-21 21:47` | End: `2026-08-21 21:56`*
+- [x] **R05-T03 (Team Hoa)**: Xây dựng `ToolPolicyGateway` (kiểm tra phân quyền allow/confirm/deny) ➔ `application/conversations/tool_policy_gateway.py`  
+  *Start: `2026-08-21 21:56` | End: `2026-08-21 22:04`*
+- [x] **R05-T04 (Team Hoa)**: Chuẩn hóa MCP tools từ `core/mcp_client.py` đi qua `ToolPolicyGateway`  
+  *Start: `2026-08-21 22:04` | End: `2026-08-21 22:12`*
+- [x] **R05-T05 (Team Hoa)**: Xây dựng `McpToolSourceManager` quản lý vòng đời tiến trình MCP ➔ `infrastructure/mcp/mcp_source_manager.py`  
+  *Start: `2026-08-21 22:12` | End: `2026-08-21 22:19`*
+
+---
+
+### 🔹 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.
+
+- [x] **R06-T01 (Team Hoa)**: Định nghĩa `WorkspaceSession` chứa snapshot project id, workspace root ➔ `domain/workspaces/workspace_session.py`  
+  *Start: `2026-08-21 22:19` | End: `2026-08-21 22:24`*
+- [x] **R06-T02 (Team Hoa)**: Xây dựng `WorkspaceRepository` từ `core/projects.py` & `ConversationRepository` từ `core/history.py` ➔ `infrastructure/persistence/json/workspace_repository_impl.py`  
+  *Start: `2026-08-21 22:24` | End: `2026-08-21 22:35`*
+- [x] **R06-T03 (Team Hoa)**: Xây dựng `ExecutionWorkspace` quản lý output/scratch files ➔ `infrastructure/filesystem/execution_workspace.py`  
+  *Start: `2026-08-21 22:35` | End: `2026-08-21 22:40`*
+- [x] **R06-T04 (Team Hoa)**: Khắc phục race condition trong `ui/workspace_tab.py::_load_current`  
+  *Start: `2026-08-21 22:40` | End: `2026-08-21 22:50`*
+- [x] **R06-T05 (Team Hoa)**: Xây dựng `FileWorkspaceService` xử lý thao tác file cho File Explorer và AI File Editor ➔ `application/workspaces/file_workspace_service.py`  
+  *Start: `2026-08-21 22:50` | End: `2026-08-21 22:57`*
+
+---
+
+### 🔹 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`.
+
+- [x] **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: `2026-08-27 16:05` | End: `2026-08-27 16:14`*
+- [x] **R07-T02 (Team Hoa)**: Xây dựng `ScheduleCalculator` tính due-time / cron độc lập ➔ `domain/tasks/schedule_calculator.py`  
+  *Start: `2026-08-27 16:14` | End: `2026-08-27 16:26`*
+- [x] **R07-T03 (Team Hoa)**: Xây dựng `QtSchedulerClock` adapter (tách `TaskScheduler` khỏi `QTimer`) ➔ `infrastructure/qt/qt_scheduler_clock.py` (đổi so với plan gốc `platform/qt/...` — xem báo cáo)  
+  *Start: `2026-08-27 16:26` | End: `2026-08-27 16:47`*
+- [x] **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: `2026-08-27 16:47` | End: `2026-08-27 17:02`*
+- [x] **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: `2026-08-27 17:02` | End: `2026-08-27 17:14`*
+- [ ] **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: `____-__-__ __:__`* (ngoài phạm vi Team Hoa)
+
+---
+
+### 🔹 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):
+- [x] **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` (+ `run_history_dialog.py`, `schedule_task_tab.py` shell — xem báo cáo)  
+  *Start: `2026-08-27 17:14` | End: `2026-08-27 17:39`*
+- [x] **R08-T12**: Tách `ui/folder_tab.py#L350` ➔ `workspace_file_tree.py`, `document_preview_manager.py`, `ai_file_editor_dialog.py` (+ `code_editor.py`, `office_document_renderer.py`, `ai_edit_model_resolver.py`, `ai_edit_pipeline.py`, `folder_tab.py` shell — xem báo cáo). Đã nối `FileWorkspaceService` (nợ từ R06-T05).  
+  *Start: `2026-08-27 17:39` | End: `2026-08-27 18:09`*
+- [x] **R08-T13**: Tách `ui/dashboard_tab.py` ➔ `token_usage_card_widget.py`, `usage_chart_widget.py`, `habits_widget.py` (+ `dashboard_tab.py` shell, `application/monitoring/dashboard_query_service.py` — xem báo cáo về ghi chú xung đột thư mục với Team Nam)  
+  *Start: `2026-08-27 18:09` | End: `2026-08-27 18:16`*
+- [x] **R08-T14**: Tách `ui/structure_graph_view.py` ➔ `presentation/graph/structure_graph_view.py` (shell) & `graph_qa_widget.py` (+ `graph_renderer.py`, `graph_scene_items.py`, `graph_messages_view.py`, `application/workspaces/graph_index_service.py` — xem báo cáo)  
+  *Start: `2026-08-27 18:16` | End: `2026-08-27 20:52`*
+
+---
+
+### 🔹 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 09:56` | `2026-08-21 10:25` | [x] |
+| **22-23/08 (T7-CN)** | Chuẩn hóa `ProviderDescriptor`, `ProviderRegistry`; Wrap OpenAI, Anthropic, Ollama, FPT Gateway; Viết Contract Tests | `2026-08-21 10:06` | `2026-08-21 10:12` | [x] ⚠️ registry chưa nối vào `state.build_provider_for` |
+| **24/08 (T2)** | Xây dựng `RoutingApplicationService` độc lập Qt; Tách `ComposerWidget` & `AttachmentPicker` | `2026-08-21 10:12` | `2026-08-21 10:15` | [~] RoutingApplicationService xong; tách widget thuộc R08 |
+| **25/08 (T3)** | Xây dựng `ConversationApplicationService`; Tách `ChatHistoryWidget` và bubble renderer | `2026-08-21 10:25` | `2026-08-21 10:27` | [~] Service xong; tách widget thuộc R08 |
+| **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-21 10:17` | `2026-08-21 10:22` | [~] 3 bản copy routing đã gỡ; circular import chưa xử lý |
+| **29/08 (T7)** | Viết suite integration test cho toàn bộ luồng Chat (`tests/integration/test_chat_flow.py`) | `2026-08-21 10:35` | `2026-08-21 10:52` | [~] 25 integration test tại `tests/integration/{test_cowork_turn_flow,test_task_executor_flow,test_routing_surfaces}.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 | `2026-08-21 09:58` | `2026-08-21 10:05` | [x] PASS |
+| **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ờ 3 team hoàn tất |
+
+---
+
+### 🟣 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/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`).

domain/__init__.py

@@ -0,0 +1,12 @@
+"""Domain layer - pure Python entities, value objects and events.
+
+The innermost layer of the 4-tier architecture (see
+``docs/architecture/ADR-001-layered-architecture.md``). Modules here describe
+WHAT the application is about - a turn of conversation, a model candidate, an
+agent event - and depend on nothing but the standard library.
+
+Hard rule (ADR-001 I1/I2, enforced by ``scripts/check_imports.py``): no imports
+of PySide6/PyQt, and no imports from ``application/``, ``infrastructure/``,
+``presentation/`` or the legacy ``core/``/``ui/`` packages. That is what keeps
+this layer testable in milliseconds and reusable from a headless scheduler.
+"""

domain/agents/__init__.py

@@ -0,0 +1,48 @@
+"""Domain entities for one agent turn: the request snapshot and the typed event
+stream it produces (EPIC R04)."""
+
+from .agent_event import (
+    AgentEvent,
+    AssistantDoneEvent,
+    ErrorEvent,
+    HistoryReadyEvent,
+    NoticeEvent,
+    OutputsAddedEvent,
+    OutputsRemovedEvent,
+    PlanUpdatedEvent,
+    ReasoningChunkEvent,
+    TextChunkEvent,
+    ToolCallFinishedEvent,
+    ToolCallStartedEvent,
+    ToolOutputEvent,
+    TurnCompletedEvent,
+    collect_text,
+    event_from_dict,
+    tool_calls,
+)
+from .conversation_execution_request import (
+    ConversationExecutionRequest,
+    new_turn_id,
+)
+
+__all__ = [
+    "ConversationExecutionRequest",
+    "new_turn_id",
+    "AgentEvent",
+    "TextChunkEvent",
+    "ReasoningChunkEvent",
+    "AssistantDoneEvent",
+    "PlanUpdatedEvent",
+    "ToolCallStartedEvent",
+    "ToolOutputEvent",
+    "ToolCallFinishedEvent",
+    "OutputsAddedEvent",
+    "OutputsRemovedEvent",
+    "NoticeEvent",
+    "HistoryReadyEvent",
+    "TurnCompletedEvent",
+    "ErrorEvent",
+    "event_from_dict",
+    "collect_text",
+    "tool_calls",
+]

domain/agents/agent_event.py

@@ -0,0 +1,370 @@
+"""AgentEvent - the typed event stream one agent turn produces (R04-T02).
+
+Today the turn engine talks to its caller through untyped dicts::
+
+    emit({"type": "tool_result", "id": tc_id, "name": name,
+          "ok": result.get("ok", False), "output": result.get("output", "")})
+
+and every consumer re-discovers the vocabulary by reading the producer. There
+are eleven such shapes across ``core/chat_agent.py``, ``core/code_agent.py`` and
+``core/task_executors.py``; a consumer that misspells ``"tool_result"`` or reads
+``"result"`` instead of ``"output"`` fails silently, at runtime, only for the
+tool path that triggers it.
+
+This module makes the vocabulary explicit. Each event is a frozen dataclass, so:
+
+* the set of possible events is enumerable (see :data:`EVENT_TYPES`);
+* a field name typo is an ``AttributeError`` at the point of use, not a silently
+  missing chat bubble;
+* an event can cross a thread boundary safely - it cannot be mutated after the
+  producer hands it over, which is exactly what the Qt-signal seam needs.
+
+Bridging with the legacy dicts is deliberate and two-way: :func:`event_from_dict`
+adapts what ``run_cowork`` emits today, and :meth:`AgentEvent.to_dict` renders an
+event back into the legacy shape so existing widgets keep working untouched
+while the presentation layer migrates screen by screen (EPIC R08).
+
+Pure domain code: stdlib only, no Qt, no I/O.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+
+@dataclass(frozen=True)
+class AgentEvent:
+    """Base class for everything a turn can report.
+
+    ``type`` is the legacy string tag, kept as a class attribute so the bridge
+    functions can round-trip an event without a separate mapping table.
+    """
+
+    type: str = field(init=False, default="event")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Render into the legacy ``emit()`` dict shape."""
+        return {"type": self.type}
+
+
+# --------------------------------------------------------------------------- #
+# Assistant output
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class TextChunkEvent(AgentEvent):
+    """One fragment of the visible answer, as it streams in."""
+
+    delta: str
+    type: str = field(init=False, default="text")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "delta": self.delta}
+
+
+@dataclass(frozen=True)
+class ReasoningChunkEvent(AgentEvent):
+    """One fragment of the model's PRIVATE reasoning.
+
+    Drives the "Thinking" indicator only. Consumers must never append this to
+    the answer or persist it into conversation history - keeping it a distinct
+    type is what makes that mistake hard to make by accident.
+    """
+
+    delta: str
+    type: str = field(init=False, default="reasoning")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "delta": self.delta}
+
+
+@dataclass(frozen=True)
+class AssistantDoneEvent(AgentEvent):
+    """One assistant message finished. A turn with tool calls emits this once
+    per step, not once per turn - see :class:`TurnCompletedEvent`."""
+
+    content: str = ""
+    type: str = field(init=False, default="assistant_done")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "content": self.content}
+
+
+# --------------------------------------------------------------------------- #
+# Planning
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class PlanUpdatedEvent(AgentEvent):
+    """The agent rewrote its plan (the ``update_plan`` tool)."""
+
+    steps: Tuple[Dict[str, Any], ...] = ()
+    type: str = field(init=False, default="plan_set")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "steps": [dict(s) for s in self.steps]}
+
+
+# --------------------------------------------------------------------------- #
+# Tool lifecycle
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class ToolCallStartedEvent(AgentEvent):
+    """A tool call is about to run, with the preview shown to the user.
+
+    Maps the legacy ``tool_proposed`` event. "Proposed" was a misnomer: by the
+    time it is emitted the call is already going to run unless a permission gate
+    rejects it, and the gate reports that as a finished call with ``ok=False``.
+    """
+
+    call_id: str
+    name: str
+    args: Dict[str, Any] = field(default_factory=dict)
+    preview: Optional[Dict[str, Any]] = None
+    type: str = field(init=False, default="tool_proposed")
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"type": self.type, "id": self.call_id,
+                               "name": self.name, "args": dict(self.args)}
+        if self.preview is not None:
+            out["preview"] = dict(self.preview)
+        return out
+
+
+@dataclass(frozen=True)
+class ToolOutputEvent(AgentEvent):
+    """A line of live output from a running tool (command stdout, for example)."""
+
+    call_id: str
+    name: str
+    delta: str
+    type: str = field(init=False, default="tool_output")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "id": self.call_id, "name": self.name,
+                "delta": self.delta}
+
+
+@dataclass(frozen=True)
+class ToolCallFinishedEvent(AgentEvent):
+    """A tool call ended, successfully or not.
+
+    ``ok=False`` covers every failure mode alike - the tool raised, the sandbox
+    blocked it, or the user rejected it at the permission gate - because the
+    consumer's job is the same in all three: show the failure and let the model
+    react to it.
+    """
+
+    call_id: str
+    name: str
+    ok: bool = False
+    output: str = ""
+    path: str = ""            # file the tool wrote, when it wrote one
+    produced: Tuple[str, ...] = ()   # extra artefacts (e.g. a generator's outputs)
+    type: str = field(init=False, default="tool_result")
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"type": self.type, "id": self.call_id, "name": self.name,
+                               "ok": self.ok, "output": self.output}
+        if self.path:
+            out["path"] = self.path
+        if self.produced:
+            out["produced"] = list(self.produced)
+        return out
+
+
+# --------------------------------------------------------------------------- #
+# Output folder
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class OutputsAddedEvent(AgentEvent):
+    """Files appeared in the turn's output folder."""
+
+    paths: Tuple[str, ...] = ()
+    type: str = field(init=False, default="outputs_added")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "paths": list(self.paths)}
+
+
+@dataclass(frozen=True)
+class OutputsRemovedEvent(AgentEvent):
+    """Files were cleaned up from the turn's output folder (intermediates)."""
+
+    paths: Tuple[str, ...] = ()
+    type: str = field(init=False, default="outputs_removed")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "paths": list(self.paths)}
+
+
+@dataclass(frozen=True)
+class NoticeEvent(AgentEvent):
+    """A UI-visible aside that is not part of the model's answer.
+
+    Three producers today, all reachable from a normal turn:
+    ``core/agent_security.py`` (a request or command blocked by the security
+    layer), ``core/context_budget.py`` (the conversation was auto-compressed)
+    and the attachment readers (a file that could not be processed, plus live
+    "reading page X/Y" progress).
+
+    ``level`` selects how the UI renders it: ``"progress"`` updates the thinking
+    indicator in place, anything else becomes a warning bubble. Dropping these
+    would silently hide security warnings from the user, which is why the type
+    exists rather than being folded into TextChunkEvent.
+    """
+
+    text: str
+    level: str = "info"
+    type: str = field(init=False, default="notice")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "level": self.level, "text": self.text}
+
+
+@dataclass(frozen=True)
+class HistoryReadyEvent(AgentEvent):
+    """A history session exists for this run and can be opened."""
+
+    session_id: str
+    type: str = field(init=False, default="history_ready")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "session_id": self.session_id}
+
+
+# --------------------------------------------------------------------------- #
+# Turn lifecycle - emitted by the application service, not by the legacy engine
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class TurnCompletedEvent(AgentEvent):
+    """The whole turn finished: no more events will follow.
+
+    New in R04. The legacy engine has no end-of-turn signal at all, so every
+    consumer infers "done" from the worker thread finishing - which is why a
+    cancelled turn and a failed turn look identical to the UI today.
+    """
+
+    content: str = ""
+    cancelled: bool = False
+    type: str = field(init=False, default="turn_completed")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "content": self.content, "cancelled": self.cancelled}
+
+
+@dataclass(frozen=True)
+class ErrorEvent(AgentEvent):
+    """The turn failed. ``recoverable`` marks errors the user can act on
+    (pick another model, shorten the prompt) rather than a hard outage."""
+
+    message: str
+    recoverable: bool = False
+    type: str = field(init=False, default="error")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "message": self.message,
+                "recoverable": self.recoverable}
+
+
+# The legacy tag -> event class map. Also the authoritative list of what a turn
+# can emit, which is what makes an exhaustive consumer possible for the first time.
+EVENT_TYPES: Dict[str, type] = {
+    "text": TextChunkEvent,
+    "reasoning": ReasoningChunkEvent,
+    "assistant_done": AssistantDoneEvent,
+    "plan_set": PlanUpdatedEvent,
+    "tool_proposed": ToolCallStartedEvent,
+    "tool_start": ToolCallStartedEvent,
+    "tool_output": ToolOutputEvent,
+    "tool_result": ToolCallFinishedEvent,
+    "outputs_added": OutputsAddedEvent,
+    "outputs_removed": OutputsRemovedEvent,
+    "notice": NoticeEvent,
+    "history_ready": HistoryReadyEvent,
+    "turn_completed": TurnCompletedEvent,
+    "error": ErrorEvent,
+}
+
+
+def event_from_dict(payload: Mapping[str, Any]) -> Optional[AgentEvent]:
+    """Adapt one legacy ``emit()`` dict into a typed event.
+
+    Returns ``None`` for an unknown tag instead of raising: the legacy engine is
+    still being refactored and may grow an event before this module knows about
+    it. Dropping an unrecognised event degrades the UI by one missing bubble;
+    raising here would abort a turn that had otherwise succeeded.
+    """
+    kind = str(payload.get("type", ""))
+    cls = EVENT_TYPES.get(kind)
+    if cls is None:
+        return None
+
+    if cls is TextChunkEvent or cls is ReasoningChunkEvent:
+        return cls(delta=str(payload.get("delta", "")))
+    if cls is AssistantDoneEvent:
+        return AssistantDoneEvent(content=str(payload.get("content", "")))
+    if cls is PlanUpdatedEvent:
+        return PlanUpdatedEvent(steps=tuple(payload.get("steps") or ()))
+    if cls is ToolCallStartedEvent:
+        return ToolCallStartedEvent(
+            call_id=str(payload.get("id", "")), name=str(payload.get("name", "")),
+            args=dict(payload.get("args") or {}), preview=payload.get("preview"),
+        )
+    if cls is ToolOutputEvent:
+        return ToolOutputEvent(call_id=str(payload.get("id", "")),
+                               name=str(payload.get("name", "")),
+                               delta=str(payload.get("delta", "")))
+    if cls is ToolCallFinishedEvent:
+        return ToolCallFinishedEvent(
+            call_id=str(payload.get("id", "")), name=str(payload.get("name", "")),
+            ok=bool(payload.get("ok", False)), output=str(payload.get("output", "")),
+            path=str(payload.get("path", "") or ""),
+            produced=tuple(payload.get("produced") or ()),
+        )
+    if cls is OutputsAddedEvent or cls is OutputsRemovedEvent:
+        return cls(paths=tuple(str(p) for p in (payload.get("paths") or ())))
+    if cls is NoticeEvent:
+        return NoticeEvent(text=str(payload.get("text", "")),
+                           level=str(payload.get("level", "info")))
+    if cls is HistoryReadyEvent:
+        return HistoryReadyEvent(session_id=str(payload.get("session_id", "")))
+    if cls is TurnCompletedEvent:
+        return TurnCompletedEvent(content=str(payload.get("content", "")),
+                                  cancelled=bool(payload.get("cancelled", False)))
+    return ErrorEvent(message=str(payload.get("message", "")),
+                      recoverable=bool(payload.get("recoverable", False)))
+
+
+def collect_text(events: Sequence[AgentEvent]) -> str:
+    """Join every :class:`TextChunkEvent` - the visible answer, reasoning excluded.
+
+    Provided here so no consumer has to re-derive "which events are the answer",
+    the question the untyped dicts made easy to get wrong.
+    """
+    return "".join(e.delta for e in events if isinstance(e, TextChunkEvent))
+
+
+def tool_calls(events: Sequence[AgentEvent]) -> List[ToolCallFinishedEvent]:
+    """Every finished tool call, in order - for audit views and assertions."""
+    return [e for e in events if isinstance(e, ToolCallFinishedEvent)]
+
+
+__all__ = [
+    "AgentEvent",
+    "TextChunkEvent",
+    "ReasoningChunkEvent",
+    "AssistantDoneEvent",
+    "PlanUpdatedEvent",
+    "ToolCallStartedEvent",
+    "ToolOutputEvent",
+    "ToolCallFinishedEvent",
+    "OutputsAddedEvent",
+    "OutputsRemovedEvent",
+    "NoticeEvent",
+    "HistoryReadyEvent",
+    "TurnCompletedEvent",
+    "ErrorEvent",
+    "EVENT_TYPES",
+    "event_from_dict",
+    "collect_text",
+    "tool_calls",
+]

domain/agents/conversation_execution_request.py

@@ -0,0 +1,192 @@
+"""ConversationExecutionRequest - an immutable snapshot of one turn (R04-T01).
+
+``ui/cowork_tab.py::build_job`` currently builds a closure that reads widget
+state from inside the worker thread::
+
+    def job(worker):
+        provider = self.build_provider()      # reads combo boxes
+        extra_tools, extra_exec = self.ctx.build_mcp_tools()
+        proj_ctx = project_context_text(load_project(project_id))
+        ...
+
+Everything that closure touches can change while the turn is running: the user
+can pick another model, switch workspace, or edit the project instructions. The
+turn then runs on a mixture of old and new state, and which mixture depends on
+thread timing - the class of bug that reproduces once a week and never in a test.
+
+This value object is the fix: the presentation layer captures everything a turn
+needs ON THE UI THREAD, at submit time, into one frozen object. Whatever happens
+to the widgets afterwards, the turn keeps running on the state the user actually
+submitted.
+
+Pure domain code: stdlib only, no Qt, no filesystem access. Paths are held as
+strings, not ``Path`` objects, so the snapshot stays trivially serialisable -
+which is what will let a turn be queued, replayed or logged later.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+# Default tool-use budget for an interactive turn, and the higher ceiling a
+# run-to-completion step (a Co4E flow step) is allowed. Same numbers
+# ``core.chat_agent.run_cowork`` defaults to - kept here so the policy is
+# visible in the request rather than buried in a function signature.
+DEFAULT_MAX_STEPS = 30
+DEFAULT_COMPLETION_MAX_STEPS = 200
+
+
+def new_turn_id() -> str:
+    """A fresh turn id. Short and random: it only has to be unique within a
+    session's lifetime, and it shows up in log lines humans read."""
+    return uuid.uuid4().hex[:12]
+
+
+@dataclass(frozen=True)
+class ConversationExecutionRequest:
+    """Everything one agent turn needs, captured at submit time.
+
+    Attributes:
+        prompt: the user's message for this turn (already assembled, including
+            any attachment text the UI inlined).
+        messages: the full conversation to send, oldest first. Held as a tuple
+            so the snapshot cannot be mutated after capture; use
+            :meth:`message_list` to get the mutable copy the engine expects.
+        output_dir: this turn's OWN folder. Each turn writes into an isolated
+            directory so parallel turns cannot clobber each other's files.
+        session_id: the conversation this turn belongs to.
+        turn_id: unique per turn, for logs and for matching events to a turn.
+        surface: which screen submitted it ("cowork", "co4e", "ai_edit", "task").
+        provider / model: what to run on, already resolved (routing included).
+            Empty ``model`` means "the provider's configured default".
+        title: conversation title, used to name generated files.
+        project_id / project_context: the workspace and its shared instructions,
+            snapshotted so a mid-turn workspace switch cannot change them.
+        agent_role: audit-log attribution for every tool call this turn makes.
+        allowed_tools: permission scope. ``None`` means "all enabled tools";
+            a list restricts the ADVERTISED catalogue, so a read-only step
+            literally cannot be offered a writing tool.
+        max_steps / run_to_completion / completion_max_steps: tool-use budget.
+        enforce_rules: run the security rulebase. Co4E sandboxed runs disable it.
+        confirm_commands: ask before run_command/install_package (permission gate).
+        metadata: free-form extras a caller wants carried along (never
+            interpreted here) - e.g. a scheduled task's id.
+    """
+
+    prompt: str
+    messages: Tuple[Mapping[str, Any], ...] = ()
+    output_dir: str = ""
+    session_id: str = ""
+    turn_id: str = field(default_factory=new_turn_id)
+    surface: str = "cowork"
+    provider: str = ""
+    model: str = ""
+    title: str = ""
+    project_id: str = ""
+    project_context: str = ""
+    agent_role: str = ""
+    allowed_tools: Optional[Tuple[str, ...]] = None
+    max_steps: int = DEFAULT_MAX_STEPS
+    run_to_completion: bool = False
+    completion_max_steps: int = DEFAULT_COMPLETION_MAX_STEPS
+    enforce_rules: bool = True
+    confirm_commands: bool = False
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    # -- construction helpers ------------------------------------------- #
+    @classmethod
+    def create(cls, prompt: str, messages: Optional[Sequence[Mapping[str, Any]]] = None,
+               **kwargs: Any) -> "ConversationExecutionRequest":
+        """Build a request from ordinary mutable inputs.
+
+        The messages list is copied element by element, so a later append by the
+        caller (the chat panel keeps appending to its own list) cannot reach
+        inside a request that is already running.
+        """
+        snapshot = tuple(dict(m) for m in (messages or ()))
+        allowed = kwargs.pop("allowed_tools", None)
+        return cls(prompt=prompt, messages=snapshot,
+                   allowed_tools=tuple(allowed) if allowed is not None else None,
+                   **kwargs)
+
+    def with_messages(self, messages: Sequence[Mapping[str, Any]]
+                      ) -> "ConversationExecutionRequest":
+        """A copy carrying a different message list, everything else unchanged.
+
+        Used when a caller assembles the system prompt or trims history after
+        building the request - it must produce a NEW snapshot rather than mutate
+        the one a turn may already be running on.
+        """
+        return replace(self, messages=tuple(dict(m) for m in messages))
+
+    def with_model(self, provider: str, model: str) -> "ConversationExecutionRequest":
+        """A copy pinned to another provider/model - how a routing switch is
+        applied without touching the user's saved settings."""
+        return replace(self, provider=provider, model=model)
+
+    # -- accessors ------------------------------------------------------ #
+    def message_list(self) -> List[Dict[str, Any]]:
+        """A fresh mutable copy of the messages, for the engine to append to.
+
+        The legacy engine mutates the list it is given (it inserts the system
+        prompt and appends assistant/tool messages). Handing it a copy is what
+        keeps this snapshot immutable in practice and not just by declaration.
+        """
+        return [dict(m) for m in self.messages]
+
+    @property
+    def effective_max_steps(self) -> int:
+        """The tool-use ceiling actually in force for this turn."""
+        return self.completion_max_steps if self.run_to_completion else self.max_steps
+
+    @property
+    def has_output_dir(self) -> bool:
+        """True when this turn may write files."""
+        return bool(self.output_dir)
+
+    def allows_tool(self, name: str) -> bool:
+        """Whether ``name`` is inside this turn's permission scope.
+
+        ``update_plan`` is always allowed: it has no side effects and drives the
+        Plan panel, so scoping it out would silently break the UI rather than
+        restrict a capability.
+        """
+        if self.allowed_tools is None:
+            return True
+        return name == "update_plan" or name in self.allowed_tools
+
+    def describe(self) -> str:
+        """Compact one-line identity for log lines."""
+        target = f"{self.provider}/{self.model}" if self.model else self.provider or "default"
+        return f"turn={self.turn_id} surface={self.surface} model={target}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe projection, for logging a turn or persisting it for replay."""
+        return {
+            "turn_id": self.turn_id,
+            "session_id": self.session_id,
+            "surface": self.surface,
+            "prompt": self.prompt,
+            "message_count": len(self.messages),
+            "output_dir": self.output_dir,
+            "provider": self.provider,
+            "model": self.model,
+            "title": self.title,
+            "project_id": self.project_id,
+            "agent_role": self.agent_role,
+            "allowed_tools": list(self.allowed_tools) if self.allowed_tools is not None else None,
+            "max_steps": self.effective_max_steps,
+            "run_to_completion": self.run_to_completion,
+            "enforce_rules": self.enforce_rules,
+            "confirm_commands": self.confirm_commands,
+            "metadata": dict(self.metadata),
+        }
+
+
+__all__ = [
+    "ConversationExecutionRequest",
+    "new_turn_id",
+    "DEFAULT_MAX_STEPS",
+    "DEFAULT_COMPLETION_MAX_STEPS",
+]

domain/models/__init__.py

@@ -0,0 +1,5 @@
+"""Domain models: provider/model catalogue value objects (EPIC R03)."""
+
+from .provider_descriptor import ProviderCapability, ProviderDescriptor
+
+__all__ = ["ProviderDescriptor", "ProviderCapability"]

domain/models/provider_descriptor.py

@@ -0,0 +1,171 @@
+"""ProviderDescriptor - the declarative catalogue entry for one model provider (R03-T02).
+
+Today the knowledge of "what a provider is" is scattered across three places
+that must be edited together and can silently drift apart:
+
+* ``providers/factory.py::_REGISTRY``  - name -> implementation class
+* ``config.py::DEFAULT_CONFIG["providers"]`` - default base_url / model / api_key
+* ``config.py::PROVIDER_LABELS``       - the human label shown in Settings
+
+Adding a provider means remembering all three; forgetting one produces a
+provider that exists but has no label, or a label with no implementation. This
+value object folds those facts into a single immutable description that the
+registry (``infrastructure/providers/provider_registry.py``) and the UI can both
+read, so a new provider is declared once.
+
+Pure domain code: stdlib only, no Qt, no network, no config access. It describes
+a provider; building one is infrastructure's job.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, FrozenSet, List, Mapping, Optional, Tuple
+
+
+class ProviderCapability(str, Enum):
+    """What a provider can do, as advertised by its descriptor.
+
+    Kept as a closed enum rather than free-form strings so a typo
+    (``"vison"``) fails at import time instead of silently disabling a feature
+    at runtime. Inherits ``str`` so existing dict/JSON code that compares against
+    plain strings keeps working during the migration.
+    """
+
+    STREAMING = "streaming"      # can stream answer fragments through on_text
+    TOOLS = "tools"              # can be given a ToolSpec catalogue and call tools
+    VISION = "vision"            # accepts image content blocks (see providers/base.py)
+    REASONING = "reasoning"      # emits a separate private "thinking" stream
+    MODEL_LISTING = "model_listing"  # list_models() returns a real catalogue
+
+
+@dataclass(frozen=True)
+class ProviderDescriptor:
+    """An immutable description of one provider the app can talk to.
+
+    Attributes:
+        id: the config key, e.g. ``"openai_compat"``. Also the ``provider`` half
+            of a routing candidate key (``provider/model_id``).
+        label: human-readable name for Settings and the model picker.
+        protocol: which wire format this provider speaks. Several ids share one
+            protocol - ``ollama``, ``github_copilot`` and ``codex`` are all
+            OpenAI-compatible endpoints - which is exactly why protocol and id
+            must be separate fields.
+        default_model: the model used when the user has not chosen one.
+        capabilities: what the provider supports (see :class:`ProviderCapability`).
+        requires_api_key: whether an empty ``api_key`` makes it unusable.
+        requires_base_url: whether an empty ``base_url`` makes it unusable.
+        local: True when the endpoint runs on the user's own machine. Routing
+            treats local models as zero-cost, and the security layer treats them
+            as not leaving the machine, so this is a real behavioural flag and
+            not just documentation.
+        notes: free-form remark shown in Settings (e.g. "paste a Copilot token").
+    """
+
+    id: str
+    label: str
+    protocol: str
+    default_model: str = ""
+    capabilities: FrozenSet[ProviderCapability] = field(default_factory=frozenset)
+    requires_api_key: bool = True
+    requires_base_url: bool = True
+    local: bool = False
+    notes: str = ""
+
+    # -- capability queries ---------------------------------------------- #
+    def supports(self, capability: ProviderCapability) -> bool:
+        """True when this provider advertises ``capability``."""
+        return capability in self.capabilities
+
+    @property
+    def supports_vision(self) -> bool:
+        """Mirrors ``providers.base.Provider.supports_vision`` so callers can ask
+        the descriptor (no instance, no network) before building a provider."""
+        return self.supports(ProviderCapability.VISION)
+
+    @property
+    def supports_tools(self) -> bool:
+        """True when this provider can run an agent turn with tools. A provider
+        without it can still chat, but must never be routed a tool-using task."""
+        return self.supports(ProviderCapability.TOOLS)
+
+    def capability_names(self) -> List[str]:
+        """Capabilities as sorted plain strings - the shape the routing layer's
+        ``required_capabilities`` filter and the assessment store both use."""
+        return sorted(c.value for c in self.capabilities)
+
+    # -- configuration validation ---------------------------------------- #
+    def missing_settings(self, conf: Mapping[str, Any]) -> List[str]:
+        """Which required config keys are absent or blank in ``conf``.
+
+        Returned as a list (not a bool) so Settings can tell the user exactly
+        what to fill in, instead of a generic "not configured". A provider that
+        needs nothing returns an empty list.
+        """
+        missing: List[str] = []
+        if self.requires_api_key and not str(conf.get("api_key", "") or "").strip():
+            missing.append("api_key")
+        if self.requires_base_url and not str(conf.get("base_url", "") or "").strip():
+            missing.append("base_url")
+        return missing
+
+    def is_configured(self, conf: Mapping[str, Any]) -> bool:
+        """True when ``conf`` carries everything this provider needs to run."""
+        return not self.missing_settings(conf)
+
+    def resolve_model(self, conf: Optional[Mapping[str, Any]] = None,
+                      requested: str = "") -> str:
+        """Pick the model id for a call: explicit request, else configured, else
+        this descriptor's default.
+
+        Centralised here because the same three-step fallback is currently
+        re-implemented at every call site (chat panel, Co4E, AI-edit, scheduler),
+        and each of them gets the precedence subtly different.
+        """
+        if requested:
+            return requested
+        configured = str((conf or {}).get("model", "") or "").strip()
+        return configured or self.default_model
+
+    def describe(self, conf: Optional[Mapping[str, Any]] = None) -> str:
+        """One-line summary for logs and the Settings row, e.g.
+        ``"anthropic:claude-sonnet-4-6 (Anthropic Claude)"``."""
+        return f"{self.id}:{self.resolve_model(conf)} ({self.label})"
+
+    def candidate_key(self, model_id: str) -> str:
+        """The ``provider/model_id`` identity the routing layer keys on.
+
+        Defined here so the domain owns the format; ``core.routing.models`` has
+        its own ``candidate_key()`` helper producing the identical string, and
+        keeping them equal is what lets the new registry and the existing
+        assessment store share one keyspace during the migration.
+        """
+        return f"{self.id}/{model_id}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe projection, for persisting a catalogue snapshot or sending
+        the descriptor to a UI layer that must not import domain types."""
+        return {
+            "id": self.id,
+            "label": self.label,
+            "protocol": self.protocol,
+            "default_model": self.default_model,
+            "capabilities": self.capability_names(),
+            "requires_api_key": self.requires_api_key,
+            "requires_base_url": self.requires_base_url,
+            "local": self.local,
+            "notes": self.notes,
+        }
+
+
+def split_candidate_key(key: str) -> Tuple[str, str]:
+    """Inverse of :meth:`ProviderDescriptor.candidate_key`.
+
+    Splits on the FIRST ``/`` only: some gateways expose model ids that contain
+    a slash (``org/model``), and splitting on the last one would corrupt them.
+    """
+    provider, _, model_id = key.partition("/")
+    return provider, model_id
+
+
+__all__ = ["ProviderCapability", "ProviderDescriptor", "split_candidate_key"]

domain/tasks/__init__.py

@@ -0,0 +1,5 @@
+"""Domain entities for schedule/due-time computation (EPIC R07)."""
+
+from .schedule_calculator import ScheduleCalculator
+
+__all__ = ["ScheduleCalculator"]

domain/tasks/schedule_calculator.py

@@ -0,0 +1,165 @@
+"""ScheduleCalculator - due-time / cron / interval math for Schedule Task,
+extracted from ``core/tasks.py``'s "schedule math" section (R07-T02).
+
+``core/tasks.py`` is already Qt-free (its own docstring says so), but it
+still lives under ``core/`` where nothing enforces that "pure" claim - and it
+is the ONE piece of scheduling logic ``docs/refactor/plan.md`` calls out as
+needing its own unit tests (none existed before this task; see
+``tests/unit/test_schedule_calculator.py``). Moving it to ``domain/tasks/``
+makes the purity a build-time guarantee (``scripts/check_imports.py`` fails
+the build if this file ever imports Qt, ``core``, or anything with I/O) and
+gives the date math a home that is trivially unit-testable without going
+through ``core/tasks.py``'s file-repository concerns at all.
+
+Two pieces of this math are themselves implemented elsewhere in ``core/`` -
+``core/cron.py::Cron`` (5-field cron parsing) and
+``core/holiday_calendar.py::is_holiday`` (VN public holidays). Importing
+``core`` from ``domain`` is exactly what ADR-001 rule I2 forbids (domain must
+not know infrastructure/core exists), so this class takes them as
+constructor-injected callables instead of importing them - the same
+dependency-inversion shape ``application/conversations/conversation_
+application_service.py`` (R04-T03) already uses for its provider factory.
+``core/tasks.py`` wires the real ``Cron``/``is_holiday`` in; tests can inject
+plain stub functions with zero I/O.
+"""
+from __future__ import annotations
+
+import calendar
+from datetime import datetime, timedelta
+from typing import Any, Callable, Dict, List, Optional, Protocol
+
+# Same on-disk format core/tasks.py::_TIME_FMT uses for schedule.run_at.
+# Duplicated here (not imported - that would be a domain -> core edge) since
+# it's a 1-line format string, not business logic.
+_TIME_FMT = "%Y-%m-%d %H:%M"
+
+_CRON_SEARCH_GUARD = 400   # matches the guard core/tasks.py used before extraction
+
+
+class _CronLike(Protocol):
+    """Structural shape this class needs from a cron object - satisfied by
+    ``core/cron.py::Cron`` without this module importing it."""
+
+    def next_after(self, after: datetime) -> Optional[datetime]:
+        ...
+
+
+def _parse_run_at(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.strptime(value, _TIME_FMT)
+    except ValueError:
+        return None
+
+
+class ScheduleCalculator:
+    """Pure due-time computation for one task's ``schedule`` dict.
+
+    ``is_holiday``: ``Callable[[date, country_code], bool]`` or ``None`` -
+    when ``None``, a schedule with ``skip_holidays`` set simply never treats
+    any day as a holiday (degrades gracefully instead of raising, mirroring
+    how a caller who doesn't care about holidays can just not wire it up).
+
+    ``make_cron``: ``Callable[[str], _CronLike]`` (raises on a malformed
+    expression) or ``None`` - when ``None``, ``repeat_type == "cron"``
+    schedules never produce a next run (same as an invalid expression today).
+    """
+
+    def __init__(self,
+                is_holiday: Optional[Callable[[Any, str], bool]] = None,
+                make_cron: Optional[Callable[[str], _CronLike]] = None) -> None:
+        self._is_holiday = is_holiday
+        self._make_cron = make_cron
+
+    def is_excluded_day(self, dt: datetime, sched: Dict[str, Any]) -> bool:
+        """True when ``dt`` falls on a day this schedule must skip: a
+        weekend (working_days_only) or a public holiday of the configured
+        country."""
+        if sched.get("working_days_only") and dt.weekday() >= 5:   # 5=Sat, 6=Sun
+            return True
+        if sched.get("skip_holidays") and self._is_holiday is not None:
+            if self._is_holiday(dt.date(), sched.get("holiday_country", "")):
+                return True
+        return False
+
+    def add_month(self, dt: datetime) -> datetime:
+        """Calendar-aware +1 month, clamping the day to the target month's
+        length (e.g. Jan 31 + 1 month -> Feb 28/29, not an overflow error)."""
+        year = dt.year + (1 if dt.month == 12 else 0)
+        month = 1 if dt.month == 12 else dt.month + 1
+        day = min(dt.day, calendar.monthrange(year, month)[1])
+        return dt.replace(year=year, month=month, day=day)
+
+    def shift_off_excluded_days(self, dt: datetime, sched: Dict[str, Any]) -> datetime:
+        """Push ``dt`` forward one day at a time until it lands on an
+        allowed day (same time of day) - used for one-time schedules set on
+        a weekend/holiday."""
+        guard = 0
+        while self.is_excluded_day(dt, sched) and guard < _CRON_SEARCH_GUARD:
+            dt += timedelta(days=1)
+            guard += 1
+        return dt
+
+    def compute_next_run(self, task: Dict[str, Any], after: datetime) -> Optional[datetime]:
+        """The next run time strictly after ``after`` for a repeating task
+        (daily / weekly / monthly / cron), or ``None`` for one-shot
+        schedules. Occurrences on excluded days are skipped forward."""
+        sched = task.get("schedule", {})
+        repeat = sched.get("repeat_type", "none")
+
+        if repeat == "cron":
+            if self._make_cron is None:
+                return None
+            try:
+                cron = self._make_cron(sched.get("cron_expression") or "")
+            except Exception:
+                # Any malformed-expression error the injected factory raises
+                # (core/cron.py::CronError, or a fake's own error type in
+                # tests) means "this schedule can't compute a next run" - not
+                # a domain-layer crash.
+                return None
+            nxt = cron.next_after(after)
+            guard = 0
+            while nxt is not None and self.is_excluded_day(nxt, sched) and guard < _CRON_SEARCH_GUARD:
+                nxt = cron.next_after(nxt)
+                guard += 1
+            return nxt
+
+        base = _parse_run_at(sched.get("run_at"))
+        if base is None:
+            return None
+        if repeat == "daily":
+            advance = lambda d: d + timedelta(days=1)          # noqa: E731
+        elif repeat == "weekly":
+            advance = lambda d: d + timedelta(weeks=1)         # noqa: E731
+        elif repeat == "monthly":
+            advance = self.add_month
+        else:
+            return None
+        nxt = base
+        while nxt <= after:
+            nxt = advance(nxt)
+        guard = 0
+        while self.is_excluded_day(nxt, sched) and guard < _CRON_SEARCH_GUARD:
+            nxt = advance(nxt)
+            guard += 1
+        return nxt
+
+    def due_tasks(self, tasks: List[Dict[str, Any]], now: datetime) -> List[Dict[str, Any]]:
+        """Tasks that should start now: Scheduled + schedule enabled +
+        run_at due."""
+        due = []
+        for t in tasks:
+            if t.get("status") != "scheduled":
+                continue
+            sched = t.get("schedule", {})
+            if not sched.get("enabled"):
+                continue
+            run_at = _parse_run_at(sched.get("run_at"))
+            if run_at is not None and run_at <= now:
+                due.append(t)
+        return due
+
+
+__all__ = ["ScheduleCalculator"]

domain/tools/__init__.py

@@ -0,0 +1,18 @@
+"""Domain entities for tool risk classification and lookup (EPIC R05)."""
+
+from .tool_descriptor import ToolCapability, ToolDescriptor
+from .tool_registry import (
+    BUILT_IN_CAPABILITIES,
+    UNKNOWN_SOURCE_CAPABILITIES,
+    ToolRegistry,
+    default_registry,
+)
+
+__all__ = [
+    "ToolCapability",
+    "ToolDescriptor",
+    "ToolRegistry",
+    "BUILT_IN_CAPABILITIES",
+    "UNKNOWN_SOURCE_CAPABILITIES",
+    "default_registry",
+]

domain/tools/tool_descriptor.py

@@ -0,0 +1,86 @@
+"""ToolCapability / ToolDescriptor - the risk-tagged catalogue entry for one
+tool the agent loop can call (R05-T01).
+
+Today a tool is just a name inside ``core/tools.py::TOOL_SPECS`` (a
+``providers.base.ToolSpec`` — name/description/JSON-schema parameters, with
+no notion of risk) plus a hand-written membership test wherever gating is
+needed: ``core/tools.py::WRITE_TOOLS``, ``core/code_agent.py``'s
+``WRITE_TOOLS | MS365_WRITE_TOOLS``, and ``core/chat_agent.py``'s literal
+``name in ("run_command", "install_package")``. Three call sites, three
+independently-maintained lists, and a new tool (or an MCP/connector tool,
+which has no list membership at all - see ``core/mcp_client.py``) is gated
+only if someone remembers to add it everywhere.
+
+``ToolDescriptor`` makes the risk an attribute of the tool itself, declared
+once, so ``application/conversations/tool_policy_gateway.py`` (R05-T03) can
+decide ALLOW/CONFIRM/DENY from data instead of a growing set of literal
+tuples.
+
+Pure domain code: stdlib only, no Qt, no I/O. ``to_spec``/``from_spec`` are
+the only place this module touches something outside domain/, and that
+something (``providers.base.ToolSpec``) is itself a plain dataclass with no
+further dependencies.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Flag, auto
+from typing import Any, Dict
+
+from cowork_local.providers.base import ToolSpec
+
+
+class ToolCapability(Flag):
+    """What calling a tool can do to the machine or the network.
+
+    A ``Flag`` (not a plain ``Enum``) because a single tool can combine risks
+    - ``install_package`` writes to the environment, runs pip as a
+    subprocess, AND needs network access. Composing three separate booleans
+    per call site is exactly the duplication this type replaces.
+    """
+
+    NONE = 0
+    READ = auto()
+    WRITE = auto()
+    EXECUTE = auto()
+    NETWORK = auto()
+
+
+@dataclass(frozen=True)
+class ToolDescriptor:
+    """An immutable description of one callable tool.
+
+    Attributes:
+        name: the identifier the model calls (``ToolSpec.name``).
+        description: shown to the model, unchanged from ``ToolSpec``.
+        parameters: JSON-Schema object for the call's arguments.
+        capabilities: the risk this tool carries - see :class:`ToolCapability`.
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    capabilities: ToolCapability = ToolCapability.NONE
+
+    def has(self, capability: ToolCapability) -> bool:
+        """True when this tool carries (any bit of) ``capability``."""
+        return bool(self.capabilities & capability)
+
+    def to_spec(self) -> ToolSpec:
+        """Project back to the ``ToolSpec`` shape the model-facing catalogue
+        and the provider call actually use - risk tagging is metadata the
+        wire format has no room for."""
+        return ToolSpec(name=self.name, description=self.description,
+                        parameters=self.parameters)
+
+    @classmethod
+    def from_spec(cls, spec: ToolSpec,
+                  capabilities: ToolCapability = ToolCapability.NONE) -> "ToolDescriptor":
+        """Wrap an existing ``ToolSpec`` (built-in, MCP, or connector) with a
+        capability tag. The one place callers attach risk to a spec they did
+        not author themselves."""
+        return cls(name=spec.name, description=spec.description,
+                   parameters=spec.parameters, capabilities=capabilities)
+
+
+__all__ = ["ToolCapability", "ToolDescriptor"]

domain/tools/tool_registry.py

@@ -0,0 +1,125 @@
+"""ToolRegistry - the centralised catalogue every tool source registers into
+(R05-T01).
+
+Built-in file/command/fetch tools (``core/tools.py``), MCP server tools
+(``core/mcp_client.py``) and unified connectors (``core/ext_connectors.py``)
+each produce their own ``List[ToolSpec]`` today, concatenated ad-hoc by
+``core/tools.py::combine_tool_sources``. None of that concatenation carries
+risk information, which is exactly why an MCP tool call reaches
+``core/chat_agent.py`` with no ``ToolDescriptor`` to consult and skips the
+permission gate entirely (the gap R05-T04 closes).
+
+``ToolRegistry`` is the one place a :class:`~domain.tools.tool_descriptor.ToolDescriptor`
+is looked up by name, so a policy gateway - or anything else that needs to ask
+"what can this tool do" - has a single source of truth instead of re-deriving
+it from a spec list.
+
+Pure domain code: stdlib only, no Qt, no I/O.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional
+
+from cowork_local.providers.base import ToolSpec
+
+from .tool_descriptor import ToolCapability, ToolDescriptor
+
+
+class ToolRegistry:
+    """An in-memory, name-keyed catalogue of :class:`ToolDescriptor`.
+
+    Deliberately mutable and unordered-by-name-only: a turn builds one
+    registry from whichever tool sources it has (built-ins + whatever MCP
+    servers/connectors are enabled), so re-registering the same name simply
+    replaces the previous descriptor rather than raising - the same
+    "last one wins" behaviour ``combine_tool_sources`` already has for
+    duplicate tool names across sources.
+    """
+
+    def __init__(self, descriptors: Optional[Iterable[ToolDescriptor]] = None) -> None:
+        self._by_name: Dict[str, ToolDescriptor] = {}
+        for descriptor in descriptors or ():
+            self.register(descriptor)
+
+    def register(self, descriptor: ToolDescriptor) -> None:
+        self._by_name[descriptor.name] = descriptor
+
+    def get(self, name: str) -> Optional[ToolDescriptor]:
+        return self._by_name.get(name)
+
+    def all(self) -> List[ToolDescriptor]:
+        return list(self._by_name.values())
+
+    def specs(self) -> List[ToolSpec]:
+        """Every registered descriptor, projected back to ``ToolSpec`` - the
+        shape the provider call and the model-facing catalogue need."""
+        return [d.to_spec() for d in self._by_name.values()]
+
+    def capabilities_for(self, name: str) -> ToolCapability:
+        """The capability set for ``name``, or ``NONE`` for an unknown tool.
+
+        Returning ``NONE`` rather than raising lets a policy gateway treat an
+        unregistered tool the same way as one with no declared risk - the
+        gateway's DENY-on-unknown-name rule is a deliberate, separate check,
+        not something this lookup should pre-empt.
+        """
+        descriptor = self._by_name.get(name)
+        return descriptor.capabilities if descriptor is not None else ToolCapability.NONE
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._by_name
+
+    def __len__(self) -> int:
+        return len(self._by_name)
+
+
+# --------------------------------------------------------------------------- #
+# Default capability map for this app's built-in tools (core/tools.py).
+# Kept here, next to the registry, rather than inside core/tools.py itself -
+# core/ is the legacy engine layer being strangled, not where new domain facts
+# should accumulate.
+# --------------------------------------------------------------------------- #
+_CAP = ToolCapability
+BUILT_IN_CAPABILITIES: Dict[str, ToolCapability] = {
+    "read_file": _CAP.READ,
+    "list_dir": _CAP.READ,
+    "write_file": _CAP.WRITE,
+    "edit_file": _CAP.WRITE,
+    "run_command": _CAP.EXECUTE,
+    "install_package": _CAP.WRITE | _CAP.EXECUTE | _CAP.NETWORK,
+    "fetch_url": _CAP.NETWORK,
+    "jira_search": _CAP.NETWORK,
+    "jira_get_issue": _CAP.NETWORK,
+    # Advertised by every engine but has no filesystem/process/network effect
+    # of its own - it only drives the Plan panel (see core/chat_agent.py).
+    "update_plan": _CAP.NONE,
+    "save_file": _CAP.WRITE,
+}
+
+# Tools with no standard, self-declared risk metadata (every MCP server tool,
+# every unified connector) are tagged with this conservative default - see
+# R05-T04. Better to over-gate an unknown remote tool than to silently let it
+# through as READ-only.
+UNKNOWN_SOURCE_CAPABILITIES: ToolCapability = _CAP.WRITE | _CAP.EXECUTE | _CAP.NETWORK
+
+
+def default_registry(specs: Iterable[ToolSpec]) -> ToolRegistry:
+    """Build a registry from ``core/tools.py``'s own ``TOOL_SPECS`` (plus
+    ``save_file``/``update_plan``, which the engines add separately), using
+    :data:`BUILT_IN_CAPABILITIES`. A spec with no entry in that map falls back
+    to :data:`UNKNOWN_SOURCE_CAPABILITIES` - the same conservative default
+    applied to MCP/connector tools, so a built-in nobody has classified yet
+    fails safe instead of silently ungated."""
+    registry = ToolRegistry()
+    for spec in specs:
+        capability = BUILT_IN_CAPABILITIES.get(spec.name, UNKNOWN_SOURCE_CAPABILITIES)
+        registry.register(ToolDescriptor.from_spec(spec, capability))
+    return registry
+
+
+__all__ = [
+    "ToolRegistry",
+    "BUILT_IN_CAPABILITIES",
+    "UNKNOWN_SOURCE_CAPABILITIES",
+    "default_registry",
+]

domain/workspaces/__init__.py

@@ -0,0 +1,5 @@
+"""Domain entities for workspace/project isolation (EPIC R06)."""
+
+from .workspace_session import WorkspaceSession
+
+__all__ = ["WorkspaceSession"]

domain/workspaces/workspace_session.py

@@ -0,0 +1,96 @@
+"""WorkspaceSession - an immutable snapshot of which project a turn belongs
+to and where it may touch the filesystem (R06-T01).
+
+``state.py::AppContext.active_project_id`` is a single mutable field read by
+every background worker thread. ``ui/workspace_tab.py::_load_current`` writes
+it (and the related ``config._project_history_dir``) on the UI thread the
+moment the user switches projects - while a turn already running on a
+worker thread may read either field mid-switch and end up acting on the
+OTHER project's workspace/history for the rest of its run (the race
+R06-T04 fixes).
+
+The fix, same shape as R04's ``ConversationExecutionRequest``: capture the
+workspace facts a turn needs ONCE, on the thread that knows which project is
+selected, into one frozen object. Whatever the user does to the UI afterwards,
+the turn keeps using the workspace it was handed at submit time.
+
+Pure domain code: stdlib only, no Qt, no network. It does touch ``Path`` (not
+plain strings, unlike ``ConversationExecutionRequest``) because its whole job
+is path-containment checking - a snapshot with no room to answer "is this
+path mine" would not replace what ``ToolContext.resolve`` currently does
+inline.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class WorkspaceSession:
+    """Everything a turn needs to know about ITS workspace, fixed at the
+    moment it was submitted.
+
+    Attributes:
+        project_id: the project this turn belongs to (``""`` when no project
+            is selected - e.g. the Code tab, which has no project concept).
+        workspace_root: the project's sandbox root (``Project.workspace_dir()``).
+        sandbox_dir: the ``.scratch`` subtree inside ``workspace_root`` used for
+            generator/helper scripts, never a final deliverable (see
+            ``infrastructure/filesystem/file_tools.py::_flatten_rel``).
+        allowed_paths: every root a tool call may read/write under. Almost
+            always just ``(workspace_root,)``; a project with a custom
+            ``output_dir`` outside the managed workspace tree still resolves
+            to exactly one root - the tuple exists so a future caller (e.g. a
+            step scoped to a shared input folder) can widen it without a
+            shape change.
+    """
+
+    project_id: str
+    workspace_root: Path
+    sandbox_dir: Path
+    allowed_paths: Tuple[Path, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if not self.allowed_paths:
+            object.__setattr__(self, "allowed_paths", (self.workspace_root,))
+
+    @classmethod
+    def from_project(cls, project) -> "WorkspaceSession":
+        """Build a session from a ``core.projects.Project``. ``project`` is
+        typed loosely (not imported) so this module has no dependency on
+        ``core/`` - the caller (``core/projects.py`` itself, or
+        ``application/conversations``) already has the Project in hand."""
+        root = Path(project.workspace_dir())
+        return cls(project_id=project.project_id, workspace_root=root,
+                   sandbox_dir=root / ".scratch", allowed_paths=(root,))
+
+    @classmethod
+    def unscoped(cls, workspace_root: Path) -> "WorkspaceSession":
+        """A session for callers with no project concept (e.g. the Code tab,
+        which sandboxes to a plain folder rather than a ``Project``)."""
+        root = Path(workspace_root)
+        return cls(project_id="", workspace_root=root, sandbox_dir=root / ".scratch")
+
+    def is_allowed(self, path: Path) -> bool:
+        """True when ``path`` resolves inside one of :attr:`allowed_paths`.
+
+        Same containment rule as ``ToolContext.resolve`` (an exact root match
+        or a real descendant), but side-effect-free: it reports the answer
+        instead of raising, so a caller (``FileWorkspaceService``, R06-T05)
+        can decide what "not allowed" means for its own UI instead of
+        catching a ``ToolError``.
+        """
+        try:
+            resolved = Path(path).expanduser().resolve()
+        except OSError:
+            return False
+        for allowed in self.allowed_paths:
+            root = Path(allowed).resolve()
+            if resolved == root or root in resolved.parents:
+                return True
+        return False
+
+
+__all__ = ["WorkspaceSession"]

infrastructure/__init__.py

@@ -0,0 +1,7 @@
+"""Infrastructure layer - adapters to the outside world.
+
+Concrete implementations of what the inner layers only describe: HTTP calls to
+model gateways, the OS keyring, the filesystem, subprocesses, telemetry sinks.
+May import ``domain/`` (to speak its types) and third-party libraries, but never
+``presentation/``/``ui/``.
+"""

infrastructure/filesystem/__init__.py

@@ -0,0 +1,6 @@
+"""Filesystem/process/network tool adapters split out of ``core/tools.py``
+(EPIC R05) and the sandbox execution context they share."""
+
+from .tool_context import CancelFn, ToolContext, ToolError
+
+__all__ = ["CancelFn", "ToolContext", "ToolError"]

infrastructure/filesystem/command_tools.py

@@ -0,0 +1,110 @@
+"""Command tools - run_command, install_package (R05-T02).
+
+Moved verbatim out of ``core/tools.py`` (see ``file_tools.py`` for why). These
+two are the ones today's hand-written permission gate in
+``core/chat_agent.py`` singles out by literal name
+(``name in ("run_command", "install_package")``) — R05-T03 replaces that
+tuple with a capability lookup, but the tools themselves are unchanged here.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .tool_context import CancelFn, ToolContext
+
+COMMAND_TIMEOUT = 120  # seconds
+
+_SNAPSHOT_SKIP = {".git", "__pycache__", "node_modules", ".scratch", ".venv",
+                  ".idea", ".mypy_cache", ".pytest_cache"}
+
+
+def _snapshot(workdir: Path) -> Dict[str, Any]:
+    """Map of file path -> (mtime, size) under the workdir (noise dirs skipped)."""
+    snap: Dict[str, Any] = {}
+    try:
+        for dirpath, dirnames, filenames in os.walk(str(workdir)):
+            dirnames[:] = [d for d in dirnames if d not in _SNAPSHOT_SKIP]
+            for fn in filenames:
+                full = os.path.join(dirpath, fn)
+                try:
+                    st = os.stat(full)
+                    snap[full] = (st.st_mtime_ns, st.st_size)
+                except OSError:
+                    pass
+            if len(snap) > 5000:
+                return snap
+    except OSError:
+        pass
+    return snap
+
+
+def _sandbox_python(ctx: ToolContext, cancel: Optional[CancelFn] = None,
+                     on_output=None) -> Optional[str]:
+    """Lazily create/reuse this ctx's project sandbox venv (Code tab only —
+    ``ctx.sandbox``); returns its python path, or None to use the app's own."""
+    if not ctx.sandbox:
+        return None
+    from cowork_local.core.deps import ensure_project_venv
+
+    py = ensure_project_venv(ctx.workdir, cancel=cancel, on_output=on_output)
+    return str(py) if py else None
+
+
+def run_command(ctx: ToolContext, args: Dict[str, Any],
+                 cancel: Optional[CancelFn] = None,
+                 on_output=None) -> Dict[str, Any]:
+    from cowork_local.core.deps import network_blocked_env, run_cancellable, sandbox_env
+    from cowork_local.core.sandbox_manager import ExecutionConfig, SandboxManager
+    from cowork_local.security.command_risk_classifier import classify_command
+
+    command = str(args.get("command", "")).strip()
+    if not command:
+        return {"ok": False, "output": "Empty command."}
+
+    # --- Security validation pipeline ---
+    risk = classify_command(command, is_cowork_mode=ctx.flatten_writes)
+    if risk.blocked:
+        denial = "Command blocked by security policy: " + "; ".join(risk.reasons)
+        return {"ok": False, "output": denial}
+
+    # Route through SandboxManager for risk-based isolation
+    mgr = SandboxManager(ExecutionConfig(
+        enabled=True,
+        block_network_by_default=ctx.block_network,
+        is_cowork_mode=ctx.flatten_writes,
+    ))
+    sandbox_result = mgr.run(
+        command=command,
+        workdir=str(ctx.workdir),
+        block_network=ctx.block_network,
+        timeout_sec=COMMAND_TIMEOUT,
+        cancel=cancel,
+    )
+    # Sandbox ALWAYS executes (never double-run). Return its result directly.
+    if sandbox_result.get("sandbox") == "blocked":
+        return {"ok": False, "output": sandbox_result.get("stderr", "Command blocked")}
+    out = sandbox_result.get("stdout", "").strip() or "(no output)"
+    err = sandbox_result.get("stderr", "")
+    rc = sandbox_result.get("returncode", -1)
+    if err:
+        out = f"{out}\n{err}" if out else err
+    return {"ok": sandbox_result.get("ok", False), "output": f"[exit {rc}]\n{out}"}
+
+
+def install_package(ctx: ToolContext, args: Dict[str, Any],
+                     cancel: Optional[CancelFn] = None,
+                     on_output=None) -> Dict[str, Any]:
+    from cowork_local.core.deps import pip_install
+
+    package = str(args.get("package", "")).strip()
+    if not package:
+        return {"ok": False, "output": "No package specified."}
+    python = _sandbox_python(ctx, cancel, on_output)
+    ok, detail = pip_install(package, cancel=cancel, on_output=on_output, python=python)
+    head = f"Installed {package}." if ok else f"Could not install {package}."
+    return {"ok": ok, "output": f"{head}\n{detail}"}
+
+
+__all__ = ["COMMAND_TIMEOUT", "run_command", "install_package", "_snapshot"]

infrastructure/filesystem/execution_workspace.py

@@ -0,0 +1,80 @@
+"""ExecutionWorkspace - the output folder vs. the scratch folder for one
+turn, as two distinct properties instead of a name convention (R06-T03).
+
+Today the ``.scratch`` subtree is a special case buried inside
+``_flatten_rel`` (``infrastructure/filesystem/file_tools.py``): a generator
+script writes there, the deliverable lands in the output root, and
+``core/chat_agent.py`` cleans ``.scratch`` up after the turn — but nothing
+NAMES "the scratch folder" as a thing; every call site re-derives
+``workdir / ".scratch"`` (or checks ``Path(rel).parts[0] == ".scratch"``) by
+hand. This class gives that convention one home.
+
+It does not change WHERE files land - ``workspace_root/.scratch`` stays
+exactly what it always was. It exists so a caller (an application service,
+R06-T05's ``FileWorkspaceService``, or a future turn-cleanup step) can ask
+for "the output dir" / "the scratch dir" instead of hand-building the path
+and hoping the convention hasn't drifted.
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from cowork_local.domain.workspaces import WorkspaceSession
+
+SCRATCH_DIRNAME = ".scratch"
+
+
+@dataclass(frozen=True)
+class ExecutionWorkspace:
+    """The two folders a turn actually writes to, derived from a
+    :class:`WorkspaceSession`.
+
+    ``output_dir`` is always the session's ``workspace_root`` itself, not a
+    per-turn subfolder - Cowork's whole design is that every deliverable lands
+    directly in the one configured Output folder (see
+    ``infrastructure/filesystem/file_tools.py::_flatten_rel``'s docstring).
+    ``scratch_dir`` is the SAME flat ``workspace_root/.scratch`` every turn on
+    that workspace already shares today (``core/chat_agent.py``'s
+    ``_cleanup_cowork_intermediates`` operates on that exact path) - this
+    class does not introduce per-turn namespacing that doesn't exist in the
+    engine yet, only names the existing convention.
+
+    ``turn_id`` is kept as metadata for callers that want to attribute a
+    workspace to the turn that used it (logging, future per-turn scratch
+    namespacing); it does not affect either path today.
+    """
+
+    session: WorkspaceSession
+    turn_id: str
+
+    @property
+    def output_dir(self) -> Path:
+        return self.session.workspace_root
+
+    @property
+    def scratch_dir(self) -> Path:
+        return self.session.workspace_root / SCRATCH_DIRNAME
+
+    def ensure_dirs(self) -> None:
+        """Create both folders if they don't exist yet. Callers that only
+        need one (most do) can skip this and let ``write_file`` create parents
+        on demand, same as today."""
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.scratch_dir.mkdir(parents=True, exist_ok=True)
+
+    def cleanup_scratch(self) -> None:
+        """Unconditionally remove the scratch subtree.
+
+        Coarser than ``core/chat_agent.py::_cleanup_cowork_intermediates``,
+        which rescues any real deliverable a generator script wrote INSIDE
+        ``.scratch`` before wiping it - that rescue logic stays there. This
+        is for callers that only need "make the scratch folder go away"
+        (e.g. before starting a fresh run) and know it holds nothing worth
+        saving.
+        """
+        shutil.rmtree(self.scratch_dir, ignore_errors=True)
+
+
+__all__ = ["ExecutionWorkspace", "SCRATCH_DIRNAME"]

infrastructure/filesystem/fetch_tools.py

@@ -0,0 +1,55 @@
+"""Fetch tools - fetch_url, jira_search, jira_get_issue (R05-T02).
+
+Moved verbatim out of ``core/tools.py`` (see ``file_tools.py`` for why). The
+network access these three carry is exactly what the ``ToolCapability.NETWORK``
+tag added in R05-T01/domain/tools/tool_registry.py describes.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .tool_context import ToolContext
+
+
+def fetch_url(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Fetch a URL's text content (web page / online document / SharePoint-
+    OneDrive share link) via link_fetch — the same parser task-link attachments
+    use. Honors the Sandbox Security Layer's "Block network" policy."""
+    url = str(args.get("url", "")).strip()
+    if not url:
+        return {"ok": False, "output": "fetch_url: 'url' is required."}
+    if not url.lower().startswith(("http://", "https://")):
+        return {"ok": False, "output": f"fetch_url: not an http(s) URL: {url}"}
+    if not ctx.allow_url_fetch:
+        return {"ok": False,
+                "output": ("fetch_url: URL fetching is turned off in Settings → Security "
+                           "(\"Allow the agent to fetch URLs\").")}
+    # A pasted Jira issue link on the CONNECTED Jira host is read via the
+    # authenticated API (so private issues resolve, not a login page). Public
+    # links / any other URL fall through to the normal fetcher below.
+    from cowork_local.core import jira_tool
+    if jira_tool.is_jira_issue_url(ctx.jira, url):
+        return {"ok": True, "output": jira_tool.get_issue_by_url(ctx.jira, url)}
+    from cowork_local.core.link_fetch import fetch_link_preview
+
+    return {"ok": True, "output": fetch_link_preview(url)}
+
+
+def jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    from cowork_local.core import jira_tool
+
+    out = jira_tool.search(ctx.jira, str(args.get("jql", "")),
+                           int(args.get("max_results", 25) or 25))
+    return {"ok": not out.lower().startswith(("jira is not configured", "jira search failed")),
+            "output": out}
+
+
+def jira_get_issue(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    from cowork_local.core import jira_tool
+
+    out = jira_tool.get_issue(ctx.jira, str(args.get("key", "")))
+    return {"ok": not out.lower().startswith(("jira is not configured", "could not fetch")),
+            "output": out}
+
+
+__all__ = ["fetch_url", "jira_search", "jira_get_issue"]

infrastructure/filesystem/file_tools.py

@@ -0,0 +1,136 @@
+"""File tools - read_file, list_dir, write_file, edit_file (R05-T02).
+
+Moved verbatim out of ``core/tools.py``, whose ``execute_tool`` used to
+dispatch to these via a hand-written if/elif chain over every tool name it
+knew about. Splitting the built-in handlers into per-concern modules
+(this one, ``command_tools.py``, ``fetch_tools.py``) means adding a tool no
+longer means growing that one function; ``core/tools.py::execute_tool`` now
+looks the name up in a dict built from these modules instead.
+
+Behavior is unchanged from before the split - this is a pure move, not a
+rewrite. Every existing characterization/contract test that exercises
+read_file/write_file/edit_file/list_dir through ``core.tools.execute_tool``
+still exercises the exact same code, just imported from here.
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any, Dict
+
+from .tool_context import ToolContext
+
+MAX_READ_BYTES = 200_000
+
+
+def _flatten_rel(rel: str) -> str:
+    """Collapse a sub-folder path down to a bare filename so the file lands in the
+    workdir root — EXCEPT the ``.scratch`` sandbox subtree, which is preserved.
+
+    Used by the Cowork agent (flatten_writes=True) so it can never create a
+    per-session / per-chat / per-task output sub-folder: every deliverable stays
+    directly in the single configured Output folder."""
+    parts = Path(rel).parts
+    if parts and parts[0] == ".scratch":
+        return rel  # temporary sandbox is allowed (and cleaned up afterwards)
+    return Path(rel).name or rel
+
+
+def _check_python_syntax(target: Path, content: str) -> str:
+    """Return a short warning if ``content`` is invalid Python, else ''.
+
+    Catches syntax errors the instant a .py file is written/edited — before the
+    agent wastes a whole run_command round-trip just to get the same error back
+    from a traceback."""
+    if target.suffix.lower() not in (".py", ".pyw"):
+        return ""
+    try:
+        ast.parse(content, filename=str(target))
+        return ""
+    except SyntaxError as exc:
+        return f"\n⚠ Syntax error at line {exc.lineno}: {exc.msg} — fix this before running the file."
+
+
+def read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    target = ctx.resolve(str(args.get("path", "")))
+    if not target.exists():
+        return {"ok": False, "output": f"File not found: {args.get('path')}"}
+    data = target.read_bytes()[:MAX_READ_BYTES]
+    text = data.decode("utf-8", errors="replace")
+    return {"ok": True, "output": text}
+
+
+def list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    rel = str(args.get("path", ".") or ".")
+    target = ctx.resolve(rel)
+    # A missing/not-yet-created path is NOT a tool failure — report it as an
+    # ordinary result so the agent can create it or pick another path and keep
+    # going. Returning ok=False here surfaced a false "tool failed: list_dir" in
+    # Co4E flows and could stall a step on a recoverable situation.
+    if not target.exists():
+        return {"ok": True, "output": f"(path '{rel}' does not exist yet — create it or use another path)"}
+    if target.is_file():
+        return {"ok": True, "output": f"('{rel}' is a file, not a directory)"}
+    entries = []
+    for child in sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower())):
+        marker = "/" if child.is_dir() else ""
+        entries.append(f"{child.name}{marker}")
+    return {"ok": True, "output": "\n".join(entries) or "(empty folder)"}
+
+
+def write_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    rel = str(args.get("path", ""))
+    if ctx.flatten_writes:
+        rel = _flatten_rel(rel)
+    target = ctx.resolve(rel)
+    content = str(args.get("content", ""))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # A .xlsx is a binary package — build a REAL workbook from the content
+    # (CSV/TSV/Markdown-table/JSON) rather than writing raw text (which corrupts it).
+    if target.suffix.lower() in (".xlsx", ".xlsm"):
+        from cowork_local.core import xlsx_write
+        if xlsx_write.build_xlsx_from_text(target, content):
+            return {"ok": True, "path": str(target),
+                    "output": f"Wrote spreadsheet {rel} ({target.name})."}
+        return {"ok": False, "output": "Could not build the .xlsx (openpyxl unavailable) — "
+                "write a .csv instead, or use a generator script."}
+    target.write_text(content, encoding="utf-8")
+    warning = _check_python_syntax(target, content)
+    return {"ok": True, "path": str(target),
+            "output": f"Wrote {len(content)} chars to {rel}.{warning}"}
+
+
+def edit_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Replace an exact snippet inside an existing file (precise patch edit)."""
+    rel = str(args.get("path", ""))
+    if ctx.flatten_writes:
+        rel = _flatten_rel(rel)
+    target = ctx.resolve(rel)
+    if not target.exists():
+        return {"ok": False,
+                "output": f"File not found: {rel} — use write_file to create it."}
+    old = str(args.get("old_string", ""))
+    new = str(args.get("new_string", ""))
+    replace_all = bool(args.get("replace_all", False))
+    if not old:
+        return {"ok": False, "output": "old_string is empty — provide the exact text to replace."}
+    try:
+        text = target.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return {"ok": False, "output": f"Could not read file: {exc}"}
+    count = text.count(old)
+    if count == 0:
+        return {"ok": False, "output": ("old_string not found. Read the file and copy the exact "
+                                        "text to replace, including indentation/whitespace.")}
+    if count > 1 and not replace_all:
+        return {"ok": False, "output": (f"old_string appears {count} times — add surrounding "
+                                        "context to make it unique, or set replace_all=true.")}
+    updated = text.replace(old, new) if replace_all else text.replace(old, new, 1)
+    target.write_text(updated, encoding="utf-8")
+    n = count if replace_all else 1
+    warning = _check_python_syntax(target, updated)
+    return {"ok": True,
+            "output": f"Edited {args.get('path')} ({n} replacement{'' if n == 1 else 's'}).{warning}"}
+
+
+__all__ = ["MAX_READ_BYTES", "read_file", "list_dir", "write_file", "edit_file"]

infrastructure/filesystem/tool_context.py

@@ -0,0 +1,62 @@
+"""ToolContext / ToolError / CancelFn - the sandboxed execution context every
+built-in tool runs against (moved out of ``core/tools.py`` in R05-T02).
+
+Kept as its own leaf module (no dependency on any sibling in this package) so
+``file_tools.py``, ``command_tools.py`` and ``fetch_tools.py`` can each import
+it without creating an import cycle back through ``core/tools.py``, which
+itself re-exports ``ToolContext``/``ToolError`` from here for the existing
+callers (``core/chat_agent.py``, ``core/code_agent.py``,
+``core/task_executors.py``) that do ``from .tools import ToolContext``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+CancelFn = Callable[[], bool]
+
+
+class ToolError(Exception):
+    pass
+
+
+@dataclass
+class ToolContext:
+    workdir: Path
+    flatten_writes: bool = False  # Cowork: force every write into the workdir root
+    sandbox: bool = False  # Code tab: isolate run_command/install_package into <workdir>/.venv
+    # Sandbox Security Layer — Settings' "Resource Limits" (cpu_percent/memory_mb/
+    # disk_mb), applied to every run_command/install_package this context runs.
+    # None (default) = no limits, matching pre-existing behavior.
+    resource_limits: Optional[Dict[str, float]] = None
+    # Sandbox Security Layer — Settings' "Block network for agent commands"
+    # (policy-level, see deps.py::network_blocked_env). False (default) =
+    # unrestricted, matching pre-existing behavior.
+    block_network: bool = False
+    # Whether the fetch_url tool may read URLs — SEPARATE from block_network
+    # (reading a web page/share link for info is safe; running networked shell
+    # commands is the risk). Defaults True; set from agent_security.allow_url_fetch.
+    allow_url_fetch: bool = True
+    # Jira read connector config (base_url/email/api_token) — None disables the
+    # jira_* tools' ability to connect. Populated from config.data["jira"].
+    jira: Optional[Dict[str, Any]] = None
+
+    def resolve(self, rel: str) -> Path:
+        """Resolve ``rel`` inside the workdir, rejecting escapes."""
+        if rel in ("", "."):
+            return self.workdir
+        candidate = (self.workdir / rel).expanduser()
+        try:
+            resolved = candidate.resolve()
+        except OSError as exc:
+            raise ToolError(f"Invalid path: {rel} ({exc})")
+        root = self.workdir.resolve()
+        if resolved != root and root not in resolved.parents:
+            raise ToolError(
+                f"Refused: '{rel}' is outside the working folder ({root})."
+            )
+        return resolved
+
+
+__all__ = ["CancelFn", "ToolError", "ToolContext"]

infrastructure/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server connection lifecycle management (EPIC R05)."""
+
+from .mcp_source_manager import McpToolSourceManager
+
+__all__ = ["McpToolSourceManager"]

infrastructure/mcp/mcp_source_manager.py

@@ -0,0 +1,113 @@
+"""McpToolSourceManager - the MCP server connection lifecycle, extracted out
+of ``state.py::AppContext`` (R05-T05).
+
+Today ``AppContext.build_mcp_tools`` inlines all of this: a ``_mcp_connections``
+dict, a ``_conn_lock`` guarding check-then-create against concurrent turns (a
+Cowork tab, a Co4E flow and a Scheduled Task can all call it at once), and a
+"start it, cache it, skip it on failure" loop repeated for both the
+admin-configured servers AND the built-in MS365 server
+(``_ms365_builtin_connection``). None of that logic touches Qt; it was only
+ever inline because ``AppContext`` is where the config lived.
+
+This class owns the SAME cache/lock/start-or-skip behavior as a standalone,
+directly testable object — ``AppContext`` becomes a thin caller (one instance
+per app, same as it holds one ``RoutingApplicationService``).
+
+Pure Python: no Qt. It DOES touch the network/filesystem via
+``core.mcp_client.McpServerConnection`` (a subprocess + asyncio loop), which is
+exactly what makes it infrastructure rather than domain.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Dict, List, Optional
+
+from cowork_local.core.mcp_client import McpServerConnection
+
+
+class McpToolSourceManager:
+    """Caches and supervises one :class:`McpServerConnection` per server name.
+
+    ``connection_factory`` defaults to ``McpServerConnection`` itself; tests
+    substitute a fake so no real subprocess is spawned (see
+    ``tests/unit/test_mcp_source_manager.py``).
+    """
+
+    def __init__(self, connection_factory=McpServerConnection) -> None:
+        self._connections: Dict[str, McpServerConnection] = {}
+        self._lock = threading.Lock()
+        self._connection_factory = connection_factory
+
+    def ensure(self, name: str, command: str, args: Optional[List[str]] = None,
+               env: Optional[Dict[str, str]] = None) -> Optional[McpServerConnection]:
+        """Return a live connection for ``name``, starting one if there is
+        none cached or the cached one's subprocess has died.
+
+        Serialized under one lock so two turns racing to build their tool
+        list at the same moment share one subprocess per server instead of
+        each spawning their own (the bug this replaces:
+        ``AppContext._conn_lock``'s original docstring). Returns ``None`` -
+        never raises - when the server fails to start, matching the existing
+        "one broken server must not block the turn" behavior.
+        """
+        with self._lock:
+            existing = self._connections.get(name)
+            if existing is not None and existing.is_alive():
+                return existing
+            if existing is not None:
+                self._connections.pop(name, None)
+            connection = self._connection_factory(name, command, args or [], env)
+            try:
+                connection.start()
+            except Exception:  # noqa: BLE001 - one broken server must not block the turn
+                return None
+            self._connections[name] = connection
+            return connection
+
+    def get(self, name: str) -> Optional[McpServerConnection]:
+        """The cached connection for ``name``, without starting one."""
+        return self._connections.get(name)
+
+    def is_alive(self, name: str) -> bool:
+        connection = self._connections.get(name)
+        return connection is not None and connection.is_alive()
+
+    def restart(self, name: str, command: str, args: Optional[List[str]] = None,
+                env: Optional[Dict[str, str]] = None) -> Optional[McpServerConnection]:
+        """Force a fresh connection for ``name`` even if the cached one still
+        looks alive - for a server the caller knows is misbehaving."""
+        with self._lock:
+            self._connections.pop(name, None)
+        return self.ensure(name, command, args, env)
+
+    def stop(self, name: str) -> None:
+        """Stop and forget one connection - used when a server becomes
+        unavailable by configuration (e.g. MS365 signed out) rather than by
+        crashing."""
+        with self._lock:
+            connection = self._connections.pop(name, None)
+        if connection is not None:
+            try:
+                connection.stop()
+            except Exception:  # noqa: BLE001 - shutdown must never raise into the caller
+                pass
+
+    def active(self) -> List[McpServerConnection]:
+        """Every currently cached connection - what
+        ``core/mcp_client.py::build_mcp_tools`` merges tool specs from."""
+        return list(self._connections.values())
+
+    def stop_all(self) -> None:
+        """Terminate every connection's subprocess - called on app shutdown
+        so none of them linger as orphan processes."""
+        with self._lock:
+            connections = list(self._connections.values())
+            self._connections.clear()
+        for connection in connections:
+            try:
+                connection.stop()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+__all__ = ["McpToolSourceManager"]

infrastructure/persistence/__init__.py

@@ -0,0 +1 @@
+"""Persistence adapters (EPIC R02/R06)."""

infrastructure/persistence/json/__init__.py

@@ -0,0 +1,9 @@
+"""JSON-file persistence adapters: crash-safe writes and the workspace/
+conversation/task repositories built on them (EPIC R06, R07)."""
+
+from .atomic_write import write_json
+from .conversation_repository_impl import ConversationRepository
+from .task_repository_impl import TaskRepository
+from .workspace_repository_impl import WorkspaceRepository
+
+__all__ = ["write_json", "WorkspaceRepository", "ConversationRepository", "TaskRepository"]

infrastructure/persistence/json/atomic_write.py

@@ -0,0 +1,56 @@
+"""write_json - crash-safe JSON writes (R06-T02).
+
+``core/projects.py::save_project`` and ``core/history.py``'s
+``save_conversation``/``rename_conversation``/``set_pinned`` all do a plain
+``path.write_text(json.dumps(...))`` today. That is two syscalls with a gap in
+between: a crash, a killed process, or a full disk between the truncate and
+the write leaves a half-written, unparseable JSON file - the NEXT read of
+that project/conversation then fails outright (``load_project`` /
+``load_conversation`` already treat a parse error as "missing", so this isn't
+even a loud failure - a project can silently vanish).
+
+``write_json`` fixes this the standard way: write the full content to a
+temporary file in the SAME directory (so the following replace is on one
+filesystem, not crossing a mount point), then atomically rename it over the
+target. Either the old file is still there, or the new one is fully there -
+never a partial one.
+
+Transitional note: EPIC R02 (Team Nam, ``docs/refactor/Refactoring_Checklist.md``
+R02-T01) plans a shared ``infrastructure/persistence/json/atomic_json_file.py``
+for the SAME purpose across the whole app (config, secrets, ...). This module
+is deliberately named differently and scoped to R06's two repositories only,
+so the two EPICs don't edit the same file in parallel; once R02-T01 lands,
+``WorkspaceRepository``/``ConversationRepository`` should switch to it and
+this module can go away.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def write_json(path: Path, data: Any) -> None:
+    """Serialize ``data`` as indented UTF-8 JSON and write it to ``path``
+    atomically. Creates parent directories if needed."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(data, ensure_ascii=False, indent=2)
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, path)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+__all__ = ["write_json"]

infrastructure/persistence/json/conversation_repository_impl.py

@@ -0,0 +1,54 @@
+"""ConversationRepository - an object-shaped, atomic-write-backed facade over
+``core/history.py`` (R06-T02). Same rationale as
+``workspace_repository_impl.py``: the module-level functions in
+``core/history.py`` are still what production code calls (they now write
+atomically themselves), this class is the seam for application-layer code
+that wants an object instead of a directory-parameterised function.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from cowork_local.config import HISTORY_DIR
+from cowork_local.core.history import (
+    delete_conversation,
+    list_conversations,
+    load_conversation,
+    new_session_id,
+    rename_conversation,
+    save_conversation,
+    set_pinned,
+)
+
+
+class ConversationRepository:
+    """CRUD + search over conversation JSON files, scoped to one
+    ``directory`` (defaults to the app's real ``HISTORY_DIR``)."""
+
+    def __init__(self, directory: Optional[Path] = None) -> None:
+        self._directory = Path(directory) if directory is not None else HISTORY_DIR
+
+    def new_session_id(self) -> str:
+        return new_session_id()
+
+    def save(self, kind: str, session_id: str, messages: List[Dict[str, Any]], **kwargs) -> Path:
+        return save_conversation(self._directory, kind, session_id, messages, **kwargs)
+
+    def load(self, path: Path) -> Dict[str, Any]:
+        return load_conversation(path)
+
+    def list(self, query: str = "") -> List[Dict[str, Any]]:
+        return list_conversations(self._directory, query)
+
+    def delete(self, path: Path) -> None:
+        delete_conversation(path)
+
+    def rename(self, path: Path, new_title: str) -> None:
+        rename_conversation(path, new_title)
+
+    def set_pinned(self, path: Path, pinned: bool) -> None:
+        set_pinned(path, pinned)
+
+
+__all__ = ["ConversationRepository"]

infrastructure/persistence/json/task_repository_impl.py

@@ -0,0 +1,63 @@
+"""TaskRepository - an object-shaped, atomic-write-backed facade over
+``core/tasks.py`` (R07-T01).
+
+``core/tasks.py``'s module-level functions (``list_tasks``, ``load_task``,
+``save_task``, ``delete_task``, ``new_task``, ``duplicate_task``) are still
+what every existing call site (``core/task_scheduler.py``,
+``core/task_executors.py``, ``ui/schedule_task_tab.py``) uses, and stay that
+way - ``save_task`` now writes through :func:`atomic_write.write_json`
+itself (R07-T01, same class of durability fix already applied to
+``core/projects.py``/``core/history.py`` at R06-T02), so the fix applies
+whether or not a caller ever touches this class.
+
+This repository exists for the application layer
+(``application/scheduling``, R07-T04) to depend on an interface instead of
+reaching into ``core/`` directly. It is a thin pass-through today, not a
+re-implementation: same on-disk format, same directory, same functions
+underneath.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from cowork_local.core.tasks import (
+    TASKS_DIR,
+    delete_task,
+    duplicate_task,
+    list_tasks,
+    load_task,
+    new_task,
+    save_task,
+)
+
+
+class TaskRepository:
+    """CRUD over task dicts (see ``core/tasks.py::DEFAULT_TASK`` for shape),
+    scoped to one ``directory`` (defaults to the app's real ``TASKS_DIR``;
+    tests pass a ``tmp_path`` so nothing touches the user's real config
+    folder)."""
+
+    def __init__(self, directory: Optional[Path] = None) -> None:
+        self._directory = directory or TASKS_DIR
+
+    def list(self) -> List[Dict[str, Any]]:
+        return list_tasks(self._directory)
+
+    def get(self, task_id: str) -> Optional[Dict[str, Any]]:
+        return load_task(task_id, self._directory)
+
+    def save(self, task: Dict[str, Any]) -> Path:
+        return save_task(task, self._directory)
+
+    def create(self, title: str = "", **overrides: Any) -> Dict[str, Any]:
+        return new_task(title, **overrides)
+
+    def duplicate(self, task: Dict[str, Any]) -> Dict[str, Any]:
+        return duplicate_task(task)
+
+    def delete(self, task_id: str) -> None:
+        delete_task(task_id, self._directory)
+
+
+__all__ = ["TaskRepository"]

infrastructure/persistence/json/workspace_repository_impl.py

@@ -0,0 +1,59 @@
+"""WorkspaceRepository - an object-shaped, atomic-write-backed facade over
+``core/projects.py`` (R06-T02).
+
+``core/projects.py``'s module-level functions (``list_projects``,
+``load_project``, ``save_project``, ``new_project``, ``delete_project``) are
+still what every existing call site (``ui/workspace_tab.py``, ``state.py``,
+task executors) uses, and stay that way - they now write through
+:func:`atomic_write.write_json` themselves, so the durability fix applies
+whether or not a caller ever touches this class.
+
+This repository exists for the application layer (``application/workspaces``,
+R06-T05) to depend on an interface instead of reaching into ``core/`` -
+useful once code above ``core/`` starts being written against
+``domain``/``application`` seams instead of the legacy module functions. It
+is a thin pass-through today, not a re-implementation: same on-disk format,
+same directory, same functions underneath.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from cowork_local.core.projects import (
+    PROJECTS_DIR,
+    Project,
+    delete_project,
+    list_projects,
+    load_project,
+    new_project,
+    save_project,
+)
+
+
+class WorkspaceRepository:
+    """CRUD over :class:`~cowork_local.core.projects.Project`, scoped to one
+    ``directory`` (defaults to the app's real ``PROJECTS_DIR``; tests pass a
+    ``tmp_path`` so nothing touches the user's real config folder)."""
+
+    def __init__(self, directory: Optional[Path] = None) -> None:
+        self._directory = directory or PROJECTS_DIR
+
+    def list(self) -> List[Project]:
+        return list_projects(self._directory)
+
+    def get(self, project_id: str) -> Optional[Project]:
+        return load_project(project_id, self._directory)
+
+    def save(self, project: Project) -> Path:
+        return save_project(project, self._directory)
+
+    def create(self, name: str, description: str = "", instructions: str = "",
+               output_dir: str = "") -> Project:
+        return new_project(name, description, instructions, output_dir, self._directory)
+
+    def delete(self, project_id: str) -> bool:
+        return delete_project(project_id, self._directory)
+
+
+__all__ = ["WorkspaceRepository"]

infrastructure/providers/__init__.py

@@ -0,0 +1,5 @@
+"""Provider adapters and the central provider catalogue (EPIC R03)."""
+
+from .provider_registry import ProviderRegistry, default_registry
+
+__all__ = ["ProviderRegistry", "default_registry"]

infrastructure/providers/provider_registry.py

@@ -0,0 +1,207 @@
+"""ProviderRegistry - the one place a provider is declared (R03-T02).
+
+Replaces the three-way split between ``providers/factory.py::_REGISTRY``,
+``config.py::DEFAULT_CONFIG["providers"]`` and ``config.py::PROVIDER_LABELS``
+with a single catalogue of :class:`ProviderDescriptor` objects plus the
+implementation class each one maps to.
+
+Adding a provider is now one entry in :data:`BUILT_IN_PROVIDERS` (declarative
+facts) and one line in :data:`_IMPLEMENTATIONS` (which class speaks that
+protocol) - see ``docs/governance/contributor-recipes.md`` (R10-T04).
+
+Migration note (strangler fig, ADR-001 section 4): this registry does not
+re-implement any provider. It builds the SAME classes ``providers/factory.py``
+builds, so both entry points stay behaviourally identical while call sites move
+over one at a time.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from cowork_local.domain.models.provider_descriptor import (
+    ProviderCapability,
+    ProviderDescriptor,
+)
+from cowork_local.providers.base import Provider, ProviderError
+
+_CAP = ProviderCapability
+
+# Every provider the app ships with, described once.
+#
+# The capability sets are deliberately conservative: a capability listed here is
+# one the adapter genuinely implements today. Claiming VISION for a provider
+# whose chat() cannot translate an image block would route an image turn into a
+# guaranteed failure, so an unimplemented capability must stay off the list.
+BUILT_IN_PROVIDERS: tuple = (
+    ProviderDescriptor(
+        id="openai_compat",
+        label="OpenAI-compatible (Internal Gateway)",
+        protocol="openai_compat",
+        default_model="gpt-4o-mini",
+        capabilities=frozenset({_CAP.STREAMING, _CAP.TOOLS, _CAP.VISION,
+                                _CAP.REASONING, _CAP.MODEL_LISTING}),
+        notes="Any endpoint speaking the OpenAI Chat Completions protocol.",
+    ),
+    ProviderDescriptor(
+        id="anthropic",
+        label="Anthropic Claude",
+        protocol="anthropic",
+        default_model="claude-sonnet-4-6",
+        capabilities=frozenset({_CAP.STREAMING, _CAP.TOOLS, _CAP.VISION,
+                                _CAP.MODEL_LISTING}),
+    ),
+    ProviderDescriptor(
+        id="ollama",
+        label="Ollama (local models)",
+        protocol="openai_compat",
+        default_model="llama3.1",
+        capabilities=frozenset({_CAP.STREAMING, _CAP.TOOLS, _CAP.REASONING,
+                                _CAP.MODEL_LISTING}),
+        # Ollama ignores the key, but the OpenAI client layer requires a value,
+        # so the default config ships a placeholder rather than an empty string.
+        requires_api_key=False,
+        local=True,
+        notes="Runs on this machine - no data leaves the device, no token cost.",
+    ),
+    ProviderDescriptor(
+        id="github_copilot",
+        label="GitHub Copilot",
+        protocol="openai_compat",
+        default_model="gpt-4o",
+        capabilities=frozenset({_CAP.STREAMING, _CAP.TOOLS, _CAP.MODEL_LISTING}),
+        notes="Paste a Copilot token as the API key.",
+    ),
+    ProviderDescriptor(
+        id="codex",
+        label="OpenAI (Codex / GPT)",
+        protocol="openai_compat",
+        default_model="gpt-4o-mini",
+        capabilities=frozenset({_CAP.STREAMING, _CAP.TOOLS, _CAP.VISION,
+                                _CAP.REASONING, _CAP.MODEL_LISTING}),
+    ),
+)
+
+
+def _implementations() -> Dict[str, type]:
+    """Protocol -> adapter class.
+
+    Imported lazily inside the function because ``providers/anthropic.py`` and
+    ``providers/openai_compat.py`` pull in ``requests`` at import time; keeping
+    that out of module import means a test that only inspects descriptors pays
+    no import cost at all.
+    """
+    from cowork_local.providers.anthropic import AnthropicProvider
+    from cowork_local.providers.openai_compat import OpenAICompatProvider
+
+    return {
+        "openai_compat": OpenAICompatProvider,
+        "anthropic": AnthropicProvider,
+    }
+
+
+class ProviderRegistry:
+    """Catalogue of known providers + the factory that instantiates them.
+
+    Intentionally holds no config and no app context: it is a pure lookup table
+    plus a build step, so it can be constructed in a test with a custom
+    descriptor list and no application running.
+    """
+
+    def __init__(self, descriptors: Optional[Iterable[ProviderDescriptor]] = None) -> None:
+        # Dict preserves declaration order (Python 3.7+), which is the order
+        # Settings lists providers in - so the catalogue order is data, not luck.
+        self._by_id: Dict[str, ProviderDescriptor] = {
+            d.id: d for d in (descriptors if descriptors is not None else BUILT_IN_PROVIDERS)
+        }
+
+    # -- catalogue queries ------------------------------------------------ #
+    def ids(self) -> List[str]:
+        """Known provider ids, in declaration order."""
+        return list(self._by_id)
+
+    def all(self) -> List[ProviderDescriptor]:
+        """Every descriptor, in declaration order."""
+        return list(self._by_id.values())
+
+    def get(self, provider_id: str) -> Optional[ProviderDescriptor]:
+        """The descriptor for ``provider_id``, or None when unknown.
+
+        Returns None rather than raising because the caller is often reacting to
+        a config file that may name a provider from a newer version; the UI
+        should be able to skip it, not crash.
+        """
+        return self._by_id.get(provider_id)
+
+    def require(self, provider_id: str) -> ProviderDescriptor:
+        """Like :meth:`get` but raises :class:`ProviderError` when unknown.
+
+        Same error type ``providers/factory.py::build_provider`` already raises,
+        so callers that migrate to the registry keep their existing except clause.
+        """
+        descriptor = self._by_id.get(provider_id)
+        if descriptor is None:
+            known = ", ".join(self._by_id) or "(none)"
+            raise ProviderError(f"Unsupported provider: {provider_id} (known: {known})")
+        return descriptor
+
+    def labels(self) -> Dict[str, str]:
+        """``{id: label}`` - the drop-in replacement for ``config.PROVIDER_LABELS``."""
+        return {d.id: d.label for d in self._by_id.values()}
+
+    def supporting(self, capability: ProviderCapability) -> List[ProviderDescriptor]:
+        """Every descriptor advertising ``capability`` - used to answer "which
+        providers could serve this turn?" before any of them is built."""
+        return [d for d in self._by_id.values() if d.supports(capability)]
+
+    def configured(self, providers_conf: Mapping[str, Mapping[str, Any]]
+                   ) -> List[ProviderDescriptor]:
+        """Descriptors whose config section is complete enough to actually call.
+
+        ``providers_conf`` is ``AppConfig.data["providers"]``. Passing the raw
+        mapping (not the AppConfig object) keeps this layer independent of the
+        config implementation, which EPIC R02 is rewriting in parallel.
+        """
+        return [d for d in self._by_id.values()
+                if d.is_configured(providers_conf.get(d.id, {}) or {})]
+
+    # -- construction ----------------------------------------------------- #
+    def build(self, provider_id: str, conf: Mapping[str, Any],
+              model: str = "") -> Provider:
+        """Instantiate the adapter for ``provider_id``.
+
+        ``model`` overrides the configured model for this instance only - that is
+        how the routing layer runs one turn on a different model without mutating
+        the user's saved settings.
+        """
+        descriptor = self.require(provider_id)
+        impl = _implementations().get(descriptor.protocol)
+        if impl is None:  # pragma: no cover - only reachable via a bad descriptor
+            raise ProviderError(
+                f"Provider '{provider_id}' declares unknown protocol "
+                f"'{descriptor.protocol}'."
+            )
+        # Copy before mutating: conf is the caller's live config dict, and
+        # writing the routed model into it would silently change the user's
+        # saved default for every later turn.
+        resolved = dict(conf or {})
+        resolved["model"] = descriptor.resolve_model(conf, model)
+        instance = impl(resolved)
+        # The adapter class is shared by several ids (three of them are
+        # OpenAI-compatible), so its class-level `name` cannot identify which
+        # provider this is. Stamping the instance keeps usage records, audit
+        # entries and routing candidate keys attributed to the right provider.
+        instance.name = descriptor.id
+        return instance
+
+    def describe(self, provider_id: str, conf: Optional[Mapping[str, Any]] = None) -> str:
+        """One-line description used in logs and error messages."""
+        return self.require(provider_id).describe(conf)
+
+
+# Shared default instance. Callers that need the built-in catalogue use this
+# instead of constructing a registry each time; tests build their own with an
+# explicit descriptor list.
+default_registry = ProviderRegistry()
+
+
+__all__ = ["ProviderRegistry", "BUILT_IN_PROVIDERS", "default_registry"]

infrastructure/qt/__init__.py

@@ -0,0 +1,18 @@
+"""Qt-backed adapters for pure interfaces used elsewhere in the app (EPIC R07).
+
+Note: the original plan (``docs/refactor/Feature_Architecture_Proposal.md``)
+placed this adapter at a new top-level ``platform/qt/`` package. That name
+was dropped after it was shown to actually shadow the stdlib ``platform``
+module (used by ``core/windows_sandbox_vm.py``/``core/appcontainer_sandbox.
+py``) whenever the repo root ends up on ``sys.path`` directly - e.g. running
+``python -c "..."`` (or any script) with the repo root as the working
+directory, which resolves a bare ``import platform`` to this package instead
+of the standard library one. ``infrastructure/`` already exists as a layer
+for exactly this kind of toolkit-specific implementation
+(``infrastructure/filesystem/``, ``infrastructure/mcp/``, ...), so the
+adapter lives here instead - same content, safer location.
+"""
+
+from .qt_scheduler_clock import QtSchedulerClock
+
+__all__ = ["QtSchedulerClock"]

infrastructure/qt/qt_scheduler_clock.py

@@ -0,0 +1,70 @@
+"""QtSchedulerClock - the ``QTimer``-backed periodic ticker `TaskScheduler`
+needs, pulled out from ``core/task_scheduler.py`` into its own adapter
+(R07-T03).
+
+``core/task_scheduler.py::TaskScheduler`` is the only file in the scheduling
+stack that imports Qt at all (confirmed by grep — ``core/tasks.py`` and
+``core/task_executors.py`` are Qt-free). Everything it needs Qt FOR is small
+and mechanical: an interval timer that calls back into ``tick()`` every
+``TICK_MS``, plus, during ``stop()``, a way to pump the event loop so a
+worker thread's queued ``finished_ok``/``failed`` signal still gets delivered
+while draining running tasks (see the long comment on ``TaskScheduler.stop()``
+for why that pump matters).
+
+Wrapping exactly that surface — ``start(interval_ms, callback)``, ``stop()``,
+``pump()`` — behind :class:`QtSchedulerClock` lets ``TaskScheduler`` take a
+clock as a constructor parameter instead of constructing a ``QTimer``
+itself. Production wiring is unchanged (``TaskScheduler`` defaults to a real
+``QtSchedulerClock`` when no clock is passed); tests can inject
+``tests/fakes/fake_clock.py::FakeClock`` to control ticks by hand with no Qt
+event loop running at all.
+
+See ``infrastructure/qt/__init__.py`` for why this lives under
+``infrastructure/qt/`` and not the ``platform/qt/`` path the original plan
+named.
+"""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from PySide6.QtCore import QCoreApplication, QObject, QTimer
+
+
+class QtSchedulerClock:
+    """Owns one ``QTimer``. Not itself a ``QObject`` subclass — it OWNS a
+    ``QObject``-parented timer instead of inheriting from one, so callers
+    (like ``FakeClock`` in tests) can satisfy the same duck-typed interface
+    without any Qt base class at all."""
+
+    def __init__(self, parent: Optional[QObject] = None) -> None:
+        # Parented so the timer is torn down with its owner instead of
+        # outliving it — the same lifetime QTimer(self) gave it inside
+        # TaskScheduler before this extraction.
+        self._timer = QTimer(parent)
+        self._timer.timeout.connect(self._on_timeout)
+        self._callback: Optional[Callable[[], None]] = None
+
+    def _on_timeout(self) -> None:
+        if self._callback is not None:
+            self._callback()
+
+    def start(self, interval_ms: int, callback: Callable[[], None]) -> None:
+        """Arm and start the timer. Calling this again while already
+        running re-arms it with the new interval/callback (matches
+        ``QTimer.start()``'s own restart-on-repeat-call behaviour)."""
+        self._callback = callback
+        self._timer.setInterval(interval_ms)
+        self._timer.start()
+
+    def stop(self) -> None:
+        self._timer.stop()
+
+    def pump(self) -> None:
+        """Process one batch of pending Qt events — used by
+        ``TaskScheduler.stop()``'s bounded drain loop so a worker thread's
+        queued completion signal can still be delivered while we wait for it
+        to exit."""
+        QCoreApplication.processEvents()
+
+
+__all__ = ["QtSchedulerClock"]

infrastructure/telemetry/__init__.py

@@ -0,0 +1,21 @@
+"""Telemetry sinks: where token usage and turn metrics are recorded (EPIC R03)."""
+
+from .usage_sink import (
+    NullUsageSink,
+    RecordingUsageSink,
+    UsageEvent,
+    UsageEventSink,
+    UsageTrackerSink,
+    default_sink,
+    set_default_sink,
+)
+
+__all__ = [
+    "UsageEvent",
+    "UsageEventSink",
+    "UsageTrackerSink",
+    "NullUsageSink",
+    "RecordingUsageSink",
+    "default_sink",
+    "set_default_sink",
+]

infrastructure/telemetry/usage_sink.py

@@ -0,0 +1,229 @@
+"""UsageEventSink - where a turn's token usage goes (R03-T06).
+
+Today each provider records its own usage inline, in the middle of the streaming
+loop::
+
+    # providers/openai_compat.py
+    def _record_usage(self, messages, text_parts, tool_acc, usage_seen):
+        from ..core import usage_tracker as ut
+        ...
+        ut.record(self.name, self.model, ...)
+
+Three problems with that shape:
+
+1. **Hidden side effect.** ``chat()`` looks like a pure request/response call but
+   also writes to the Dashboard's store, so a test of a provider silently
+   appends rows to the developer's real usage history.
+2. **Duplicated estimation.** The "no usage block from the server, so estimate
+   at ~4 chars/token" fallback is copy-pasted per provider and can drift.
+3. **One hard-wired destination.** Usage can only ever go to
+   ``core.usage_tracker``; a run that wants to bill a workflow, or a test that
+   wants to assert on token counts, has nowhere to plug in.
+
+This module introduces the seam: providers build a :class:`UsageEvent` and hand
+it to a :class:`UsageEventSink`. Production wires :class:`UsageTrackerSink`
+(same destination, same numbers as before); tests wire
+:class:`RecordingUsageSink` or :class:`NullUsageSink`.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Protocol, Sequence
+
+logger = logging.getLogger("cowork_local.telemetry")
+
+# Rough characters-per-token ratio used when the gateway sends no usage block.
+# Matches the constant behaviour of ``core.usage_tracker.estimate_tokens`` so
+# moving the estimation here does not change a single recorded number.
+_CHARS_PER_TOKEN = 4
+
+
+@dataclass(frozen=True)
+class UsageEvent:
+    """Token usage for exactly one provider round trip.
+
+    ``estimated`` marks a record derived from text length rather than reported by
+    the server. The Dashboard shows the two differently, and conflating them
+    would make cost figures look more precise than they are.
+    """
+
+    provider: str
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cached_tokens: int = 0
+    estimated: bool = False
+
+    @property
+    def total_tokens(self) -> int:
+        """Input + output. Cached tokens are a subset of input, not an addition,
+        so adding them here would double-count a cache hit."""
+        return self.input_tokens + self.output_tokens
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe projection for logs and for sinks that persist raw events."""
+        return {
+            "provider": self.provider,
+            "model": self.model,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cached_tokens": self.cached_tokens,
+            "estimated": self.estimated,
+        }
+
+
+class UsageEventSink(Protocol):
+    """Anything that can absorb a :class:`UsageEvent`.
+
+    Implementations MUST NOT raise: telemetry is observability, and a failure to
+    record usage must never abort the turn that produced it.
+    """
+
+    def record(self, event: UsageEvent) -> None:
+        """Absorb one usage event."""
+
+
+class NullUsageSink:
+    """Discards everything. The default for tests and headless tooling, so a
+    unit test never writes into the developer's real usage history."""
+
+    def record(self, event: UsageEvent) -> None:  # noqa: D102 - see protocol
+        return None
+
+
+class RecordingUsageSink:
+    """Keeps events in memory so a test can assert on what was recorded."""
+
+    def __init__(self) -> None:
+        self.events: List[UsageEvent] = []
+
+    def record(self, event: UsageEvent) -> None:  # noqa: D102 - see protocol
+        self.events.append(event)
+
+    @property
+    def total_tokens(self) -> int:
+        """Sum across every recorded event."""
+        return sum(e.total_tokens for e in self.events)
+
+
+class UsageTrackerSink:
+    """Forwards to ``core.usage_tracker`` - the Dashboard's store.
+
+    This is the production sink and the only place that still knows about the
+    legacy tracker module, which is what lets EPIC R10 replace the storage
+    without touching a single provider.
+    """
+
+    def __init__(self, tracker: Optional[Any] = None) -> None:
+        # Injectable for tests; imported lazily otherwise because the tracker
+        # touches the config directory at import time.
+        self._tracker = tracker
+
+    def _resolve(self) -> Any:
+        if self._tracker is None:
+            from cowork_local.core import usage_tracker
+
+            self._tracker = usage_tracker
+        return self._tracker
+
+    def record(self, event: UsageEvent) -> None:
+        """Write the event to the usage tracker, swallowing any failure.
+
+        The bare except mirrors the behaviour this replaces (each provider
+        already wrapped its ``ut.record`` call in ``try/except: pass``) but logs
+        at debug level instead of discarding the reason entirely, so a broken
+        Dashboard store can at least be diagnosed.
+        """
+        try:
+            self._resolve().record(
+                event.provider, event.model,
+                event.input_tokens, event.output_tokens, event.cached_tokens,
+                estimated=event.estimated,
+            )
+        except Exception:  # noqa: BLE001 - telemetry must never break a turn
+            logger.debug("usage sink: failed to record %s", event.to_dict(), exc_info=True)
+
+
+def estimate_tokens(text: str) -> int:
+    """Approximate token count for ``text`` (~4 characters per token).
+
+    Deliberately identical to ``core.usage_tracker.estimate_tokens`` so that
+    moving estimation into this layer changes no recorded number. Duplicated
+    rather than imported to keep this module free of the legacy dependency;
+    :class:`UsageTrackerSink` is the only bridge back to it.
+    """
+    return max(0, len(text or "") // _CHARS_PER_TOKEN)
+
+
+def estimated_event(provider: str, model: str, sent: str, received: str) -> UsageEvent:
+    """Build an estimated :class:`UsageEvent` from the raw text of a round trip.
+
+    Used when the gateway sends no usage block - most self-hosted OpenAI-compatible
+    servers and Ollama do not.
+    """
+    return UsageEvent(
+        provider=provider, model=model,
+        input_tokens=estimate_tokens(sent),
+        output_tokens=estimate_tokens(received),
+        cached_tokens=0,
+        estimated=True,
+    )
+
+
+def openai_usage_event(provider: str, model: str, usage: Dict[str, Any]) -> UsageEvent:
+    """Build a reported :class:`UsageEvent` from an OpenAI-style usage block."""
+    details = usage.get("prompt_tokens_details") or {}
+    return UsageEvent(
+        provider=provider, model=model,
+        input_tokens=int(usage.get("prompt_tokens", 0) or 0),
+        output_tokens=int(usage.get("completion_tokens", 0) or 0),
+        cached_tokens=int(details.get("cached_tokens", 0) or 0),
+        estimated=False,
+    )
+
+
+def anthropic_usage_event(provider: str, model: str, usage: Dict[str, Any]) -> UsageEvent:
+    """Build a reported :class:`UsageEvent` from Anthropic's usage accumulator.
+
+    Anthropic reports input tokens on ``message_start`` and output tokens on
+    ``message_delta``, so ``providers/anthropic.py`` accumulates them into a dict
+    keyed ``in``/``out``/``cache`` - this reads that shape.
+    """
+    return UsageEvent(
+        provider=provider, model=model,
+        input_tokens=int(usage.get("in", 0) or 0),
+        output_tokens=int(usage.get("out", 0) or 0),
+        cached_tokens=int(usage.get("cache", 0) or 0),
+        estimated=False,
+    )
+
+
+# The sink providers use unless one is injected. A module-level default keeps
+# the change to the provider classes to a single attribute, and lets a test swap
+# the destination process-wide with one monkeypatch.
+default_sink: UsageEventSink = UsageTrackerSink()
+
+
+def set_default_sink(sink: UsageEventSink) -> UsageEventSink:
+    """Replace the process-wide default sink; returns the previous one so a
+    caller (or fixture) can restore it."""
+    global default_sink
+    previous = default_sink
+    default_sink = sink
+    return previous
+
+
+__all__ = [
+    "UsageEvent",
+    "UsageEventSink",
+    "UsageTrackerSink",
+    "NullUsageSink",
+    "RecordingUsageSink",
+    "estimate_tokens",
+    "estimated_event",
+    "openai_usage_event",
+    "anthropic_usage_event",
+    "default_sink",
+    "set_default_sink",
+]

mcp_servers/project_context/__init__.py

@@ -1,5 +0,0 @@
-"""Provider-neutral Project Context MCP server template."""
-
-from .server import build_server, dispatch
-
-__all__ = ["build_server", "dispatch"]

mcp_servers/project_context/foundation.py

@@ -1,106 +0,0 @@
-"""Shared, stable boundary used by all Project Context tool work packages."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Any, Protocol
-
-from pydantic import AnyUrl, BaseModel, ConfigDict, Field
-
-
-class ContractModel(BaseModel):
-    """Strict immutable model so provider-specific fields cannot leak to the Agent."""
-
-    model_config = ConfigDict(extra="forbid", frozen=True)
-
-
-class IdentityContext(ContractModel):
-    actor_id: str = Field(min_length=1, max_length=256)
-    org_unit: str = Field(min_length=1, max_length=128)
-    customer: str = Field(min_length=1, max_length=128)
-    project: str = Field(min_length=1, max_length=128)
-    granted_scopes: frozenset[str]
-
-
-class SourceCitation(ContractModel):
-    system: str = Field(min_length=1, max_length=64)
-    url: AnyUrl
-    revision: str = Field(min_length=1, max_length=256)
-    retrieved_at: datetime
-
-
-@dataclass(frozen=True)
-class DispatchResult:
-    ok: bool
-    payload: dict[str, Any]
-
-
-class PolicyDecisionPoint(Protocol):
-    def decide(self, identity: IdentityContext, tool_name: str, project_id: str) -> bool: ...
-
-
-class CredentialResolver(Protocol):
-    def resolve(self, identity: IdentityContext, tool_name: str) -> Any: ...
-
-
-@dataclass(frozen=True)
-class ProjectContextRuntime:
-    identity: IdentityContext
-    policy: PolicyDecisionPoint
-    credential_resolver: CredentialResolver
-
-
-class ProviderError(RuntimeError):
-    """A provider failure with a caller-safe message and retry classification."""
-
-    def __init__(self, code: str, message: str, *, retryable: bool) -> None:
-        super().__init__(message)
-        self.code = code
-        self.safe_message = message
-        self.retryable = retryable
-
-
-ToolHandler = Callable[[ContractModel, Any], dict[str, Any]]
-
-
-@dataclass(frozen=True)
-class ToolTemplate:
-    name: str
-    description: str
-    input_model: type[ContractModel]
-    output_model: type[ContractModel]
-    handler: ToolHandler
-
-    def declaration(self) -> dict[str, Any]:
-        return {
-            "name": self.name,
-            "description": self.description,
-            "inputSchema": self.input_model.model_json_schema(),
-            "outputSchema": self.output_model.model_json_schema(),
-        }
-
-
-def error_result(
-    code: str,
-    *,
-    category: str,
-    retryable: bool,
-    message: str,
-    suggested_action: str,
-    correlation_id: str,
-) -> DispatchResult:
-    return DispatchResult(
-        ok=False,
-        payload={
-            "error": {
-                "code": code,
-                "category": category,
-                "retryable": retryable,
-                "message": message,
-                "suggested_action": suggested_action,
-                "correlation_id": correlation_id,
-            }
-        },
-    )

mcp_servers/project_context/providers/__init__.py

@@ -1 +0,0 @@
-"""One provider module per member-owned tool work package."""

mcp_servers/project_context/providers/change.py

@@ -1,25 +0,0 @@
-"""Provider boundary owned with get_project_change_context."""
-
-from __future__ import annotations
-
-from typing import Any, Protocol
-
-from ..foundation import IdentityContext, ProviderError
-
-
-class ChangeProvider(Protocol):
-    def get_change_context(self, **arguments: Any) -> dict[str, Any]: ...
-
-
-class UnconfiguredChangeProvider:
-    def get_change_context(self, **arguments: Any) -> dict[str, Any]:
-        raise ProviderError(
-            "UNAVAILABLE",
-            "The change provider is not configured for this environment.",
-            retryable=False,
-        )
-
-
-def build_provider(identity: IdentityContext) -> ChangeProvider:
-    """Replace only this factory when wiring the approved read-only Git adapter."""
-    return UnconfiguredChangeProvider()

mcp_servers/project_context/providers/issue.py

@@ -1,25 +0,0 @@
-"""Provider boundary owned with get_project_issue_context."""
-
-from __future__ import annotations
-
-from typing import Any, Protocol
-
-from ..foundation import IdentityContext, ProviderError
-
-
-class IssueProvider(Protocol):
-    def get_issue_context(self, **arguments: Any) -> dict[str, Any]: ...
-
-
-class UnconfiguredIssueProvider:
-    def get_issue_context(self, **arguments: Any) -> dict[str, Any]:
-        raise ProviderError(
-            "UNAVAILABLE",
-            "The issue provider is not configured for this environment.",
-            retryable=False,
-        )
-
-
-def build_provider(identity: IdentityContext) -> IssueProvider:
-    """Replace only this factory when wiring the approved read-only issue adapter."""
-    return UnconfiguredIssueProvider()

mcp_servers/project_context/providers/knowledge.py

@@ -1,25 +0,0 @@
-"""Provider boundary owned with search_project_knowledge."""
-
-from __future__ import annotations
-
-from typing import Any, Protocol
-
-from ..foundation import IdentityContext, ProviderError
-
-
-class KnowledgeProvider(Protocol):
-    def search_knowledge(self, **arguments: Any) -> dict[str, Any]: ...
-
-
-class UnconfiguredKnowledgeProvider:
-    def search_knowledge(self, **arguments: Any) -> dict[str, Any]:
-        raise ProviderError(
-            "UNAVAILABLE",
-            "The knowledge provider is not configured for this environment.",
-            retryable=False,
-        )
-
-
-def build_provider(identity: IdentityContext) -> KnowledgeProvider:
-    """Replace only this factory when wiring approved project retrieval."""
-    return UnconfiguredKnowledgeProvider()

mcp_servers/project_context/registry.py

@@ -1,23 +0,0 @@
-"""Immutable registry composed before member work starts to prevent merge conflicts."""
-
-from __future__ import annotations
-
-from types import MappingProxyType
-from typing import Any
-
-from .foundation import ToolTemplate
-from .tools.change_context import TOOL as CHANGE_CONTEXT_TOOL
-from .tools.issue_context import TOOL as ISSUE_CONTEXT_TOOL
-from .tools.knowledge_search import TOOL as KNOWLEDGE_SEARCH_TOOL
-
-TOOLS: tuple[ToolTemplate, ...] = (
-    ISSUE_CONTEXT_TOOL,
-    KNOWLEDGE_SEARCH_TOOL,
-    CHANGE_CONTEXT_TOOL,
-)
-TOOLS_BY_NAME = MappingProxyType({tool.name: tool for tool in TOOLS})
-TOOL_NAMES = tuple(tool.name for tool in TOOLS)
-
-
-def tool_declarations() -> list[dict[str, Any]]:
-    return [tool.declaration() for tool in TOOLS]

mcp_servers/project_context/runtime.py

@@ -1,74 +0,0 @@
-"""Fail-closed identity, policy, and provider resolution for the template server."""
-
-from __future__ import annotations
-
-import os
-import sys
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Any
-
-from .foundation import IdentityContext, ProjectContextRuntime, ProviderError
-from .providers.change import build_provider as build_change_provider
-from .providers.issue import build_provider as build_issue_provider
-from .providers.knowledge import build_provider as build_knowledge_provider
-
-MINIMUM_PYTHON = (3, 11)
-
-
-def require_supported_python(version_info: tuple[int, ...] | None = None) -> None:
-    """Fail with an actionable message before the MCP server starts."""
-    current = version_info or tuple(sys.version_info[:3])
-    if current[:2] < MINIMUM_PYTHON:
-        raise RuntimeError(
-            "Project Context MCP requires Python 3.11 or newer; "
-            f"current runtime is {current[0]}.{current[1]}"
-        )
-
-
-@dataclass(frozen=True)
-class ProjectScopePolicy:
-    """Pilot policy: read scope and exact identity-bound project are both mandatory."""
-
-    def decide(self, identity: IdentityContext, tool_name: str, project_id: str) -> bool:
-        return "read" in identity.granted_scopes and project_id == identity.project
-
-
-PROVIDER_FACTORIES: dict[str, Callable[[IdentityContext], Any]] = {
-    "get_project_issue_context": build_issue_provider,
-    "search_project_knowledge": build_knowledge_provider,
-    "get_project_change_context": build_change_provider,
-}
-
-
-@dataclass(frozen=True)
-class ProjectProviderResolver:
-    def resolve(self, identity: IdentityContext, tool_name: str) -> Any:
-        factory = PROVIDER_FACTORIES.get(tool_name)
-        if factory is None:
-            raise ProviderError("NOT_FOUND", "The requested tool is not registered.", retryable=False)
-        return factory(identity)
-
-
-def _required_environment(name: str) -> str:
-    value = os.environ.get(name, "").strip()
-    if not value:
-        raise RuntimeError(f"Project Context MCP cannot start: required setting {name} is missing")
-    return value
-
-
-def default_runtime() -> ProjectContextRuntime:
-    """Build immutable runtime state; missing identity configuration fails at boot."""
-    require_supported_python()
-    identity = IdentityContext(
-        actor_id=_required_environment("COWORK_MCP_ACTOR_ID"),
-        org_unit=_required_environment("COWORK_MCP_ORG_UNIT"),
-        customer=_required_environment("COWORK_MCP_CUSTOMER"),
-        project=_required_environment("COWORK_MCP_PROJECT"),
-        granted_scopes=frozenset({"read"}),
-    )
-    return ProjectContextRuntime(
-        identity=identity,
-        policy=ProjectScopePolicy(),
-        credential_resolver=ProjectProviderResolver(),
-    )

mcp_servers/project_context/server.py

@@ -1,142 +0,0 @@
-"""Low-level MCP stdio adapter around the transport-agnostic Project Context core."""
-
-# ruff: noqa: UP045 -- Optional keeps the template importable with Pydantic on Python 3.9.
-
-from __future__ import annotations
-
-import json
-from typing import Any, Optional
-from uuid import uuid4
-
-from pydantic import ValidationError
-
-from .foundation import (
-    DispatchResult,
-    ProjectContextRuntime,
-    ProviderError,
-    error_result,
-)
-from .registry import TOOLS_BY_NAME, tool_declarations
-from .runtime import default_runtime, require_supported_python
-
-
-def dispatch(
-    name: str,
-    arguments: dict[str, Any],
-    runtime: ProjectContextRuntime,
-) -> DispatchResult:
-    """Validate → authorize → resolve provider → execute → validate output."""
-    correlation_id = str(uuid4())
-    tool = TOOLS_BY_NAME.get(name)
-    if tool is None:
-        return error_result(
-            "NOT_FOUND",
-            category="NOT_FOUND",
-            retryable=False,
-            message="The requested MCP tool is not registered.",
-            suggested_action="Refresh the tool list and choose one of the advertised tools.",
-            correlation_id=correlation_id,
-        )
-
-    try:
-        validated_input = tool.input_model.model_validate(arguments or {})
-    except ValidationError:
-        return error_result(
-            "INVALID_INPUT",
-            category="INVALID_INPUT",
-            retryable=False,
-            message="The tool arguments do not match the published input contract.",
-            suggested_action="Correct the required fields and value bounds, then call again.",
-            correlation_id=correlation_id,
-        )
-
-    project_id = str(validated_input.project_id)
-    if not runtime.policy.decide(runtime.identity, name, project_id):
-        return error_result(
-            "DENIED",
-            category="DENIED",
-            retryable=False,
-            message="The project is outside the caller's approved scope.",
-            suggested_action="Use an approved project or ask the project owner for access.",
-            correlation_id=correlation_id,
-        )
-
-    try:
-        provider = runtime.credential_resolver.resolve(runtime.identity, name)
-        raw_output = tool.handler(validated_input, provider)
-    except ProviderError as exc:
-        return error_result(
-            exc.code,
-            category=exc.code,
-            retryable=exc.retryable,
-            message=exc.safe_message,
-            suggested_action="Check the approved provider configuration and retry if allowed.",
-            correlation_id=correlation_id,
-        )
-    except Exception:  # noqa: BLE001 - provider failures must not crash or leak into the agent turn
-        return error_result(
-            "UPSTREAM_ERROR",
-            category="UPSTREAM_ERROR",
-            retryable=False,
-            message="The approved provider could not complete the request.",
-            suggested_action="Check the correlation ID in server logs; do not resend credentials.",
-            correlation_id=correlation_id,
-        )
-
-    try:
-        output_with_trace = {**raw_output, "correlation_id": correlation_id}
-        validated_output = tool.output_model.model_validate(output_with_trace)
-    except ValidationError:
-        return error_result(
-            "UPSTREAM_ERROR",
-            category="UPSTREAM_ERROR",
-            retryable=False,
-            message="The provider response did not match the published output contract.",
-            suggested_action="Fix the provider mapping before retrying the request.",
-            correlation_id=correlation_id,
-        )
-    return DispatchResult(ok=True, payload=validated_output.model_dump(mode="json"))
-
-
-def build_server(runtime: Optional[ProjectContextRuntime] = None):
-    from mcp import types
-    from mcp.server.lowlevel import Server
-
-    require_supported_python()
-    app_runtime = runtime or default_runtime()
-    app = Server("project_context")
-
-    @app.list_tools()
-    async def list_tools() -> list[types.Tool]:
-        return [types.Tool(**declaration) for declaration in tool_declarations()]
-
-    @app.call_tool()
-    async def call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
-        result = dispatch(name, arguments or {}, app_runtime)
-        return types.CallToolResult(
-            content=[types.TextContent(
-                type="text",
-                text=json.dumps(result.payload, ensure_ascii=False, separators=(",", ":")),
-            )],
-            structuredContent=result.payload if result.ok else None,
-            isError=not result.ok,
-        )
-
-    return app
-
-
-def main() -> None:
-    import anyio
-    from mcp.server.stdio import stdio_server
-
-    app = build_server()
-
-    async def _run() -> None:
-        async with stdio_server() as (read, write):
-            await app.run(read, write, app.create_initialization_options())
-
-    anyio.run(_run)
-
-
-if __name__ == "__main__":
-    main()

mcp_servers/project_context/tools/__init__.py

@@ -1 +0,0 @@
-"""Independent tool modules; ownership is documented in the team guide."""

mcp_servers/project_context/tools/change_context.py

@@ -1,55 +0,0 @@
-"""Member C work package: get_project_change_context."""
-
-# ruff: noqa: UP045 -- Optional keeps Pydantic model evaluation compatible with Python 3.9.
-
-from __future__ import annotations
-
-from typing import Any, Literal, Optional
-
-from pydantic import Field
-
-from ..foundation import ContractModel, SourceCitation, ToolTemplate
-
-
-class ChangeContextInput(ContractModel):
-    project_id: str = Field(min_length=1, max_length=128)
-    change_id: str = Field(min_length=1, max_length=128)
-    detail: Literal["summary", "standard", "full"] = "standard"
-    cursor: Optional[str] = Field(default=None, max_length=2048)
-
-
-class ChangeContextOutput(ContractModel):
-    correlation_id: str
-    project_id: str
-    change_id: str
-    change_type: Literal["commit", "pull-request", "merge-request"]
-    title: str
-    state: str
-    summary: str
-    authors: tuple[str, ...]
-    files: tuple[str, ...]
-    commits: tuple[str, ...]
-    related_issues: tuple[str, ...]
-    source: SourceCitation
-    truncated: bool
-    returned: int = Field(ge=0)
-    remaining: int = Field(ge=0)
-    next_cursor: Optional[str] = None
-
-
-def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
-    request = ChangeContextInput.model_validate(arguments)
-    return provider.get_change_context(**request.model_dump())
-
-
-TOOL = ToolTemplate(
-    name="get_project_change_context",
-    description=(
-        "Returns provider-neutral context for one authorized commit, pull request, or merge request "
-        "with changed files, commits, related issues, and a pinned source. Use when an exact change "
-        "identifier is known. Do not use for issue details or free-text document search."
-    ),
-    input_model=ChangeContextInput,
-    output_model=ChangeContextOutput,
-    handler=_handle,
-)

mcp_servers/project_context/tools/issue_context.py

@@ -1,59 +0,0 @@
-"""Member A work package: get_project_issue_context."""
-
-# ruff: noqa: UP045 -- Optional keeps Pydantic model evaluation compatible with Python 3.9.
-
-from __future__ import annotations
-
-from typing import Any, Literal, Optional
-
-from pydantic import Field
-
-from ..foundation import ContractModel, SourceCitation, ToolTemplate
-
-
-class IssueContextInput(ContractModel):
-    project_id: str = Field(min_length=1, max_length=128)
-    issue_key: str = Field(min_length=1, max_length=128)
-    detail: Literal["summary", "standard", "full"] = "standard"
-    cursor: Optional[str] = Field(default=None, max_length=2048)
-
-
-class RelatedItem(ContractModel):
-    item_id: str
-    relation: str
-    title: str
-    url: str
-
-
-class IssueContextOutput(ContractModel):
-    correlation_id: str
-    project_id: str
-    issue_key: str
-    title: str
-    status: str
-    description: str
-    acceptance_criteria: tuple[str, ...]
-    related: tuple[RelatedItem, ...]
-    source: SourceCitation
-    truncated: bool
-    returned: int = Field(ge=0)
-    remaining: int = Field(ge=0)
-    next_cursor: Optional[str] = None
-
-
-def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
-    request = IssueContextInput.model_validate(arguments)
-    return provider.get_issue_context(**request.model_dump())
-
-
-TOOL = ToolTemplate(
-    name="get_project_issue_context",
-    description=(
-        "Returns one authorized work item's title, state, description, acceptance criteria, "
-        "related items, and pinned source. Use when an exact issue key is known. Do not use for "
-        "free-text knowledge search or Git change review."
-    ),
-    input_model=IssueContextInput,
-    output_model=IssueContextOutput,
-    handler=_handle,
-)

mcp_servers/project_context/tools/knowledge_search.py

@@ -1,58 +0,0 @@
-"""Member B work package: search_project_knowledge."""
-
-# ruff: noqa: UP045 -- Optional keeps Pydantic model evaluation compatible with Python 3.9.
-
-from __future__ import annotations
-
-from typing import Any, Literal, Optional
-
-from pydantic import Field
-
-from ..foundation import ContractModel, SourceCitation, ToolTemplate
-
-
-class KnowledgeSearchInput(ContractModel):
-    project_id: str = Field(min_length=1, max_length=128)
-    query: str = Field(min_length=2, max_length=1000)
-    detail: Literal["summary", "standard", "full"] = "standard"
-    top_k: int = Field(default=5, ge=1, le=20)
-    language: Optional[Literal["en", "ja", "vi"]] = None
-    cursor: Optional[str] = Field(default=None, max_length=2048)
-
-
-class KnowledgeItem(ContractModel):
-    document_id: str
-    chunk_id: str
-    title: str
-    excerpt: str
-    score: float = Field(ge=0, le=1)
-    source: SourceCitation
-
-
-class KnowledgeSearchOutput(ContractModel):
-    correlation_id: str
-    project_id: str
-    query: str
-    items: tuple[KnowledgeItem, ...]
-    truncated: bool
-    returned: int = Field(ge=0)
-    remaining: int = Field(ge=0)
-    next_cursor: Optional[str] = None
-
-
-def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
-    request = KnowledgeSearchInput.model_validate(arguments)
-    return provider.search_knowledge(**request.model_dump())
-
-
-TOOL = ToolTemplate(
-    name="search_project_knowledge",
-    description=(
-        "Searches approved knowledge for one authorized project and returns ranked excerpts with "
-        "pinned citations. Use for requirements, design notes, or runbooks when no exact issue is "
-        "known. Do not use for issue details or Git change review."
-    ),
-    input_model=KnowledgeSearchInput,
-    output_model=KnowledgeSearchOutput,
-    handler=_handle,
-)

mcp_servers/project_context_server.py

@@ -1,9 +0,0 @@
-"""Stable module entry point for ``python -m cowork_local.mcp_servers.project_context_server``."""
-
-from .project_context.server import build_server, dispatch, main
-
-__all__ = ["build_server", "dispatch", "main"]
-
-
-if __name__ == "__main__":
-    main()

presentation/__init__.py

@@ -0,0 +1,7 @@
+"""Presentation layer: Qt widgets, one screen/concern per file, assembled
+into thin shell containers (EPIC R08).
+
+Nothing under here is imported by ``domain/`` or ``application/``
+(``scripts/check_imports.py`` rule I3) — data flows the other way, through
+application services these widgets call.
+"""

presentation/dashboard/__init__.py

@@ -0,0 +1,3 @@
+"""Dashboard screen, split into single-responsibility widgets (R08-T13):
+``token_usage_card_widget``, ``usage_chart_widget``, ``habits_widget``,
+assembled by the ``dashboard_tab`` shell."""

presentation/dashboard/dashboard_tab.py

@@ -0,0 +1,91 @@
+"""DashboardTab shell (R08-T13) — assembles
+``token_usage_card_widget.py::TokenUsageCardWidget``,
+``usage_chart_widget.py::UsageChartWidget`` and
+``habits_widget.py::HabitsWidget`` behind the scroll area / header / 30s
+auto-refresh timer that used to be inline in
+``ui/dashboard_tab.py::DashboardTab.__init__`` (lines 40-193 of the original
+437-line file).
+
+The one ``DashboardQueryService`` (R08-T13) instance is built here and
+shared by all three children so pricing/currency stay consistent across the
+whole screen.
+"""
+from __future__ import annotations
+
+from PySide6.QtCore import QTimer, Signal
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QPushButton, QScrollArea, QVBoxLayout, QWidget
+
+from cowork_local.application.monitoring import DashboardQueryService
+from cowork_local.i18n import on_language_changed, tr
+from cowork_local.presentation.dashboard.habits_widget import HabitsWidget
+from cowork_local.presentation.dashboard.token_usage_card_widget import TokenUsageCardWidget
+from cowork_local.presentation.dashboard.usage_chart_widget import UsageChartWidget
+from cowork_local.state import AppContext
+from cowork_local.ui.icons import icon
+
+
+class DashboardTab(QWidget):
+    status_message = Signal(str)
+
+    def __init__(self, ctx: AppContext):
+        super().__init__()
+        self.ctx = ctx
+        self._query = DashboardQueryService(ctx)
+
+        outer = QVBoxLayout(self)
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        scroll.setFrameShape(QScrollArea.NoFrame)
+        content = QWidget()
+        scroll.setWidget(content)
+        outer.addWidget(scroll)
+        root = QVBoxLayout(content)
+
+        head = QHBoxLayout()
+        self._title = QLabel()
+        self._title.setStyleSheet("font-weight:700; font-size:15px;")
+        self.refresh_btn = QPushButton("")
+        self.refresh_btn.setIcon(icon("refresh"))
+        self.refresh_btn.setFixedWidth(34)
+        self.refresh_btn.clicked.connect(self.refresh)
+        head.addWidget(self._title, 1)
+        head.addWidget(self.refresh_btn)
+        root.addLayout(head)
+
+        self.token_cards = TokenUsageCardWidget(ctx, self._query)
+        root.addWidget(self.token_cards)
+
+        self.chart = UsageChartWidget(ctx, self._query)
+        self.chart.period_changed.connect(self.refresh)
+        self.chart.currency_changed.connect(self.refresh)
+        root.addWidget(self.chart)
+
+        self.habits = HabitsWidget(ctx, self._query)
+        self.habits.status_message.connect(self.status_message.emit)
+        root.addWidget(self.habits, 1)
+
+        # Auto-refresh every 30s so numbers follow ongoing work.
+        self._timer = QTimer(self)
+        self._timer.setInterval(30_000)
+        self._timer.timeout.connect(self.refresh)
+        self._timer.start()
+
+        on_language_changed(self._retranslate)
+        self.refresh()
+
+    def _retranslate(self) -> None:
+        self._title.setText(tr("dashboard.title"))
+        self.refresh_btn.setToolTip(tr("dashboard.refresh_tooltip"))
+        self.token_cards.retranslate()
+        self.chart.retranslate()
+        self.habits.retranslate()
+        self.refresh()
+
+    def refresh(self, *_a) -> None:
+        start, end = self.chart.period_range()
+        self.token_cards.refresh(start, end)
+        self.chart.refresh()
+        self.habits.refresh(start, end)
+
+
+__all__ = ["DashboardTab"]

presentation/dashboard/habits_widget.py

@@ -0,0 +1,171 @@
+"""HabitsWidget — the usage-habits summary + AI recommendations panel of the
+Dashboard (R08-T13, extracted from ``ui/dashboard_tab.py::DashboardTab``,
+lines 154-184/348-372/376-438 of the original 437-line file: the habits/AI
+layout, ``refresh()``'s habits-HTML section, ``_apply_saving_strategy``,
+``_ai_analyze``).
+"""
+from __future__ import annotations
+
+from datetime import date
+from typing import List, Optional
+
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QPushButton, QTextBrowser, QVBoxLayout, QWidget
+from PySide6.QtCore import Signal
+
+from cowork_local.application.monitoring import DashboardQueryService
+from cowork_local.core.worker import AgentWorker
+from cowork_local.i18n import tr
+from cowork_local.ui.icons import icon
+from cowork_local.ui.widgets import fmt_tokens
+
+
+class HabitsWidget(QWidget):
+    status_message = Signal(str)
+
+    def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        super().__init__(parent)
+        self.ctx = ctx
+        self._query = query
+        self._ai_worker: Optional[AgentWorker] = None
+        self._period_range = (None, None)   # set on each refresh(); _ai_analyze reuses it
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+        self._habits_title = QLabel()
+        self._habits_title.setStyleSheet("font-weight:600;")
+        habits_head = QHBoxLayout()
+        self.ai_analyze_btn = QPushButton()
+        self.ai_analyze_btn.setIcon(icon("sparkle"))
+        self.ai_analyze_btn.clicked.connect(self._ai_analyze)
+        # Apply an AI-suggested cost-saving strategy — only after the user
+        # clicks to approve it.
+        self.apply_strategy_btn = QPushButton()
+        self.apply_strategy_btn.setIcon(icon("bolt"))
+        self.apply_strategy_btn.setVisible(False)
+        self.apply_strategy_btn.clicked.connect(self._apply_saving_strategy)
+        habits_head.addWidget(self._habits_title, 1)
+        habits_head.addWidget(self.apply_strategy_btn)
+        habits_head.addWidget(self.ai_analyze_btn)
+        root.addLayout(habits_head)
+        self.habits = QTextBrowser()
+        self.habits.setOpenExternalLinks(False)
+        self.habits.setMinimumHeight(160)
+        root.addWidget(self.habits, 1)
+        self._ai_title = QLabel()
+        self._ai_title.setStyleSheet("font-weight:600;")
+        self._ai_title.setVisible(False)
+        root.addWidget(self._ai_title)
+        self.ai_advice = QTextBrowser()
+        self.ai_advice.setOpenExternalLinks(False)
+        self.ai_advice.setMinimumHeight(140)
+        self.ai_advice.setVisible(False)
+        root.addWidget(self.ai_advice, 1)
+
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
+        self.ai_analyze_btn.setToolTip(tr("dashboard.ai_analyze_tooltip"))
+        self.apply_strategy_btn.setText(tr("dashboard.strategy_btn"))
+        self.apply_strategy_btn.setToolTip(tr("dashboard.strategy_tooltip"))
+        self._habits_title.setText(tr("dashboard.habits_title"))
+
+    def refresh(self, start: date, end: date) -> None:
+        self._period_range = (start, end)
+        summary = self._query.summary(start, end)
+        s, events = summary["stats"], summary["events"]
+
+        lines: List[str] = []
+        if not events:
+            lines.append(f"<i>{tr('dashboard.no_data')}</i>")
+        else:
+            lines.append(f"<b>{tr('dashboard.h_top')}</b>")
+            lines.append("<ol>")
+            for label, tok in s["top_labels"]:
+                pct = int(tok * 100 / s["total"]) if s["total"] else 0
+                lines.append(f"<li>{label[:60]} — {fmt_tokens(tok)} tokens ({pct}%)</li>")
+            lines.append("</ol>")
+            src_parts = ", ".join(
+                f"{tr(f'app.tab.{k}') if k in ('cowork', 'code') else k}: {fmt_tokens(v)}"
+                for k, v in s["by_source"])
+            lines.append(f"<b>{tr('dashboard.h_by_source')}</b>: {src_parts}<br>")
+            lines.append(f"<b>{tr('dashboard.h_avg')}</b>: "
+                         f"{fmt_tokens(s['avg_per_turn'])} tokens<br>")
+            if s["busiest_day"]:
+                lines.append(f"<b>{tr('dashboard.h_busiest_day')}</b>: {s['busiest_day']}<br>")
+            if s["busiest_hour"] is not None:
+                lines.append(f"<b>{tr('dashboard.h_busiest_hour')}</b>: "
+                             f"{s['busiest_hour']:02d}:00–{s['busiest_hour']:02d}:59<br>")
+            if s["estimated_share"] > 0:
+                lines.append(f"<i>{tr('dashboard.estimated_note', pct=int(s['estimated_share'] * 100))}</i>")
+        self.habits.setHtml("".join(lines))
+
+    def _apply_saving_strategy(self) -> None:
+        """Apply an AI-suggested cost-saving strategy AFTER the user
+        approves: turn on auto-compress and compress earlier (lower
+        threshold) + compress content before sending it to the agent."""
+        from PySide6.QtWidgets import QMessageBox
+        if QMessageBox.question(self, tr("dashboard.strategy_title"),
+                                tr("dashboard.strategy_confirm")) != QMessageBox.Yes:
+            return
+        cx = self.ctx.config.data.setdefault("context", {})
+        cx["auto_compact"] = True
+        cx["compact_threshold"] = 0.6          # compress at 60% of the window (was ~80%)
+        cx["compress_before_send"] = True      # digest context before each turn
+        self.ctx.save()
+        self.status_message.emit(tr("dashboard.strategy_applied"))
+
+    def _ai_analyze(self) -> None:
+        """✨ Send the aggregated numbers (never raw prompt text) to the
+        active provider and show habit feedback + token-saving
+        recommendations."""
+        if self._ai_worker is not None:
+            return
+        start, end = self._period_range
+        if start is None:
+            return
+        summary = self._query.summary(start, end)
+        if not summary["events"]:
+            self.status_message.emit(tr("dashboard.no_data"))
+            return
+        stats = summary["stats"]
+        self.ai_analyze_btn.setEnabled(False)
+        self.ai_analyze_btn.setText(tr("dashboard.ai_analyzing"))
+        ctx = self.ctx
+
+        def job(worker: AgentWorker):
+            from cowork_local.core import usage_tracker as ut
+            from cowork_local.i18n import get_language
+
+            prompt = ut.build_ai_analysis_prompt(stats, get_language())
+            provider = ctx.build_active_provider()
+            reply = provider.chat([{"role": "user", "content": prompt}],
+                                  cancel=worker.stop_event)
+            return {"text": (reply.get("content") or "").strip()}
+
+        def done(result: dict) -> None:
+            self._ai_worker = None
+            self.ai_analyze_btn.setEnabled(True)
+            self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
+            text = result.get("text") or ""
+            if text:
+                self._ai_title.setText(tr("dashboard.ai_advice_title"))
+                self._ai_title.setVisible(True)
+                self.ai_advice.setMarkdown(text)
+                self.ai_advice.setVisible(True)
+                self.apply_strategy_btn.setVisible(True)
+
+        def failed(err: str) -> None:
+            self._ai_worker = None
+            self.ai_analyze_btn.setEnabled(True)
+            self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
+            self.status_message.emit(str(err))
+
+        w = AgentWorker(job)
+        w.finished_ok.connect(done)
+        w.failed.connect(failed)
+        self._ai_worker = w
+        w.start()
+
+
+__all__ = ["HabitsWidget"]

presentation/dashboard/token_usage_card_widget.py

@@ -0,0 +1,108 @@
+"""TokenUsageCardWidget — the stat-card grid + budget card of the Dashboard
+(R08-T13, extracted from ``ui/dashboard_tab.py::DashboardTab``, lines
+116-141/226-254/337-346 of the original 437-line file: the card grid layout,
+``_apply_budget``, ``_refresh_budget``, and ``refresh()``'s card-filling
+section).
+"""
+from __future__ import annotations
+
+from datetime import date
+
+from PySide6.QtWidgets import QGridLayout, QWidget
+
+from cowork_local.application.monitoring import DashboardQueryService
+from cowork_local.i18n import tr
+from cowork_local.ui.icons import icon
+from cowork_local.ui.widgets import BudgetCard, StatCard, fmt_tokens
+
+
+class TokenUsageCardWidget(QWidget):
+    """Cost is the headline this screen exists for, so it gets a card twice
+    the height of the rest instead of being the fifth of five identical
+    tiles — with six equal cards nothing said which number mattered."""
+
+    def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        super().__init__(parent)
+        self.ctx = ctx
+        self._query = query
+
+        cards_grid = QGridLayout(self)
+        cards_grid.setSpacing(8)
+        self.card_total = StatCard()
+        self.card_in = StatCard()
+        self.card_out = StatCard()
+        self.card_cache = StatCard()
+        self.card_cost = StatCard().as_hero()
+        # Hero on the left, spanning both rows; the four supporting figures
+        # fill a 2x2 block beside it.
+        cards_grid.addWidget(self.card_cost, 0, 0, 2, 1)
+        for i, card in enumerate((self.card_total, self.card_in,
+                                  self.card_out, self.card_cache)):
+            cards_grid.addWidget(card, i // 2, 1 + i % 2)
+        # Budget: remaining/budget, direct entry, auto-warns red past 85% used.
+        self.budget_card = BudgetCard()
+        self.budget_card.apply_btn.setIcon(icon("check"))
+        self.budget_card.apply_btn.clicked.connect(self._apply_budget)
+        cards_grid.addWidget(self.budget_card, 0, 3, 2, 1)
+        for col, stretch in ((0, 3), (1, 2), (2, 2), (3, 3)):
+            cards_grid.setColumnStretch(col, stretch)
+
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self.budget_card.apply_btn.setToolTip(tr("usage.budget_apply_tooltip"))
+        self.budget_card.budget_spin.setToolTip(tr("usage.budget_spin_tooltip"))
+
+    def refresh(self, start: date, end: date) -> None:
+        summary = self._query.summary(start, end)
+        s, pricing, costs = summary["stats"], summary["pricing"], summary["costs"]
+        from cowork_local.core import usage_tracker as ut
+
+        est_note = (tr("dashboard.estimated_note", pct=int(s["estimated_share"] * 100))
+                    if s["estimated_share"] > 0 else "")
+        self.card_total.set(tr("dashboard.card_total"), fmt_tokens(s["total"]),
+                            tr("dashboard.card_turns", n=s["turns"]))
+        self.card_in.set(tr("dashboard.card_in"), fmt_tokens(s["in"]),
+                         ut.format_cost(costs["in"], pricing))
+        self.card_out.set(tr("dashboard.card_out"), fmt_tokens(s["out"]),
+                          ut.format_cost(costs["out"], pricing))
+        self.card_cache.set(tr("dashboard.card_cache"), fmt_tokens(s["cache"]),
+                            ut.format_cost(costs["cache"], pricing))
+        self.card_cost.set(tr("dashboard.card_cost"),
+                           ut.format_cost(summary["total_cost"], pricing, digits=2), est_note)
+        self._refresh_budget()
+
+    def _apply_budget(self) -> None:
+        """Persist the spin box's value as the new budget — starts a fresh
+        remaining-balance window (spend before now is no longer counted)."""
+        ccy = (self.ctx.config.data.get("usage") or {}).get("currency", "USD")
+        self._query.set_budget(self.budget_card.budget_spin.value(), ccy)
+        self.ctx.save()
+        self._refresh_budget()
+
+    def _refresh_budget(self) -> None:
+        from cowork_local.core import model_pricing as mp
+        from cowork_local.core import usage_tracker as ut
+
+        pricing = self._query.pricing()
+        status = self._query.budget_status()
+        if status is None:
+            self.budget_card.set(tr("usage.budget_title"), "—", tr("usage.budget_no_budget"))
+            self.budget_card.budget_spin.setValue(0.0)
+            return
+        remaining_disp = mp.convert(status["remaining_usd"], "USD",
+                                    pricing.get("currency", "USD"), self.ctx.config)
+        amount_disp = mp.convert(status["amount_usd"], "USD",
+                                 pricing.get("currency", "USD"), self.ctx.config)
+        value = (f"{ut.format_cost(status['remaining_usd'], pricing, digits=2)}"
+                 f" / {ut.format_cost(status['amount_usd'], pricing, digits=2)}")
+        pct = int(round(status["pct_used"] * 100))
+        sub = tr("usage.budget_over_warning") if status["over_85"] else tr("usage.budget_used_pct", pct=pct)
+        self.budget_card.set(tr("usage.budget_title"), value, sub, warn=status["over_85"])
+        # keep the entry field showing the CURRENT budget (in display currency)
+        # — only when it doesn't already have unsaved focus/edits from the user.
+        if not self.budget_card.budget_spin.hasFocus():
+            self.budget_card.budget_spin.setValue(round(amount_disp, 2))
+
+
+__all__ = ["TokenUsageCardWidget"]

presentation/dashboard/usage_chart_widget.py

@@ -0,0 +1,179 @@
+"""UsageChartWidget — the period pager + granularity/metric/currency
+controls + spline chart of the Dashboard (R08-T13, extracted from
+``ui/dashboard_tab.py::DashboardTab``, lines 53-114/143-152/201-207/
+263-323 of the original 437-line file).
+
+Owns the period SELECTOR (granularity + prev/next offset) that the whole
+screen follows — ``token_usage_card_widget.py`` and ``habits_widget.py``
+read :meth:`period_range`/:meth:`granularity` rather than keeping their own
+copy, and the shell re-refreshes them on :attr:`period_changed`.
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import QComboBox, QHBoxLayout, QLabel, QPushButton, QVBoxLayout, QWidget
+
+from cowork_local.application.monitoring import DashboardQueryService
+from cowork_local.i18n import tr
+from cowork_local.theme import current_palette
+from cowork_local.ui.icons import icon
+from cowork_local.ui.spline_chart import SplineChart
+from cowork_local.ui.widgets import fmt_tokens
+
+
+class UsageChartWidget(QWidget):
+    period_changed = Signal()     # granularity or offset changed — re-run every widget
+    currency_changed = Signal()   # display currency changed — same, cost text depends on it
+
+    def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        super().__init__(parent)
+        self.ctx = ctx
+        self._query = query
+        self._chart_offset = 0    # 0 = current period; <0 = a past period
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+        controls = QHBoxLayout()
+        controls.setSpacing(6)
+        self.chart_prev_btn = QPushButton()
+        self.chart_prev_btn.setIcon(icon("chevron-left"))
+        self.chart_prev_btn.setFixedWidth(30)
+        self.chart_prev_btn.clicked.connect(self._chart_prev)
+        controls.addWidget(self.chart_prev_btn)
+        self._chart_period_lbl = QLabel()
+        self._chart_period_lbl.setObjectName("hint")
+        self._chart_period_lbl.setAlignment(Qt.AlignCenter)
+        self._chart_period_lbl.setMinimumWidth(170)
+        controls.addWidget(self._chart_period_lbl)
+        self.chart_next_btn = QPushButton()
+        self.chart_next_btn.setIcon(icon("chevron-right"))
+        self.chart_next_btn.setFixedWidth(30)
+        self.chart_next_btn.clicked.connect(self._chart_next)
+        controls.addWidget(self.chart_next_btn)
+        controls.addSpacing(12)
+        self.gran_combo = QComboBox()
+        for g in ("week", "month", "year"):
+            self.gran_combo.addItem(tr(f"dashboard.gran_{g}"), g)
+        self.gran_combo.currentIndexChanged.connect(self._on_gran_changed)
+        controls.addWidget(self.gran_combo)
+        self.metric_combo = QComboBox()
+        for m in ("cost", "tokens"):
+            self.metric_combo.addItem(tr(f"dashboard.metric_{m}"), m)
+        self.metric_combo.currentIndexChanged.connect(self.refresh)
+        controls.addWidget(self.metric_combo)
+        controls.addStretch(1)
+        # Display-currency picker — both Dashboard and Monitoring read/write
+        # the same usage.currency config key, so changing it here updates
+        # cost text everywhere.
+        self.currency_lbl = QLabel()
+        self.currency_lbl.setObjectName("hint")
+        controls.addWidget(self.currency_lbl)
+        self.currency_combo = QComboBox()
+        from cowork_local.core import usage_tracker as ut
+        for cur in ut.SUPPORTED_CURRENCIES:
+            self.currency_combo.addItem(cur, cur)
+        idx = self.currency_combo.findData(
+            (self.ctx.config.data.get("usage") or {}).get("currency", "USD"))
+        self.currency_combo.setCurrentIndex(max(0, idx))
+        self.currency_combo.currentIndexChanged.connect(self._on_currency_changed)
+        controls.addWidget(self.currency_combo)
+        root.addLayout(controls)
+
+        chart_head = QHBoxLayout()
+        self._chart_title = QLabel()
+        self._chart_title.setStyleSheet("font-weight:600;")
+        chart_head.addWidget(self._chart_title, 1)
+        root.addLayout(chart_head)
+        self.chart = SplineChart()
+        root.addWidget(self.chart)
+
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self.currency_lbl.setText(tr("monitoring.overview_currency"))
+        self.currency_combo.setToolTip(tr("dashboard.currency_tooltip"))
+        self._chart_title.setText(tr("dashboard.chart_title"))
+        self.chart_prev_btn.setToolTip(tr("dashboard.chart_prev"))
+        self.chart_next_btn.setToolTip(tr("dashboard.chart_next"))
+
+    # ---- public: the period selector every other widget follows ------------- #
+    def granularity(self) -> str:
+        return self.gran_combo.currentData() or "week"
+
+    @property
+    def chart_offset(self) -> int:
+        return self._chart_offset
+
+    def period_range(self) -> Tuple:
+        return self._query.period_range(self.granularity(), self._chart_offset)
+
+    # ---- navigation ------------------------------------------------------------ #
+    def _on_gran_changed(self, *_a) -> None:
+        self._chart_offset = 0            # period size changed → back to current
+        self.period_changed.emit()
+
+    def _chart_prev(self) -> None:
+        self._chart_offset -= 1
+        self.period_changed.emit()
+
+    def _chart_next(self) -> None:
+        self._chart_offset = min(0, self._chart_offset + 1)   # never past the present
+        self.period_changed.emit()
+
+    def _on_currency_changed(self, _idx: int) -> None:
+        cur = self.currency_combo.currentData()
+        if not cur:
+            return
+        self.ctx.config.data.setdefault("usage", {})["currency"] = cur
+        self.ctx.save()
+        self.currency_changed.emit()
+
+    @staticmethod
+    def _delta_txt(cur: float, prev: float) -> str:
+        """▲/▼ percent change of ``cur`` vs ``prev`` (empty if no baseline)."""
+        if not prev:
+            return ""
+        pct = (cur - prev) / prev * 100
+        arrow = "▲" if pct > 0.5 else ("▼" if pct < -0.5 else "•")
+        return f"{arrow}{abs(pct):.0f}%"
+
+    # ---- rendering --------------------------------------------------------------- #
+    def refresh(self, *_a) -> None:
+        """Break the SELECTED period into its parts: WEEK -> 7 days (Mon-Sun)
+        - MONTH -> weeks W1..Wn - YEAR -> 12 months. A dashed line marks the
+        previous same-granularity period's average per point with the %
+        change of the totals."""
+        from cowork_local.core import usage_tracker as ut
+
+        gran = self.granularity()
+        metric = self.metric_combo.currentData() or "cost"
+        pts = self._query.chart_series(gran, self._chart_offset, metric)
+        pricing = self._query.pricing()
+        mi = 0 if metric == "tokens" else 1
+        # Compact cost format (2 decimals, K/M above 1,000/1,000,000) — the
+        # chart's y-axis label box is narrow; format_cost's full precision
+        # overflowed it, clipping/obscuring the amount.
+        fmt = fmt_tokens if metric == "tokens" else (lambda v: ut.format_cost_compact(v, pricing))
+
+        cur = self._query.period_totals(gran, self._chart_offset)
+        prev = self._query.period_totals(gran, self._chart_offset - 1)
+        ref_key = {"week": "dashboard.ref_last_week",
+                   "month": "dashboard.ref_last_month",
+                   "year": "dashboard.ref_last_year"}.get(gran, "dashboard.ref_last_week")
+        n_points = max(1, len(pts))
+        refs = []
+        if prev[mi] > 0:
+            # Muted on purpose: the comparison line is a reference, not the
+            # series — it must not compete with the accent-coloured spline.
+            refs.append((prev[mi] / n_points,
+                         f"{tr(ref_key)} {self._delta_txt(cur[mi], prev[mi])}",
+                         current_palette().text_muted))
+        self.chart.set_reference_lines(refs)
+        self.chart.set_data(pts, fmt, tr(f"dashboard.metric_{metric}"))
+        self._chart_period_lbl.setText(self._query.period_range_label(gran, self._chart_offset))
+        self.chart_next_btn.setEnabled(self._chart_offset < 0)
+
+
+__all__ = ["UsageChartWidget"]

presentation/folder/__init__.py

@@ -0,0 +1,4 @@
+"""Folder Explorer screen, split into single-responsibility widgets
+(R08-T12): ``workspace_file_tree``, ``document_preview_manager``,
+``ai_edit_model_resolver``, ``ai_file_editor_dialog``, assembled by the
+``folder_tab`` shell."""

presentation/folder/ai_edit_model_resolver.py

@@ -0,0 +1,248 @@
+"""AiEditModelResolver — model picker + Auto Model Routing + image-model
+discovery for the AI-Edit panel (R08-T12, extracted from
+``ui/folder_tab.py::FolderTab``, lines 802-1036/911-961 of the original
+1587-line file: ``refresh_ai_models``, ``_scan_all_image_models``,
+``_ai_provider``, ``_ai_apply_routing``, ``_confirm_routing_switch``,
+``_ai_image_model``, ``_maybe_suggest_image_model``,
+``_suggest_cross_provider_image``).
+
+A plain (non-Qt-widget) helper composed BY
+``ai_file_editor_dialog.py::AiFileEditorDialog`` — this is genuinely a
+distinct concern (which provider/model answers THIS run) from the panel's
+send/plan/edit orchestration, and splitting it out is also what keeps
+``ai_file_editor_dialog.py`` under the 400-line cap.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional, Tuple
+
+from cowork_local.core.worker import AgentWorker
+from cowork_local.i18n import tr
+
+
+class AiEditModelResolver:
+    """Owns the AI-edit model combo's contents and every "which provider/
+    model should THIS run use" decision — independent of the Cowork/Settings
+    agent, exactly like the original panel's own picker was.
+
+    Args:
+        ctx: ``AppContext``.
+        model_combo: the ``QComboBox`` populated by :meth:`refresh`.
+        on_status: ``(text) -> None`` — posts a status line into the AI
+            chat (production passes ``ai_chat.add_status``).
+        confirm_switch: ``(self, decision, timeout) -> bool`` — the Qt
+            confirm dialog for Manual routing mode (kept as a callback so
+            this class never imports a dialog itself).
+    """
+
+    def __init__(self, ctx, model_combo, on_status, confirm_switch) -> None:
+        self.ctx = ctx
+        self._combo = model_combo
+        self._on_status = on_status
+        self._confirm_switch = confirm_switch
+        self._models: List[str] = []
+        self._models_provider = ""
+        self._all_image_models: List[Tuple[str, str]] = []   # [(provider_key, model)]
+        self._img_scan_worker = None
+        self._pending_img_suggest = False
+        self._routed_provider: Optional[str] = None
+        self._routed_model: Optional[str] = None
+
+    @property
+    def models(self) -> List[str]:
+        return self._models
+
+    @property
+    def models_provider(self) -> str:
+        return self._models_provider
+
+    @property
+    def routed_provider(self) -> Optional[str]:
+        """The provider :meth:`apply_routing` switched to for the current
+        run, or ``None`` when it didn't switch (routing off/declined)."""
+        return self._routed_provider
+
+    @property
+    def routed_model(self) -> Optional[str]:
+        return self._routed_model
+
+    def should_refresh(self) -> bool:
+        """True on first open, or when the active provider changed since
+        the model list was last loaded — a stale list would resolve a pick
+        to the wrong/default model at the new endpoint."""
+        return self._combo.count() <= 1 or self._models_provider != self.ctx.config.active_provider
+
+    def refresh(self) -> None:
+        """Fetch the active provider's model list (background) into the
+        picker. Also proactively scans ALL providers for image-capable
+        models so a suggestion is ready the moment one is needed."""
+        name = self.ctx.config.active_provider
+        setting_model = self.ctx.config.provider_conf(name).get("model", "")
+
+        def job(worker):
+            prov = self.ctx.build_provider_for(name)
+            try:
+                models = list(getattr(prov, "list_models", lambda: [])() or [])
+            except Exception:  # noqa: BLE001
+                models = []
+            return {"models": models}
+
+        def done(res):
+            fetched = list(res.get("models", []))
+            # Always offer the Settings-configured model as an explicit
+            # choice, even when the provider can't list models.
+            self._models = list(dict.fromkeys(
+                ([setting_model] if setting_model else []) + [m for m in fetched if m]))
+            self._models_provider = name
+            cur = self._combo.currentData()
+            self._combo.blockSignals(True)
+            self._combo.clear()
+            self._combo.addItem(tr("folder.ai_model_auto"), None)
+            for m in self._models:
+                self._combo.addItem(m, m)
+            idx = self._combo.findData(cur)
+            self._combo.setCurrentIndex(idx if idx >= 0 else 0)
+            self._combo.blockSignals(False)
+
+        w = AgentWorker(job)
+        w.finished_ok.connect(done)
+        self._models_worker = w
+        w.start()
+        self._scan_all_image_models()
+
+    def _scan_all_image_models(self, then_suggest: bool = False) -> None:
+        if self._img_scan_worker is not None:
+            if then_suggest:
+                self._pending_img_suggest = True
+            return
+        providers = dict(self.ctx.config.data.get("providers", {}))
+        candidates = [k for k, c in providers.items()
+                      if (c.get("base_url") or c.get("api_key"))]
+
+        def job(worker):
+            from cowork_local.core import image_gen
+            found = []
+            for key in candidates:
+                try:
+                    prov = self.ctx.build_provider_for(key)
+                    models = list(getattr(prov, "list_models", lambda: [])() or [])
+                except Exception:  # noqa: BLE001 - a broken provider must not block the scan
+                    models = []
+                for m in models:
+                    if image_gen.looks_like_image_model(m):
+                        found.append((key, m))
+            return {"found": found}
+
+        def done(res):
+            self._img_scan_worker = None
+            self._all_image_models = list(res.get("found", []))
+            if self._pending_img_suggest:
+                self._pending_img_suggest = False
+                self._suggest_cross_provider_image()
+
+        w = AgentWorker(job)
+        w.finished_ok.connect(done)
+        w.failed.connect(self._on_image_scan_failed)
+        self._img_scan_worker = w
+        if then_suggest:
+            self._pending_img_suggest = True
+        w.start()
+
+    def _on_image_scan_failed(self, _err) -> None:
+        self._img_scan_worker = None
+
+    def provider(self) -> Any:
+        """Build a provider using the model chosen in the picker ('(auto)'
+        -> the active provider's default), or an Auto/Manual routing
+        override set by :meth:`apply_routing` for the current run."""
+        if self._routed_provider or self._routed_model:
+            provider = self._routed_provider or self.ctx.config.active_provider
+            return self.ctx.build_provider_for(provider, self._routed_model or None)
+        model = self._combo.currentData()
+        return self.ctx.build_provider_for(self.ctx.config.active_provider, model or None)
+
+    def apply_routing(self, instruction: str) -> None:
+        """Auto Model Routing for the AI-Edit surface (always a CODING
+        task). Sets the routing override :meth:`provider` honours."""
+        from cowork_local.core.routing.models import TaskType
+
+        self._routed_provider = None
+        self._routed_model = None
+        cur_provider = self.ctx.config.active_provider
+        picked = self._combo.currentData()
+        cur_model = picked or self.ctx.config.provider_conf(cur_provider).get("model", "")
+        decision = self.ctx.routing_application().route_turn(
+            "ai_edit", instruction, cur_provider, cur_model,
+            task_type=TaskType.CODING, confirm=self._confirm_switch,
+        )
+        if not decision.switched:
+            return
+        self._routed_provider, self._routed_model = decision.target()
+        self._on_status(tr(
+            "routing.switched_notice",
+            model=decision.model, task=decision.task_type,
+            gain=f"{decision.score_gain:.2f}"))
+
+    _IMAGE_WORDS = ("image", "picture", "photo", "illustration", "icon", "logo", "diagram",
+                    "ảnh", "hình", "minh họa", "biểu tượng", "画像", "イラスト")
+
+    def maybe_suggest_image_model(self, instruction: str) -> None:
+        """If the request looks image-related, suggest a suitable image
+        model BEFORE running — active provider first, then ALL providers."""
+        from cowork_local.core import image_gen
+        low = (instruction or "").lower()
+        if not any(w in low for w in self._IMAGE_WORDS):
+            return
+        picked = self._combo.currentData()
+        if picked and image_gen.looks_like_image_model(picked):
+            return
+        local = image_gen.suggest_image_model(self._models)
+        if local:
+            self._on_status(tr("folder.ai_image_suggest", model=local))
+            return
+        if self._all_image_models:
+            self._suggest_cross_provider_image()
+        elif self._img_scan_worker is not None:
+            self._pending_img_suggest = True
+        else:
+            self._scan_all_image_models(then_suggest=True)
+
+    def _suggest_cross_provider_image(self) -> None:
+        from cowork_local.config import PROVIDER_LABELS
+        if not self._all_image_models:
+            picked = self._combo.currentData()
+            if picked:
+                self._on_status(tr("folder.ai_image_use_selected", model=picked))
+            else:
+                self._on_status(tr("folder.ai_image_none"))
+            return
+        seen, lines = set(), []
+        for key, model in self._all_image_models:
+            tag = (key, model)
+            if tag in seen:
+                continue
+            seen.add(tag)
+            lines.append(f"• {model}  ({PROVIDER_LABELS.get(key, key)})")
+            if len(lines) >= 5:
+                break
+        self._on_status(tr("folder.ai_image_suggest_all") + "\n" + "\n".join(lines))
+
+    def image_model(self) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+        """Resolve ``(model, base_url, api_key)`` for image generation,
+        searching ALL providers — see the module docstring for priority
+        order (picked model if image-capable -> active provider's image
+        model -> any other provider's -> fall back to the picked model)."""
+        from cowork_local.core import image_gen
+        picked = self._combo.currentData()
+        if picked and image_gen.looks_like_image_model(picked):
+            return picked, None, None
+        local = image_gen.suggest_image_model(self._models)
+        if local:
+            return local, None, None
+        for key, model in self._all_image_models:
+            conf = self.ctx.config.provider_conf(key)
+            return model, (conf.get("base_url") or None), (conf.get("api_key") or None)
+        return (picked or None), None, None
+
+
+__all__ = ["AiEditModelResolver"]

presentation/folder/ai_edit_pipeline.py

@@ -0,0 +1,372 @@
+"""AiEditPipeline — the plan-then-edit-then-apply state machine behind the
+AI-Edit panel (R08-T12, extracted from ``ui/folder_tab.py::FolderTab``,
+lines 1068-1097/1119-1146/1147-1467 of the original 1587-line file:
+``_ai_start`` through ``_ai_failed``, minus the queue/busy-badge bookkeeping
+which stays on ``ai_file_editor_dialog.py::AiFileEditorDialog`` — see that
+module's docstring for the split rationale).
+
+A plain (non-Qt-widget) helper composed BY ``AiFileEditorDialog`` — same
+composition-to-respect-the-400-line-cap pattern as
+``office_document_renderer.py``. Talks to the file only through
+``document_preview_manager.py``'s public API (``ensure_editable_for_ai``,
+``write_content``, ``create_new_file``) — it never touches disk itself.
+"""
+from __future__ import annotations
+
+import difflib
+import os
+from pathlib import Path
+from typing import Optional
+
+from cowork_local.application.workspaces.ai_edit_output import parse_ai_output
+from cowork_local.core.worker import AgentWorker
+from cowork_local.i18n import tr
+from cowork_local.theme import current_palette
+
+
+class AiEditPipeline:
+    """Runs one instruction through PLAN -> EDIT -> (review) -> APPLY/DISCARD.
+
+    Args:
+        owner: the ``AiFileEditorDialog`` — supplies ``ai_chat``, ``preview``
+            (``DocumentPreviewManager``), ``resolver``
+            (``AiEditModelResolver``), ``ctx``, ``cowork_context()``, and is
+            told about status changes via ``on_busy_changed``/``on_flag_done``
+            so the panel's queue/badge bookkeeping stays in one place.
+    """
+
+    def __init__(self, owner) -> None:
+        self._owner = owner
+        self.worker: Optional[AgentWorker] = None
+        self.pending: Optional[dict] = None   # proposed content awaiting confirmation
+        self._ctx: dict = {}
+        self._prompt_usage: dict = {"in": 0, "out": 0, "cache": 0, "cost": 0.0}
+        self._running_file = ""
+
+    def start(self, instruction: str) -> None:
+        """Begin processing one instruction. Assumes the pipeline is idle
+        (the panel's queue calls this when the previous run finishes)."""
+        o = self._owner
+        preview = o.preview
+        editable = preview.stack.currentWidget() is preview.editor
+        if not editable:
+            editable = preview.ensure_editable_for_ai()
+        o.resolver.maybe_suggest_image_model(instruction)
+        o.resolver.apply_routing(instruction)   # may switch to the best coding model
+        has_file = editable and bool(preview.current_file)
+        self._running_file = Path(preview.current_file).name if has_file else tr("folder.ai_new_file")
+        o.set_busy(True)
+        o.status_message.emit(tr("folder.ai_running", name=self._running_file))
+        # Two phases so the PLAN is shown INLINE *before* the edit runs.
+        self._ctx = {
+            "filename": Path(preview.current_file).name if has_file else "",
+            "content": preview.editor.toPlainText() if has_file else "",
+            "convo": o.cowork_context(),
+            "instruction": instruction,
+            "provider": o.resolver.provider(),
+            "plan": "",
+            "edit_kind": preview.edit_kind,
+        }
+        self._prompt_usage = {"in": 0, "out": 0, "cache": 0, "cost": 0.0}
+        self._run_plan()
+
+    # ---- usage accounting (like Cowork's per-message footer) --------------- #
+    def _add_usage(self, usage) -> None:
+        if not isinstance(usage, dict):
+            return
+        tot = self._prompt_usage
+        tot["in"] += int(usage.get("in", 0) or 0)
+        tot["out"] += int(usage.get("out", 0) or 0)
+        tot["cache"] += int(usage.get("cache", 0) or 0)
+        tot["cost"] += float(usage.get("cost_usd", 0.0) or 0.0)
+
+    def _show_usage(self, bubble) -> None:
+        tot = self._prompt_usage
+        if bubble is None or not (tot["in"] or tot["out"]):
+            return
+        from cowork_local.core import model_pricing as mp, usage_tracker as ut
+        pricing = {**ut.DEFAULT_PRICING, **(self._owner.ctx.config.data.get("usage") or {})}
+        line = (f"↓{mp.format_tokens(int(tot['in']))} ↑{mp.format_tokens(int(tot['out']))} "
+                f"▤{mp.format_tokens(int(tot['in'] + tot['out'] + tot['cache']))} "
+                f"{ut.format_cost(tot['cost'], pricing)}")
+        try:
+            bubble.add_usage(line)
+        except Exception:  # noqa: BLE001 - a usage footer must never break the edit
+            pass
+
+    # ---- phase 1: plan ------------------------------------------------------- #
+    def _run_plan(self) -> None:
+        o = self._owner
+        c = self._ctx
+        plan_bubble = o.ai_chat.add_plan(tr("folder.ai_planning"))
+        o.ai_chat.scroll_to_bottom()
+
+        def job(worker):
+            from cowork_local.core import usage_tracker as ut
+            from cowork_local.core.co4e_runner import _usage_delta
+            provider = c["provider"]
+            messages = [{"role": "system", "content":
+                         "You are an AI file editor. Give a SHORT numbered plan (2-4 steps) for "
+                         "the requested change. Plan ONLY — do NOT output any code."}]
+            if c["convo"]:
+                messages.append({"role": "system",
+                                 "content": "Context from the user's Cowork conversation:\n" + c["convo"]})
+            messages.append({"role": "user", "content":
+                             f"File: {c['filename']}\n\nCurrent content:\n```\n{c['content']}\n```\n\n"
+                             f"Request: {c['instruction']}"})
+            ut.set_context("folder", c.get("filename") or "AI edit")
+            ut.begin_accumulation(); base = ut.accumulated()
+            try:
+                r = provider.chat(messages, tools=None, cancel=worker.is_cancelled)
+                txt = r.get("content", "") if isinstance(r, dict) else str(r)
+                usage = _usage_delta(base, o.ctx.config)
+            finally:
+                ut.end_accumulation()
+            return {"plan": provider.strip_think(txt) or "", "usage": usage}
+
+        worker = AgentWorker(job)
+        worker.finished_ok.connect(lambda res, b=plan_bubble: self._plan_done(res, b))
+        worker.failed.connect(lambda err, b=plan_bubble: self._failed(err, b))
+        self.worker = worker
+        worker.start()
+
+    def _plan_done(self, result, plan_bubble) -> None:
+        self._add_usage((result or {}).get("usage"))
+        plan = ((result or {}).get("plan") or "").strip()
+        self._ctx["plan"] = plan
+        plan_bubble.set_plain(plan or tr("folder.ai_empty"))
+        self._owner.ai_chat.scroll_to_bottom()
+        self._run_edit()
+
+    # ---- phase 2: execute (edit the file) ------------------------------------ #
+    def _run_edit(self) -> None:
+        o = self._owner
+        c = self._ctx
+        bubble = o.ai_chat.add_assistant(tr("folder.ai_edit"))
+        o.ai_chat.scroll_to_bottom()
+
+        pptx_note = ("\nThis is a PPTX shown as marker blocks '### Slide N / Box M', where N is the "
+                     "1-based SLIDE NUMBER and M the box on that slide. When the user refers to a "
+                     "slide by number (e.g. 'edit slide 3'), change ONLY the blocks under '### Slide "
+                     "3' and leave every other slide's block exactly as-is. Each block has fields "
+                     "type/pos/size/font/text (and image for pictures). To change TEXT COLOUR or "
+                     "FONT edit the `font:` line — e.g. `font: name=Arial size=28 bold=1 "
+                     "color=FF0000`. Keep all block markers and structure.") if c["edit_kind"] == "pptx" else ""
+
+        _pptx_words = ("pptx", "powerpoint", "slide", "presentation", "deck",
+                       "スライド", "プレゼン", "trình chiếu", "trinh chieu", "bài thuyết trình")
+        wants_new_pptx = (c["edit_kind"] != "pptx"
+                          and any(w in c["instruction"].lower() for w in _pptx_words))
+        new_pptx_note = ("\nTo CREATE a PowerPoint, name it `FILE: <name>.pptx` and output the slides "
+                         "as marker blocks — one block per shape:\n"
+                         "### Slide 1 / Box 1\ntype: text\npos: 0.5, 0.4\nsize: 9.0, 1.2\n"
+                         "font: name=Calibri size=32 bold=1 color=1F3864\ntext:\nTitle here\n\n"
+                         "### Slide 1 / Box 2\ntype: text\npos: 0.5, 1.8\nsize: 9.0, 4.5\n"
+                         "text:\nBullet one\nBullet two\n\n"
+                         "Increment the Slide number for each new slide; pos/size are in inches; "
+                         "font color is RRGGBB hex.") if wants_new_pptx else ""
+
+        imggen_note = ""
+        try:
+            from cowork_local.core import image_gen
+            if image_gen.is_configured(o.ctx.config):
+                imggen_note = ("\nYou can also GENERATE an illustration image: add a line "
+                               "`IMAGE_GEN: <describe the image> => <relative/path.png>`. Use a "
+                               "generated image e.g. as a new picture, or (for pptx) set a picture "
+                               "box's `image:` field to that same path to insert it.")
+        except Exception:  # noqa: BLE001
+            pass
+
+        def job(worker):
+            provider = c["provider"]
+            open_note = (f"the currently-open file '{c['filename']}'" if c["filename"]
+                         else "no file is open")
+            messages = [{"role": "system", "content":
+                         "You are an AI file editor inside an app. Following the plan, output the "
+                         "COMPLETE file content in ONE fenced code block (```), and nothing after "
+                         "it. Preserve everything you were not asked to change.\n"
+                         "If the request is to CREATE A NEW file (or a different file than the one "
+                         "open), put a line `FILE: <relative/path/name.ext>` (relative to the "
+                         "current folder) immediately before the code block. Omit FILE to edit the "
+                         f"open file. Right now, {open_note}." + pptx_note + new_pptx_note + imggen_note}]
+            if c["convo"]:
+                messages.append({"role": "system",
+                                 "content": "Context from the user's Cowork conversation:\n" + c["convo"]})
+            if c["plan"]:
+                messages.append({"role": "system", "content": "Plan to follow:\n" + c["plan"]})
+            cur = (f"File: {c['filename']}\n\nCurrent content:\n```\n{c['content']}\n```\n\n"
+                   if c["filename"] else "No file is currently open.\n\n")
+            messages.append({"role": "user", "content": cur + f"Request: {c['instruction']}"})
+
+            def on_text(piece: str) -> None:
+                worker.emit_event({"type": "text", "delta": piece})
+
+            from cowork_local.core import usage_tracker as ut
+            from cowork_local.core.co4e_runner import _usage_delta
+            ut.set_context("folder", c.get("filename") or "AI edit")
+            ut.begin_accumulation(); base = ut.accumulated()
+            try:
+                r = provider.chat(messages, tools=None, on_text=on_text, cancel=worker.is_cancelled)
+                txt = r.get("content", "") if isinstance(r, dict) else str(r)
+                usage = _usage_delta(base, o.ctx.config)
+            finally:
+                ut.end_accumulation()
+            return {"text": provider.strip_think(txt) or "", "usage": usage}
+
+        worker = AgentWorker(job)
+        worker.event.connect(lambda ev, b=bubble: self._stream(ev, b))
+        worker.finished_ok.connect(lambda res, b=bubble: self._done(res, b))
+        worker.failed.connect(lambda err, b=bubble: self._failed(err, b))
+        self.worker = worker
+        worker.start()
+
+    def _stream(self, ev, bubble) -> None:
+        if isinstance(ev, dict) and ev.get("type") == "text":
+            bubble.append_delta(ev.get("delta", ""))
+            self._owner.ai_chat.scroll_to_bottom()
+
+    def _done(self, result, bubble) -> None:
+        o = self._owner
+        self.worker = None
+        o.set_busy(False)
+        self._add_usage((result or {}).get("usage"))
+        self._show_usage(bubble)
+        text = ((result or {}).get("text") or "").strip()
+        target, new_content, summary, image_gens = parse_ai_output(text)
+        if new_content is None and not image_gens:
+            bubble.set_markdown(text or tr("folder.ai_empty"))
+            o.ai_chat.scroll_to_bottom()
+            o.flag_done()
+            return
+        create = bool(target) and (not o.preview.current_file
+                                   or Path(target).name != Path(o.preview.current_file).name)
+        self.pending = {"content": new_content, "target": target if create else None,
+                        "image_gens": image_gens}
+        hint = tr("folder.ai_review_hint")
+        bubble.set_markdown((summary + "\n\n" if summary else "") + "_" + hint + "_")
+        if new_content is not None:
+            old = "" if create else o.preview.editor.toPlainText()
+            diff = "".join(difflib.unified_diff(
+                old.splitlines(keepends=True), new_content.splitlines(keepends=True),
+                fromfile=("(new file)" if create else "current"),
+                tofile=(target if create else "proposed"))) or "(no textual difference)"
+            title = tr("folder.ai_proposed_new", name=target) if create else tr("folder.ai_proposed")
+            o.ai_chat.add_diff(title, diff)
+        if image_gens:
+            listing = "\n".join(f"• {p}  ({prompt[:60]})" for prompt, p in image_gens)
+            o.ai_chat.add_status(tr("folder.ai_image_plan") + "\n" + listing)
+        o.show_confirm_row(True)
+        o.ai_chat.scroll_to_bottom()
+        name = target if create else self._running_file
+        o.status_message.emit(tr("folder.ai_proposed_status", name=name))
+        o.set_review_status("● " + hint, current_palette().warning)
+
+    # ---- apply / discard ------------------------------------------------------ #
+    def apply(self) -> None:
+        """Confirmed by the user. If the edit GENERATES images, ask the
+        image gate then generate them (off-thread) before finalising."""
+        if not self.pending:
+            return
+        p = self.pending
+        self.pending = None
+        self._owner.show_confirm_row(False)
+        if p.get("image_gens"):
+            from PySide6.QtWidgets import QMessageBox
+            if QMessageBox.question(self._owner, tr("folder.ai_image_confirm_title"),
+                                    tr("folder.ai_image_confirm_gen")) != QMessageBox.Yes:
+                self._owner.status_message.emit(tr("folder.ai_image_declined"))
+                return
+            self._generate_then_finalize(p)
+            return
+        self._finalize_apply(p)
+
+    def _generate_then_finalize(self, p: dict) -> None:
+        o = self._owner
+        imgs = p.get("image_gens") or []
+        root = os.path.normpath(o.preview.root)
+        img_model, img_base, img_key = o.resolver.image_model()
+        o.set_busy(True)
+        o.status_message.emit(tr("folder.ai_generating"))
+
+        def job(worker):
+            from cowork_local.core import image_gen
+            results = []
+            for prompt, rel in imgs:
+                dest = rel if os.path.isabs(rel) else os.path.join(root, rel)
+                dest = os.path.normpath(dest)
+                if os.path.commonpath([dest, root]) != root:
+                    results.append((rel, False, "path escapes the folder"))
+                    continue
+                try:
+                    os.makedirs(os.path.dirname(dest) or root, exist_ok=True)
+                except OSError as exc:
+                    results.append((rel, False, str(exc)))
+                    continue
+                ok, msg = image_gen.generate_image(o.ctx.config, prompt, dest,
+                                                   model=img_model, base_url=img_base, api_key=img_key)
+                results.append((dest, ok, msg))
+            return {"results": results}
+
+        worker = AgentWorker(job)
+        worker.finished_ok.connect(lambda res, pp=p: self._images_done(res, pp))
+        worker.failed.connect(lambda err, pp=p: self._images_done({"results": [], "err": err}, pp))
+        self.worker = worker
+        worker.start()
+
+    def _images_done(self, res: dict, p: dict) -> None:
+        o = self._owner
+        self.worker = None
+        o.set_busy(False)
+        created = []
+        for dest, ok, msg in res.get("results", []):
+            if ok:
+                created.append(dest)
+                o.ai_chat.add_success("✓ " + tr("folder.ai_image_created", name=Path(dest).name))
+            else:
+                o.ai_chat.add_error(tr("folder.ai_image_failed", err=msg))
+        self._finalize_apply(p, images_done=True)
+        if p.get("content") is None and not p.get("target") and created:
+            o.preview.open_file(created[0], reset_ai=False)
+
+    def _finalize_apply(self, p: dict, images_done: bool = False) -> None:
+        o = self._owner
+        content = p.get("content")
+        target = p.get("target")
+        if content is None:
+            o.ai_chat.scroll_to_bottom()
+            o.flag_done()
+            o.status_message.emit(tr("folder.ai_done", name=self._running_file))
+            return
+        if target:
+            dest = o.preview.create_new_file(target, content)
+            if dest is None:
+                return
+            o.ai_chat.add_success("✓ " + tr("folder.ai_created", name=Path(dest).name))
+            o.status_message.emit(tr("folder.ai_created", name=Path(dest).name))
+        else:
+            o.preview.editor.setPlainText(content)     # live update in the editor/preview
+            o.preview.write_content(content, skip_image_confirm=images_done)
+            o.ai_chat.add_success("✓ " + tr("folder.ai_applied"))
+            o.status_message.emit(tr("folder.ai_done", name=self._running_file))
+        o.ai_chat.scroll_to_bottom()
+        o.flag_done()
+
+    def discard(self) -> None:
+        o = self._owner
+        self.pending = None
+        o.show_confirm_row(False)
+        o.ai_chat.add_status(tr("folder.ai_discarded"))
+        o.ai_chat.scroll_to_bottom()
+        o.set_review_status("", None)
+        o.maybe_dequeue()   # discarding resolves the gate → run the next queued edit
+
+    def _failed(self, err, bubble) -> None:
+        o = self._owner
+        self.worker = None
+        bubble.set_markdown(tr("folder.ai_error", err=err))
+        o.set_busy(False)
+        o.status_message.emit(tr("folder.ai_error", err=err))
+        o.flag_done()
+
+
+__all__ = ["AiEditPipeline"]

presentation/folder/ai_file_editor_dialog.py

@@ -0,0 +1,237 @@
+"""AiFileEditorDialog — the collapsible AI-edit panel of the Folder Explorer
+(R08-T12, extracted from ``ui/folder_tab.py::FolderTab``, lines 701-800/
+1039-1066/1099-1118/1468-1517 of the original 1587-line file:
+``_build_ai_panel``, panel open/reset, the instruction queue, and the busy/
+done status line).
+
+Despite the name (matching ``docs/refactor/Feature_Architecture_Proposal.md``'s
+R08-T12 file list), this is an inline collapsible ``QWidget`` panel, not a
+modal ``QDialog`` — exactly like the original ``_ai_panel`` was.
+
+Composes two helpers to stay under the 400-line cap:
+``ai_edit_model_resolver.py::AiEditModelResolver`` (which provider/model
+answers a run) and ``ai_edit_pipeline.py::AiEditPipeline`` (the actual
+plan-then-edit-then-apply state machine). This class owns the widget itself,
+the instruction queue, and the busy/done status line/badge — the parts that
+needed to stay together because the queue decides when the pipeline's next
+``start()`` call happens.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from PySide6.QtWidgets import (
+    QComboBox, QHBoxLayout, QLabel, QLineEdit, QPushButton, QVBoxLayout, QWidget,
+)
+from PySide6.QtCore import Signal
+
+from cowork_local.i18n import on_language_changed, tr
+from cowork_local.presentation.folder.ai_edit_model_resolver import AiEditModelResolver
+from cowork_local.presentation.folder.ai_edit_pipeline import AiEditPipeline
+from cowork_local.theme import current_palette
+from cowork_local.ui.chat_view import ChatView
+
+
+class AiFileEditorDialog(QWidget):
+    """Collapsible panel: a Cowork-style inline chat timeline, this panel's
+    OWN model picker + routing toggle, an instruction box, and an Apply/
+    Discard confirmation bar for the proposed edit.
+
+    Args:
+        ctx: ``AppContext``.
+        preview: ``document_preview_manager.py::DocumentPreviewManager`` —
+            every read/write of the actual file content goes through it.
+        cowork: the shared Cowork tab (optional) — its recent messages are
+            included as background context for the edit.
+    """
+
+    status_message = Signal(str)
+    badge_changed = Signal(str)   # "" | " ⏳" | " ✓" — the shell mirrors this onto its toggle button
+
+    def __init__(self, ctx, preview, cowork=None, parent=None):
+        super().__init__(parent)
+        self.ctx = ctx
+        self.preview = preview
+        self._cowork = cowork
+        self._ai_queue: List[str] = []
+        self.pipeline = AiEditPipeline(self)
+        self.resolver: Optional[AiEditModelResolver] = None   # built after ai_model_combo exists
+
+        preview.ai_reset_requested.connect(self.reset_conversation)
+        preview.status_message.connect(self.status_message.emit)
+
+        v = QVBoxLayout(self)
+        v.setContentsMargins(6, 0, 0, 0)
+        v.setSpacing(4)
+        title_row = QHBoxLayout()
+        self._ai_title = QLabel(tr("folder.ai_edit"))
+        self._ai_title.setStyleSheet("font-weight:600;")
+        title_row.addWidget(self._ai_title)
+        title_row.addStretch(1)
+        self._ai_status = QLabel("")
+        self._ai_status.setObjectName("hint")
+        title_row.addWidget(self._ai_status)
+        v.addLayout(title_row)
+        self.ai_chat = ChatView()
+        v.addWidget(self.ai_chat, 1)
+
+        model_row = QHBoxLayout()
+        self._ai_model_lbl = QLabel(tr("folder.ai_model_label"))
+        self._ai_model_lbl.setObjectName("hint")
+        model_row.addWidget(self._ai_model_lbl)
+        self.ai_model_combo = QComboBox()
+        self.ai_model_combo.addItem(tr("folder.ai_model_auto"), None)
+        model_row.addWidget(self.ai_model_combo, 1)
+        from cowork_local.ui.routing_toggle import RoutingToggle
+        self.ai_routing_toggle = RoutingToggle(self.ctx, "ai_edit")
+        model_row.addWidget(self.ai_routing_toggle)
+        v.addLayout(model_row)
+        self.resolver = AiEditModelResolver(
+            ctx, self.ai_model_combo, self.ai_chat.add_status, self._confirm_routing_switch)
+
+        row = QHBoxLayout()
+        self.ai_input = QLineEdit()
+        self.ai_input.setPlaceholderText(tr("folder.ai_placeholder"))
+        self.ai_input.returnPressed.connect(self._ai_send)
+        row.addWidget(self.ai_input, 1)
+        self.ai_send_btn = QPushButton(tr("folder.ai_send"))
+        self.ai_send_btn.setObjectName("primary")
+        self.ai_send_btn.clicked.connect(self._ai_send)
+        row.addWidget(self.ai_send_btn)
+        v.addLayout(row)
+
+        self._ai_confirm_row = QWidget()
+        cf = QHBoxLayout(self._ai_confirm_row)
+        cf.setContentsMargins(0, 0, 0, 0)
+        cf.addStretch(1)
+        self._ai_discard_btn = QPushButton(tr("folder.ai_discard"))
+        self._ai_discard_btn.clicked.connect(self.pipeline.discard)
+        cf.addWidget(self._ai_discard_btn)
+        self._ai_apply_btn = QPushButton(tr("folder.ai_apply"))
+        self._ai_apply_btn.setObjectName("primary")
+        self._ai_apply_btn.clicked.connect(self.pipeline.apply)
+        cf.addWidget(self._ai_apply_btn)
+        self._ai_confirm_row.setVisible(False)
+        v.addWidget(self._ai_confirm_row)
+
+        on_language_changed(self.retranslate)
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self._ai_title.setText(tr("folder.ai_edit"))
+        self.ai_input.setPlaceholderText(tr("folder.ai_placeholder"))
+        self.ai_send_btn.setText(tr("folder.ai_send"))
+        self._ai_model_lbl.setText(tr("folder.ai_model_label"))
+        if self.ai_model_combo.count() >= 1 and self.ai_model_combo.itemData(0) is None:
+            self.ai_model_combo.setItemText(0, tr("folder.ai_model_auto"))
+        self._ai_apply_btn.setText(tr("folder.ai_apply"))
+        self._ai_discard_btn.setText(tr("folder.ai_discard"))
+
+    # ---- called by the shell (header button, splitter owner) --------------- #
+    def on_opened(self) -> None:
+        """The shell's AI toggle button was just checked ON."""
+        self.ai_input.setFocus()
+        if self.resolver.should_refresh():
+            self.resolver.refresh()
+        if self.pipeline.worker is None:
+            self.badge_changed.emit("")
+            self._ai_status.setText("")
+
+    def reset_conversation(self) -> None:
+        """Clear the AI-edit chat so each file starts a clean conversation. A
+        run in progress (editing the previous file) is left untouched — the
+        reset applies the next time a file is opened while idle."""
+        if self.pipeline.worker is not None:
+            return
+        self.ai_chat.clear()
+        self.badge_changed.emit("")
+        self.pipeline.pending = None
+        self._ai_confirm_row.setVisible(False)
+        self._ai_status.setText("")
+
+    def cowork_context(self) -> str:
+        """The whole Cowork conversation (recent turns) as background context."""
+        cw = self._cowork
+        msgs = getattr(cw, "messages", None) if cw is not None else None
+        if not msgs:
+            return ""
+        lines = [f"{m['role']}: {str(m['content'])[:1000]}"
+                 for m in msgs if m.get("role") in ("user", "assistant") and m.get("content")]
+        return "\n".join(lines[-12:])
+
+    # ---- send / queue -------------------------------------------------------- #
+    def _ai_send(self) -> None:
+        if not self.preview.root:
+            self.ai_chat.add_error(tr("folder.ai_no_file"))
+            return
+        instruction = self.ai_input.text().strip()
+        if not instruction:
+            return
+        self.ai_input.clear()
+        self.ai_chat.add_user(instruction)
+        # QUEUE: while a run is active OR a proposal is awaiting Apply/Discard,
+        # hold the new instruction and run it once the pipeline goes idle.
+        if self.pipeline.worker is not None or self.pipeline.pending is not None:
+            self._ai_queue.append(instruction)
+            self.ai_chat.add_status(tr("folder.ai_queued", n=len(self._ai_queue)))
+            self._update_queue_status()
+            return
+        self.pipeline.start(instruction)
+
+    def _update_queue_status(self) -> None:
+        n = len(self._ai_queue)
+        if n:
+            self._ai_status.setText("⏳ " + tr("folder.ai_status_running")
+                                    + "  ·  " + tr("folder.ai_queue_count", n=n))
+            self._ai_status.setStyleSheet(f"color:{current_palette().accent};")
+
+    def maybe_dequeue(self) -> None:
+        """When the pipeline is fully idle, start the next queued instruction."""
+        if self.pipeline.worker is not None or self.pipeline.pending is not None:
+            return
+        if not self._ai_queue:
+            return
+        nxt = self._ai_queue.pop(0)
+        self._update_queue_status()
+        self.pipeline.start(nxt)
+
+    # ---- pipeline callbacks (see ai_edit_pipeline.py) ------------------------- #
+    def set_busy(self, busy: bool) -> None:
+        self.ai_input.setEnabled(not busy)
+        self.ai_send_btn.setEnabled(not busy)
+        if busy:
+            self._ai_status.setText("⏳ " + tr("folder.ai_status_running"))
+            self._ai_status.setStyleSheet(f"color:{current_palette().accent};")
+            self.badge_changed.emit(" ⏳")   # visible even when collapsed
+        else:
+            self._ai_status.setText("")
+            self.badge_changed.emit("")
+
+    def flag_done(self) -> None:
+        """After a background run, show a 'done' badge so the user notices
+        the result when they return to the tab; cleared on reopen. If more
+        instructions are queued, start the next one instead."""
+        if self.pipeline.worker is None and self.pipeline.pending is None and self._ai_queue:
+            self.maybe_dequeue()
+            return
+        self._ai_status.setText("✓ " + tr("folder.ai_status_done"))
+        self._ai_status.setStyleSheet(f"color:{current_palette().success};")
+        self.badge_changed.emit(" ✓")
+
+    def show_confirm_row(self, visible: bool) -> None:
+        self._ai_confirm_row.setVisible(visible)
+
+    def set_review_status(self, text: str, color) -> None:
+        self._ai_status.setText(text)
+        if color:
+            self._ai_status.setStyleSheet(f"color:{color};")
+
+    def _confirm_routing_switch(self, decision) -> bool:
+        """Manual mode: ask before moving this AI-Edit run to another model."""
+        from cowork_local.ui.routing_toggle import confirm_switch
+
+        timeout = float(self.ctx.config.routing.get("confirm_timeout_sec", 60) or 60)
+        return bool(confirm_switch(self, decision, timeout))
+
+
+__all__ = ["AiFileEditorDialog"]

presentation/folder/code_editor.py

@@ -0,0 +1,190 @@
+"""CodeEditor — the VS-Code-style code/text editor widget (R08-T12, split
+out of ``document_preview_manager.py`` to keep that file under the 400-line
+cap; originally ``ui/folder_tab.py``, lines 61-236 of the original
+1587-line file: the Pygments token-colour helper, ``PygmentsHighlighter``,
+``_LineNumbers``, ``CodeEditor``).
+"""
+from __future__ import annotations
+
+from PySide6.QtCore import QRect, QSize, Qt, QTimer
+from PySide6.QtGui import QColor, QFont, QPainter, QSyntaxHighlighter, QTextCharFormat
+from PySide6.QtWidgets import QPlainTextEdit, QWidget
+
+from cowork_local.theme import current_palette
+
+_MAX_HIGHLIGHT_CHARS = 300_000     # skip colouring huge files (keeps typing snappy)
+
+
+# ── VS-Code-Dark+-ish token palette ────────────────────────────────────────
+def _fmt(color: str, *, italic: bool = False, bold: bool = False) -> QTextCharFormat:
+    f = QTextCharFormat()
+    f.setForeground(QColor(color))
+    if italic:
+        f.setFontItalic(True)
+    if bold:
+        f.setFontWeight(QFont.Bold)
+    return f
+
+
+class PygmentsHighlighter(QSyntaxHighlighter):
+    """Colour the whole document with Pygments and apply per-block. Re-lexes the
+    full text (debounced) so multi-line strings/comments colour correctly."""
+
+    def __init__(self, document):
+        super().__init__(document)
+        from pygments.lexers.special import TextLexer
+        self._lexer = TextLexer(stripnl=False)
+        self._ranges: list[tuple[int, int, QTextCharFormat]] = []
+        self._rules = self._build_rules()
+        self._timer = QTimer(self)
+        self._timer.setSingleShot(True)
+        self._timer.setInterval(250)
+        self._timer.timeout.connect(self._retokenize)
+        document.contentsChanged.connect(self._timer.start)
+
+    @staticmethod
+    def _build_rules():
+        from pygments.token import (
+            Comment, Error, Keyword, Name, Number, Operator, Punctuation, String,
+        )
+        p = current_palette()
+        return [
+            (Comment, _fmt(p.code_comment, italic=True)),
+            (Keyword.Type, _fmt(p.code_type)),
+            (Keyword, _fmt(p.code_keyword)),
+            (Name.Function, _fmt(p.code_func)),
+            (Name.Class, _fmt(p.code_type)),
+            (Name.Decorator, _fmt(p.code_func)),
+            (Name.Builtin, _fmt(p.code_type)),
+            (Name.Tag, _fmt(p.code_keyword)),
+            (Name.Attribute, _fmt(p.code_attr)),
+            (String.Doc, _fmt(p.code_comment, italic=True)),
+            (String, _fmt(p.code_string)),
+            (Number, _fmt(p.code_number)),
+            (Operator, _fmt(p.code_fg)),
+            (Punctuation, _fmt(p.code_fg)),
+            (Error, _fmt(p.code_error)),
+        ]
+
+    def set_filename(self, filename: str, text: str = "") -> None:
+        from pygments.lexers import get_lexer_for_filename, guess_lexer
+        from pygments.lexers.special import TextLexer
+        from pygments.util import ClassNotFound
+        try:
+            self._lexer = get_lexer_for_filename(filename, stripnl=False)
+        except ClassNotFound:
+            try:
+                self._lexer = guess_lexer(text) if text.strip() else TextLexer()
+            except ClassNotFound:
+                self._lexer = TextLexer(stripnl=False)
+        self._retokenize()
+
+    def _fmt_for(self, tok):
+        for ttype, fmt in self._rules:
+            if tok in ttype:
+                return fmt
+        return None
+
+    def _retokenize(self) -> None:
+        from pygments import lex
+        text = self.document().toPlainText()
+        self._ranges = []
+        if len(text) <= _MAX_HIGHLIGHT_CHARS:
+            pos = 0
+            for tok, val in lex(text, self._lexer):
+                fmt = self._fmt_for(tok)
+                if fmt is not None and val:
+                    self._ranges.append((pos, pos + len(val), fmt))
+                pos += len(val)
+        self.rehighlight()
+
+    def highlightBlock(self, text: str) -> None:  # noqa: N802 - Qt override
+        if not self._ranges:
+            return
+        bstart = self.currentBlock().position()
+        bend = bstart + len(text)
+        for start, end, fmt in self._ranges:
+            if end <= bstart or start >= bend:
+                continue
+            s = max(start, bstart) - bstart
+            e = min(end, bend) - bstart
+            if e > s:
+                self.setFormat(s, e - s, fmt)
+
+
+class _LineNumbers(QWidget):
+    def __init__(self, editor):
+        super().__init__(editor)
+        self._editor = editor
+
+    def sizeHint(self) -> QSize:
+        return QSize(self._editor.line_number_width(), 0)
+
+    def paintEvent(self, event):  # noqa: N802
+        self._editor.paint_line_numbers(event)
+
+
+class CodeEditor(QPlainTextEdit):
+    """A dark, monospaced editor with a line-number gutter + Pygments colouring —
+    the Sublime/VS-Code look for viewing & editing source files."""
+
+    def __init__(self):
+        super().__init__()
+        self.setObjectName("codeEditor")
+        self.setLineWrapMode(QPlainTextEdit.NoWrap)
+        self.setTabStopDistance(4 * self.fontMetrics().horizontalAdvance(" "))
+        font = QFont("Consolas")
+        font.setStyleHint(QFont.Monospace)
+        font.setPointSize(10)
+        self.setFont(font)
+        self._gutter = _LineNumbers(self)
+        self.blockCountChanged.connect(lambda _=0: self._update_gutter_width())
+        self.updateRequest.connect(self._on_update_request)
+        self._highlighter = PygmentsHighlighter(self.document())
+        self._update_gutter_width()
+
+    def line_number_width(self) -> int:
+        digits = max(2, len(str(max(1, self.blockCount()))))
+        return 12 + self.fontMetrics().horizontalAdvance("9") * digits
+
+    def _update_gutter_width(self) -> None:
+        self.setViewportMargins(self.line_number_width(), 0, 0, 0)
+
+    def _on_update_request(self, rect, dy: int) -> None:
+        if dy:
+            self._gutter.scroll(0, dy)
+        else:
+            self._gutter.update(0, rect.y(), self._gutter.width(), rect.height())
+        if rect.contains(self.viewport().rect()):
+            self._update_gutter_width()
+
+    def resizeEvent(self, event):  # noqa: N802
+        super().resizeEvent(event)
+        cr = self.contentsRect()
+        self._gutter.setGeometry(QRect(cr.left(), cr.top(), self.line_number_width(), cr.height()))
+
+    def paint_line_numbers(self, event) -> None:
+        p = current_palette()
+        painter = QPainter(self._gutter)
+        painter.fillRect(event.rect(), QColor(p.code_gutter_bg))
+        block = self.firstVisibleBlock()
+        num = block.blockNumber()
+        top = self.blockBoundingGeometry(block).translated(self.contentOffset()).top()
+        bottom = top + self.blockBoundingRect(block).height()
+        painter.setPen(QColor(p.code_gutter_fg))
+        while block.isValid() and top <= event.rect().bottom():
+            if block.isVisible() and bottom >= event.rect().top():
+                painter.drawText(0, int(top), self._gutter.width() - 6,
+                                 self.fontMetrics().height(), Qt.AlignRight,
+                                 str(num + 1))
+            block = block.next()
+            top = bottom
+            bottom = top + self.blockBoundingRect(block).height()
+            num += 1
+
+    def load_file(self, path: str, text: str) -> None:
+        self.setPlainText(text)
+        self._highlighter.set_filename(path, text)
+
+
+__all__ = ["CodeEditor", "PygmentsHighlighter"]

presentation/folder/document_preview_manager.py

@@ -0,0 +1,304 @@
+"""DocumentPreviewManager — the view/edit pane of the Folder Explorer
+(R08-T12, extracted from ``ui/folder_tab.py::FolderTab``, lines 295-373/
+410-449/649-699 of the original 1587-line file: the preview
+``QStackedWidget`` + open/save/create/external dispatch. HTML/PPTX/Excel/
+PDF/office rendering lives in ``office_document_renderer.py``; the code
+editor widget lives in ``code_editor.py`` — both split out to keep this file
+under the 400-line cap.
+
+**Closes the R06-T05 loop**: ``application/workspaces/file_workspace_service.
+py::FileWorkspaceService`` existed since R06 but had zero production call
+sites (confirmed by grep before this task — ``ui/folder_tab.py`` wrote files
+with raw ``Path.write_text`` instead). Every plain-text write this class does
+(``save``, ``create_new_file``, ``write_content``) now goes through it —
+same path-containment check, same auto ``mkdir``, and (new, from
+``infrastructure/filesystem/file_tools.py::write_file``) a Python-syntax
+warning on a bad ``.py`` write, which the original code never had. A ``.pptx``
+save still goes through ``core/pptx_edit.py`` directly — that's a binary
+package build, not a text write, and ``FileWorkspaceService`` has no opinion
+on it.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QHBoxLayout, QLabel, QPushButton, QScrollArea, QStackedWidget,
+    QTextBrowser, QVBoxLayout, QWidget,
+)
+
+from cowork_local.application.workspaces import FileWorkspaceService
+from cowork_local.application.workspaces.file_preview_helpers import (
+    is_probably_text, pptx_available, read_text,
+)
+from cowork_local.domain.workspaces.workspace_session import WorkspaceSession
+from cowork_local.i18n import tr
+from cowork_local.presentation.folder.code_editor import CodeEditor
+from cowork_local.presentation.folder.office_document_renderer import OfficeDocumentRenderer
+from cowork_local.ui.icons import icon
+from cowork_local.ui.libreoffice_view import DOC_SUFFIXES
+
+_IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".ico"}
+_HTML_SUFFIXES = {".html", ".htm"}
+_PPTX_SUFFIXES = {".pptx"}          # text-editable in-app via python-pptx (no PowerPoint)
+_EXCEL_SUFFIXES = {".xlsx", ".xlsm"}  # viewed as a real table via openpyxl (no LibreOffice)
+_MAX_EDIT_BYTES = 2_000_000        # above this, view read-only / note only
+
+
+class DocumentPreviewManager(QWidget):
+    """View/edit pane: header (file name, Preview⇄Edit toggle, Save, Open
+    externally) above a ``QStackedWidget`` that renders whichever preview a
+    file's suffix calls for."""
+
+    status_message = Signal(str)
+    ai_reset_requested = Signal()   # a DIFFERENT file was opened by the user
+
+    def __init__(self, root: str, parent=None):
+        super().__init__(parent)
+        self._root = root
+        self._file_service = FileWorkspaceService(WorkspaceSession.unscoped(Path(root)))
+        self._office = OfficeDocumentRenderer(self)
+        self._edit_kind: Optional[str] = None   # None | "html" | "pptx"
+        self._current_file: Optional[str] = None
+
+        rl = QVBoxLayout(self)
+        rl.setContentsMargins(0, 0, 0, 0)
+
+        hdr = QHBoxLayout()
+        self.file_label = QLabel("")
+        self.file_label.setStyleSheet("font-weight:600;")
+        self.file_label.setWordWrap(True)
+        hdr.addWidget(self.file_label, 1)
+        self.mode_btn = QPushButton()      # Preview⇄Edit toggle (HTML / PPTX)
+        self.mode_btn.setCheckable(True)
+        self.mode_btn.clicked.connect(self._office.toggle_edit_mode)
+        self.mode_btn.setVisible(False)
+        hdr.addWidget(self.mode_btn)
+        self.save_btn = QPushButton()
+        self.save_btn.setIcon(icon("save"))
+        self.save_btn.setObjectName("primary")
+        self.save_btn.clicked.connect(self.save)
+        self.save_btn.setVisible(False)
+        hdr.addWidget(self.save_btn)
+        self.ext_btn = QPushButton()
+        self.ext_btn.setIcon(icon("upload"))
+        self.ext_btn.clicked.connect(self.open_external)
+        self.ext_btn.setVisible(False)
+        hdr.addWidget(self.ext_btn)
+        rl.addLayout(hdr)
+        # Exposed so the shell can insert its own AI-panel toggle button into
+        # this same header row (between mode_btn and save_btn, matching the
+        # original single-class layout) without this class knowing the AI
+        # panel exists.
+        self.header_layout = hdr
+
+        self.stack = QStackedWidget()
+        self._placeholder = QLabel("")
+        self._placeholder.setObjectName("hint")
+        self._placeholder.setAlignment(Qt.AlignCenter)
+        self.stack.addWidget(self._placeholder)                       # 0
+
+        self.editor = CodeEditor()                                    # 1
+        self.stack.addWidget(self.editor)
+
+        self.web = QTextBrowser()                                     # 2
+        self.web.setOpenExternalLinks(True)
+        self.stack.addWidget(self.web)
+
+        self.doc_view = QTextBrowser()                                # 3
+        self.doc_view.setObjectName("docPreview")
+        self.stack.addWidget(self.doc_view)
+
+        self._img_scroll = QScrollArea()                              # 4
+        self._img_scroll.setWidgetResizable(True)
+        self._img_label = QLabel("")
+        self._img_label.setAlignment(Qt.AlignCenter)
+        self._img_scroll.setWidget(self._img_label)
+        self.stack.addWidget(self._img_scroll)
+
+        rl.addWidget(self.stack, 1)
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self.save_btn.setText(tr("folder.save"))
+        self.ext_btn.setText(tr("folder.open_external"))
+        if not self._current_file:
+            self._placeholder.setText(tr("folder.select_file"))
+        self._retranslate_mode_btn()
+
+    def _retranslate_mode_btn(self) -> None:
+        self.mode_btn.setText(tr("folder.edit") if not self.mode_btn.isChecked()
+                              else tr("folder.preview"))
+
+    # ---- public API used by the shell / AI panel --------------------------- #
+    @property
+    def current_file(self) -> Optional[str]:
+        return self._current_file
+
+    @property
+    def edit_kind(self) -> Optional[str]:
+        return self._edit_kind
+
+    @property
+    def root(self) -> str:
+        return self._root
+
+    def set_root(self, root: str) -> None:
+        self._root = root
+        self._file_service = FileWorkspaceService(WorkspaceSession.unscoped(Path(root)))
+
+    def open_file(self, path: str, reset_ai: bool = True) -> None:
+        # Switching to a DIFFERENT file starts a fresh AI-edit conversation
+        # (reset_ai=False when the AI itself just CREATED this file — keep
+        # that chat). Whether/how to reset is the AI panel's own business —
+        # this class only announces that a genuine file switch happened.
+        if reset_ai and path != self._current_file:
+            self.ai_reset_requested.emit()
+        self._current_file = path
+        self.file_label.setText(path)
+        suffix = Path(path).suffix.lower()
+        self.mode_btn.setVisible(False)
+        self.save_btn.setVisible(False)
+        self.ext_btn.setVisible(False)
+        self._edit_kind = None
+        try:
+            size = os.path.getsize(path)
+        except OSError:
+            size = 0
+
+        if suffix in _IMAGE_SUFFIXES:
+            self._show_image(path)
+        elif suffix in _HTML_SUFFIXES:
+            self._office.show_html(path, mode_preview=True)
+        elif suffix in _PPTX_SUFFIXES and pptx_available():
+            self._office.show_pptx(path, mode_preview=True)
+        elif suffix in _EXCEL_SUFFIXES:
+            self._office.show_excel(path)
+        elif suffix in DOC_SUFFIXES:
+            self._office.show_document(path)
+        elif size > _MAX_EDIT_BYTES or not is_probably_text(path):
+            self._show_binary(path)
+        else:
+            self._show_code(path)
+
+    def ensure_editable_for_ai(self) -> bool:
+        """Make the current file editable in the code editor (switching an
+        HTML preview to edit, or loading a text file). Returns False when
+        there's no file open or it isn't a text/code file."""
+        path = self._current_file
+        if not path or not os.path.isfile(path):
+            return False
+        suffix = Path(path).suffix.lower()
+        if suffix in _HTML_SUFFIXES:
+            self._office.show_html(path, mode_preview=False)
+            return True
+        if suffix in _PPTX_SUFFIXES and pptx_available():
+            self._office.show_pptx(path, mode_preview=False)
+            return True
+        if suffix in DOC_SUFFIXES or suffix in _IMAGE_SUFFIXES:
+            return False
+        if is_probably_text(path):
+            self._show_code(path)
+            return True
+        return False
+
+    def save(self) -> None:
+        if not self._current_file:
+            return
+        try:
+            if self._edit_kind == "pptx":
+                if not self._office.write_pptx(self.editor.toPlainText()):
+                    return
+            else:
+                self._write_plain_text(self._current_file, self.editor.toPlainText())
+            self.status_message.emit(tr("folder.saved", name=Path(self._current_file).name))
+        except Exception as exc:  # noqa: BLE001
+            self.status_message.emit(tr("folder.save_error", err=str(exc)))
+
+    def write_content(self, content: str, skip_image_confirm: bool = False) -> None:
+        """Persist AI-confirmed content to disk AND refresh the preview.
+        pptx text is written back into the deck (no PowerPoint window)."""
+        if not self._current_file:
+            return
+        try:
+            if self._edit_kind == "pptx":
+                if not self._office.write_pptx(content, skip_confirm=skip_image_confirm):
+                    return
+            else:
+                self._write_plain_text(self._current_file, content)
+        except Exception as exc:  # noqa: BLE001
+            self.status_message.emit(tr("folder.save_error", err=str(exc)))
+            return
+        suffix = Path(self._current_file).suffix.lower()
+        if suffix in _HTML_SUFFIXES:
+            self._office.show_html(self._current_file, mode_preview=True)
+        elif suffix in _PPTX_SUFFIXES:
+            self._office.show_pptx(self._current_file, mode_preview=True)
+
+    def create_new_file(self, target: str, content: str) -> Optional[str]:
+        """Create ``target`` (relative to the folder root) with ``content``
+        and open it — like Cowork's save_file. Refuses paths escaping the
+        root (enforced by ``FileWorkspaceService``/``WorkspaceSession``)."""
+        root = os.path.normpath(self._root)
+        dest = target if os.path.isabs(target) else os.path.join(root, target)
+        dest = os.path.normpath(dest)
+        try:
+            if Path(dest).suffix.lower() in _PPTX_SUFFIXES and pptx_available():
+                # A .pptx is a binary package — build a real deck from the
+                # marker text (writing text straight to .pptx would corrupt it).
+                from cowork_local.core import pptx_edit
+                os.makedirs(os.path.dirname(dest) or root, exist_ok=True)
+                pptx_edit.create_pptx_from_text(dest, content)
+            else:
+                self._write_plain_text(dest, content)
+        except Exception as exc:  # noqa: BLE001 - OS error, containment error, or pptx build failure
+            self.status_message.emit(tr("folder.save_error", err=str(exc)))
+            return None
+        self.open_file(dest, reset_ai=False)   # show the new file; keep the AI chat
+        return dest
+
+    def open_external(self) -> None:
+        if self._current_file:
+            from cowork_local.ui.osutil import open_location
+            open_location(self._current_file)
+
+    # ---- writes ------------------------------------------------------------- #
+    def _write_plain_text(self, path: str, content: str) -> None:
+        """Write ``content`` to ``path`` (must resolve inside the current
+        root) via ``FileWorkspaceService`` — same containment check, ``mkdir``
+        and Python-syntax warning the agent's own ``write_file`` tool gets."""
+        rel = os.path.relpath(path, self._root)
+        result = self._file_service.write_file(rel, content)
+        if not result.get("ok"):
+            raise OSError(result.get("output") or "write failed")
+
+    # ---- simple renderers (HTML/PPTX/Excel/PDF/office live in
+    # office_document_renderer.py) --------------------------------------------- #
+    def _show_code(self, path: str) -> None:
+        text = read_text(path)
+        self.editor.setReadOnly(False)
+        self.editor.load_file(path, text)
+        self.save_btn.setVisible(True)
+        self.stack.setCurrentWidget(self.editor)
+
+    def _show_image(self, path: str) -> None:
+        from PySide6.QtGui import QPixmap
+        pix = QPixmap(path)
+        if pix.isNull():
+            self._show_binary(path)
+            return
+        self._img_label.setPixmap(pix)
+        self._img_label.resize(pix.size())
+        self.ext_btn.setVisible(True)
+        self.stack.setCurrentWidget(self._img_scroll)
+
+    def _show_binary(self, path: str) -> None:
+        self._placeholder.setText(tr("folder.binary_file"))
+        self.ext_btn.setVisible(True)
+        self.stack.setCurrentWidget(self._placeholder)
+
+
+__all__ = ["DocumentPreviewManager"]

presentation/folder/folder_tab.py

@@ -0,0 +1,120 @@
+"""FolderTab shell (R08-T12) — assembles
+``workspace_file_tree.py::WorkspaceFileTree``,
+``document_preview_manager.py::DocumentPreviewManager`` and
+``ai_file_editor_dialog.py::AiFileEditorDialog`` behind the splitter/terminal
+layout that used to be inline in ``ui/folder_tab.py::FolderTab.__init__``
+(lines 238-384 of the original 1587-line file).
+
+The AI-panel toggle button (``ai_btn``) lives here because it controls
+things two different children own: the panel's own visibility AND the
+content splitter's sizing — a genuine shell-level concern, not either
+child's.
+"""
+from __future__ import annotations
+
+from PySide6.QtWidgets import QHBoxLayout, QPushButton, QSplitter, QVBoxLayout, QWidget
+from PySide6.QtCore import Qt, Signal
+
+from cowork_local.i18n import on_language_changed, tr
+from cowork_local.presentation.folder.ai_file_editor_dialog import AiFileEditorDialog
+from cowork_local.presentation.folder.document_preview_manager import DocumentPreviewManager
+from cowork_local.presentation.folder.workspace_file_tree import WorkspaceFileTree
+from cowork_local.state import AppContext
+from cowork_local.ui.icons import icon
+
+
+class FolderTab(QWidget):
+    """Two-pane file explorer: directory tree + view/edit pane (+ collapsible
+    AI-edit panel, + collapsible terminal)."""
+
+    status_message = Signal(str)
+
+    def __init__(self, ctx: AppContext, cowork=None):
+        super().__init__()
+        self.ctx = ctx
+        self._root = str(ctx.config.cowork_output_dir())
+
+        root_layout = QVBoxLayout(self)
+        split = QSplitter(Qt.Horizontal)
+
+        self.tree = WorkspaceFileTree(self._root)
+        split.addWidget(self.tree)
+
+        right = QWidget()
+        rl = QVBoxLayout(right)
+        rl.setContentsMargins(0, 0, 0, 0)
+
+        self.preview = DocumentPreviewManager(self._root)
+        self.ai_panel = AiFileEditorDialog(ctx, self.preview, cowork=cowork)
+
+        self.ai_btn = QPushButton()        # expand/collapse the AI-edit panel
+        self.ai_btn.setIcon(icon("sparkle"))
+        self.ai_btn.setCheckable(True)
+        self.ai_btn.clicked.connect(self._toggle_ai_panel)
+        # Same visual position as the original single-class header: between
+        # the Preview⇄Edit toggle and Save (file_label=0, mode_btn=1).
+        self.preview.header_layout.insertWidget(2, self.ai_btn)
+        self.ai_panel.badge_changed.connect(self._on_ai_badge_changed)
+
+        content_split = QSplitter(Qt.Horizontal)
+        content_split.addWidget(self.preview)
+        content_split.addWidget(self.ai_panel)
+        content_split.setStretchFactor(0, 1)
+        content_split.setStretchFactor(1, 0)
+        content_split.setSizes([700, 320])
+        self._content_split = content_split
+        self.ai_panel.setVisible(False)   # default collapsed
+        rl.addWidget(content_split, 1)
+
+        split.addWidget(right)
+        split.setStretchFactor(0, 0)
+        split.setStretchFactor(1, 1)
+        split.setSizes([300, 800])
+        root_layout.addWidget(split, 1)
+
+        # Terminal CLI below the file view — collapsible, default collapsed;
+        # opening it points the shell at the current workspace folder.
+        from cowork_local.ui.terminal_panel import TerminalPanel
+
+        self.terminal = TerminalPanel()
+        self.terminal.set_cwd(self._root)
+        self.terminal.expanded.connect(lambda: self.terminal.set_cwd(self._root))
+        root_layout.addWidget(self.terminal)
+
+        self.tree.file_selected.connect(self.preview.open_file)
+        self.preview.status_message.connect(self.status_message.emit)
+        self.ai_panel.status_message.connect(self.status_message.emit)
+
+        on_language_changed(self._retranslate)
+        self._retranslate()
+
+    # ---- public API ---------------------------------------------------------
+    def set_root(self, path: str) -> None:
+        self.tree.set_root(path)
+        # WorkspaceFileTree silently no-ops on an invalid path (same guard
+        # the original single-class _root setter had) — mirror that here by
+        # only propagating when the tree actually accepted it.
+        if self.tree.root == path:
+            self._root = path
+            self.preview.set_root(path)
+            self.terminal.set_cwd(path)
+
+    def _toggle_ai_panel(self) -> None:
+        show = self.ai_btn.isChecked()
+        self.ai_panel.setVisible(show)
+        if show:
+            self._content_split.setSizes([700, 320])
+            self.ai_panel.on_opened()
+
+    def _on_ai_badge_changed(self, suffix: str) -> None:
+        self.ai_btn.setText(tr("folder.ai_edit") + suffix)
+
+    def _retranslate(self) -> None:
+        self.tree.retranslate()
+        self.preview.retranslate()
+        self.ai_panel.retranslate()
+        self.ai_btn.setText(tr("folder.ai_edit"))
+        self.ai_btn.setToolTip(tr("folder.ai_edit_tooltip"))
+
+
+__all__ = ["FolderTab"]

presentation/folder/office_document_renderer.py

@@ -0,0 +1,269 @@
+"""OfficeDocumentRenderer — HTML/PPTX/Excel/PDF/office-doc preview for
+``document_preview_manager.py`` (R08-T12, split out to keep that file under
+the 400-line cap; originally ``ui/folder_tab.py``, lines 451-647/679-694 of
+the original 1587-line file).
+
+A plain (non-Qt-widget) helper composed BY a ``DocumentPreviewManager``
+rather than a widget of its own: these renderers are tightly coupled to the
+manager's shared ``QStackedWidget``/toolbar/editor — genuinely one screen's
+internal state, not an independent concern — so this is a composition split
+to respect the line-count cap, the same way
+``presentation/scheduling/kanban_board_widget.py`` composes
+``TaskApplicationService`` rather than owning that logic inline.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from PySide6.QtWidgets import QTabWidget, QTableWidget, QTableWidgetItem
+
+from cowork_local.application.workspaces.file_preview_helpers import read_text
+from cowork_local.core.worker import AgentWorker
+from cowork_local.i18n import tr
+from cowork_local.presentation.shared import HAS_WEB_ENGINE
+
+try:
+    from PySide6.QtPdf import QPdfDocument  # noqa: F401
+    from PySide6.QtPdfWidgets import QPdfView  # noqa: F401
+    HAS_PDF = True
+except Exception:  # pragma: no cover - QtPdf not bundled
+    HAS_PDF = False
+
+
+class OfficeDocumentRenderer:
+    """Renders HTML/PPTX/Excel/PDF/office docs into ``owner.stack``.
+
+    ``owner`` is the ``DocumentPreviewManager`` — this class reaches into
+    ``owner.stack``/``owner.editor``/``owner.mode_btn``/``owner.ext_btn``/
+    ``owner.save_btn``/``owner.doc_view``/``owner.web`` because those widgets
+    are shared with the manager's simpler renderers (code/image/binary);
+    duplicating them here would mean two stacked widgets fighting over which
+    one is "the" preview.
+    """
+
+    def __init__(self, owner) -> None:
+        self._owner = owner
+        self._engine = None
+        self._pdf_view = None
+        self._pdf_doc = None
+        self._pdf_tmp: Optional[str] = None
+        self._pdf_cache: dict = {}
+        self._convert_worker = None
+        self._xlsx_view = None
+
+    def show_html(self, path: str, mode_preview: bool) -> None:
+        o = self._owner
+        o._edit_kind = "html"
+        o.mode_btn.setVisible(True)
+        o.mode_btn.setChecked(not mode_preview)   # checked = Edit
+        o._retranslate_mode_btn()
+        if mode_preview:
+            from PySide6.QtCore import QUrl
+            html = read_text(path)
+            engine = self._ensure_engine()
+            if engine is not None:
+                engine.setHtml(html, QUrl.fromLocalFile(path))
+                o.stack.setCurrentWidget(engine)
+            else:
+                o.web.setHtml(html)
+                o.stack.setCurrentWidget(o.web)
+            o.save_btn.setVisible(False)
+        else:
+            o._show_code(path)
+
+    def show_pptx(self, path: str, mode_preview: bool) -> None:
+        """PPTX: Preview renders the slides (PDF via LibreOffice); Edit shows the
+        deck's text (marker-delimited per box) in the editor."""
+        o = self._owner
+        o._edit_kind = "pptx"
+        o.mode_btn.setVisible(True)
+        o.mode_btn.setChecked(not mode_preview)   # checked = Edit
+        o._retranslate_mode_btn()
+        o.ext_btn.setVisible(True)
+        if mode_preview:
+            self.show_document(path)                # PDF render of the slides
+            o.mode_btn.setVisible(True)             # show_document doesn't touch it
+        else:
+            from cowork_local.core.pptx_edit import pptx_to_text
+            try:
+                text = pptx_to_text(path)
+            except Exception as exc:  # noqa: BLE001
+                text = f"[could not read pptx text: {exc}]"
+            o.editor.setReadOnly(False)
+            o.editor.load_file(path + ".txt", text)   # .txt → plain highlighting
+            o.save_btn.setVisible(True)
+            o.stack.setCurrentWidget(o.editor)
+
+    def _ensure_engine(self):
+        """Create the QWebEngineView on first HTML preview (only when WebEngine
+        is safe to use); otherwise stay on the QTextBrowser fallback."""
+        if not HAS_WEB_ENGINE:
+            return None
+        if self._engine is None:
+            try:
+                from PySide6.QtWebEngineWidgets import QWebEngineView
+                self._engine = QWebEngineView()
+                self._owner.stack.addWidget(self._engine)
+            except Exception:  # noqa: BLE001
+                self._engine = None
+        return self._engine
+
+    def toggle_edit_mode(self) -> None:
+        o = self._owner
+        if not o.current_file:
+            return
+        preview = not o.mode_btn.isChecked()   # checked = Edit
+        if o._edit_kind == "pptx":
+            self.show_pptx(o.current_file, mode_preview=preview)
+        else:
+            self.show_html(o.current_file, mode_preview=preview)
+
+    def show_excel(self, path: str) -> None:
+        """View a spreadsheet as a real TABLE (openpyxl) — one tab per sheet."""
+        o = self._owner
+        o.ext_btn.setVisible(True)
+        try:
+            from cowork_local.core.deps import ensure_module
+            ensure_module("openpyxl", "openpyxl")
+            from openpyxl import load_workbook
+            wb = load_workbook(path, read_only=True, data_only=True)
+        except Exception:  # noqa: BLE001 - no openpyxl / unreadable → try PDF/text
+            self.show_document(path)
+            return
+        MAX_ROWS, MAX_COLS = 2000, 100
+        if self._xlsx_view is None:
+            self._xlsx_view = QTabWidget()
+            o.stack.addWidget(self._xlsx_view)
+        tabs = self._xlsx_view
+        while tabs.count():
+            w = tabs.widget(0); tabs.removeTab(0); w.deleteLater()
+        try:
+            for ws in wb.worksheets:
+                rows = list(ws.iter_rows(max_row=MAX_ROWS, max_col=MAX_COLS, values_only=True))
+                ncols = max((len(r) for r in rows), default=0)
+                table = QTableWidget(len(rows), ncols)
+                table.setEditTriggers(QTableWidget.NoEditTriggers)
+                table.horizontalHeader().setVisible(False)
+                for r, row in enumerate(rows):
+                    for c, val in enumerate(row):
+                        if val is not None:
+                            table.setItem(r, c, QTableWidgetItem(str(val)))
+                table.resizeColumnsToContents()
+                title = ws.title + (" (…)" if (ws.max_row or 0) > MAX_ROWS
+                                    or (ws.max_column or 0) > MAX_COLS else "")
+                tabs.addTab(table, title)
+        finally:
+            wb.close()
+        if tabs.count() == 0:
+            self.show_document(path)
+            return
+        o.stack.setCurrentWidget(tabs)
+
+    def show_document(self, path: str) -> None:
+        """Office docs + PDF are RENDERED via QtPdf — LibreOffice converts
+        them to PDF first. Falls back to text extraction when QtPdf/
+        LibreOffice aren't available."""
+        o = self._owner
+        o.ext_btn.setVisible(True)
+        suffix = Path(path).suffix.lower()
+        if not HAS_PDF:
+            self.show_document_text(path)
+            return
+        if suffix == ".pdf":
+            self._render_pdf(path)
+            return
+        try:
+            mtime = os.path.getmtime(path)
+        except OSError:
+            mtime = 0
+        cached = self._pdf_cache.get((path, mtime))
+        if cached and os.path.exists(cached):
+            self._render_pdf(cached)
+            return
+        from cowork_local.core.doc_extract import convert_to_pdf, find_soffice
+        if not find_soffice() and os.name != "nt":
+            self.show_document_text(path)
+            return
+        o.doc_view.setPlainText(tr("folder.converting"))
+        o.stack.setCurrentWidget(o.doc_view)
+        if self._pdf_tmp is None:
+            import tempfile
+            self._pdf_tmp = tempfile.mkdtemp(prefix="cowork_folder_pdf_")
+        src, out_dir = path, self._pdf_tmp
+
+        def job(worker):
+            return {"src": src, "mtime": mtime, "pdf": convert_to_pdf(src, out_dir)}
+
+        def done(result):
+            if result.get("src") != o.current_file:
+                return   # user moved on to another file
+            pdf = result.get("pdf")
+            if pdf:
+                self._pdf_cache[(result["src"], result["mtime"])] = pdf
+                self._render_pdf(pdf)
+            else:
+                self.show_document_text(src)
+
+        worker = AgentWorker(job)
+        worker.finished_ok.connect(done)
+        worker.failed.connect(lambda _e, p=src: self.show_document_text(p))
+        self._convert_worker = worker
+        worker.start()
+
+    def _ensure_pdf_view(self):
+        if not HAS_PDF:
+            return None
+        if self._pdf_view is None:
+            from PySide6.QtPdf import QPdfDocument
+            from PySide6.QtPdfWidgets import QPdfView
+            self._pdf_doc = QPdfDocument(self._owner)
+            self._pdf_view = QPdfView(self._owner)
+            self._pdf_view.setDocument(self._pdf_doc)
+            try:
+                self._pdf_view.setPageMode(QPdfView.PageMode.MultiPage)
+                self._pdf_view.setZoomMode(QPdfView.ZoomMode.FitToWidth)
+            except Exception:  # noqa: BLE001 - enum names vary slightly across versions
+                pass
+            self._owner.stack.addWidget(self._pdf_view)
+        return self._pdf_view
+
+    def _render_pdf(self, pdf_path: str) -> None:
+        view = self._ensure_pdf_view()
+        if view is None:
+            self.show_document_text(pdf_path)
+            return
+        self._pdf_doc.load(pdf_path)
+        self._owner.stack.setCurrentWidget(view)
+
+    def show_document_text(self, path: str) -> None:
+        from cowork_local.core.doc_extract import extract_text
+        o = self._owner
+        try:
+            text, note = extract_text(path)
+        except Exception as exc:  # noqa: BLE001
+            text, note = None, str(exc)
+        body = text if text else tr("folder.doc_unreadable", note=note or "?")
+        o.doc_view.setPlainText(body)
+        o.stack.setCurrentWidget(o.doc_view)
+
+    def write_pptx(self, content: str, skip_confirm: bool = False) -> bool:
+        """Write edited pptx text back into the deck. If the edit REPLACES any
+        image, ask the user to confirm first. ``skip_confirm`` is used when
+        the image was already confirmed (e.g. just generated). Returns False
+        if the user declined."""
+        from cowork_local.core import pptx_edit
+        o = self._owner
+        if not skip_confirm and pptx_edit.image_change_requested(content):
+            from PySide6.QtWidgets import QMessageBox
+            ok = QMessageBox.question(o, tr("folder.ai_image_confirm_title"),
+                                      tr("folder.ai_image_confirm"))
+            if ok != QMessageBox.Yes:
+                o.status_message.emit(tr("folder.ai_image_declined"))
+                return False
+        pptx_edit.apply_text_to_pptx(o.current_file, content)
+        return True
+
+
+__all__ = ["OfficeDocumentRenderer", "HAS_PDF"]

presentation/folder/workspace_file_tree.py

@@ -0,0 +1,97 @@
+"""WorkspaceFileTree — the folder-picker bar + directory tree pane of the
+Folder Explorer (R08-T12, extracted from ``ui/folder_tab.py::FolderTab``,
+lines 264-293/386-408 of the original 1587-line file).
+
+Owns navigation only: which root is browsed and which file was clicked.
+Rendering/editing the SELECTED file is
+``document_preview_manager.py::DocumentPreviewManager``'s job — this widget
+just emits :attr:`file_selected`.
+"""
+from __future__ import annotations
+
+import os
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QFileDialog, QFileSystemModel, QHBoxLayout, QLabel, QPushButton,
+    QTreeView, QVBoxLayout, QWidget,
+)
+
+from cowork_local.i18n import tr
+from cowork_local.ui.icons import icon
+
+
+class WorkspaceFileTree(QWidget):
+    """The left-hand tree pane: a path bar (label + "open folder" button)
+    above a ``QFileSystemModel``-backed ``QTreeView``."""
+
+    file_selected = Signal(str)   # absolute path of the clicked file
+    root_changed = Signal(str)    # absolute path of the new root
+
+    def __init__(self, initial_root: str, parent=None):
+        super().__init__(parent)
+        self._root = initial_root
+
+        root_layout = QVBoxLayout(self)
+        root_layout.setContentsMargins(0, 0, 0, 0)
+
+        # The path IS the title of this screen, so it is written as one
+        # rather than shown in a read-only text box that looks editable.
+        # Full path on hover; the button still opens the folder picker.
+        bar = QHBoxLayout()
+        self.path_lbl = QLabel(self._root)
+        self.path_lbl.setObjectName("folderTitle")
+        self.path_lbl.setTextInteractionFlags(Qt.TextSelectableByMouse)
+        self.path_lbl.setToolTip(self._root)
+        self._open_btn = QPushButton()
+        self._open_btn.setIcon(icon("folder"))
+        self._open_btn.setObjectName("primary")
+        self._open_btn.clicked.connect(self._pick_root)
+        bar.addWidget(self.path_lbl, 1)
+        bar.addWidget(self._open_btn)
+        root_layout.addLayout(bar)
+
+        self.model = QFileSystemModel()
+        self.model.setRootPath(self._root)
+        self.tree = QTreeView()
+        self.tree.setModel(self.model)
+        self.tree.setRootIndex(self.model.index(self._root))
+        for col in (1, 2, 3):          # hide Size / Type / Date-modified columns
+            self.tree.hideColumn(col)
+        self.tree.setHeaderHidden(True)
+        self.tree.clicked.connect(self._on_tree_clicked)
+        root_layout.addWidget(self.tree, 1)
+
+        self.retranslate()
+
+    def retranslate(self) -> None:
+        self._open_btn.setToolTip(tr("folder.path_placeholder"))
+        self._open_btn.setText(tr("folder.open_folder"))
+
+    @property
+    def root(self) -> str:
+        return self._root
+
+    def set_root(self, path: str) -> None:
+        p = str(path or "").strip()
+        if not p or not os.path.isdir(p):
+            return
+        self._root = p
+        self.path_lbl.setText(p)
+        self.path_lbl.setToolTip(p)
+        self.model.setRootPath(p)
+        self.tree.setRootIndex(self.model.index(p))
+        self.root_changed.emit(p)
+
+    def _pick_root(self) -> None:
+        chosen = QFileDialog.getExistingDirectory(self, tr("folder.open_folder"), self._root)
+        if chosen:
+            self.set_root(chosen)
+
+    def _on_tree_clicked(self, index) -> None:
+        path = self.model.filePath(index)
+        if path and os.path.isfile(path):
+            self.file_selected.emit(path)
+
+
+__all__ = ["WorkspaceFileTree"]

presentation/graph/__init__.py

@@ -0,0 +1,3 @@
+"""GraphRAG (Structure) screen, split into single-responsibility widgets
+(R08-T14): ``graph_scene_items``, ``graph_renderer``, ``graph_qa_widget``,
+assembled by the ``structure_graph_view`` shell."""