iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/main/ports.py

@@ -0,0 +1,571 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Semantic ports for main-screen controllers."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from rich.text import Text
+
+from chrys.app.tui.notifications import NotificationEvent
+from chrys.app.tui.util.diff_entries import DiffLoadResult
+from chrys.app.tui.widgets.sidebar.context import ContextUsageState
+from chrys.foundation.events.types import (
+    ApprovalRequest,
+    ApprovalReviewed,
+    Event,
+    ProvisionalPresentation,
+    QuestionToUser,
+)
+from chrys.foundation.i18n import MessageRef
+from chrys.foundation.models.approval_reuse import ReuseChoice
+from chrys.service.approval.policy import ApprovalMode
+
+if TYPE_CHECKING:
+    from textual.content import Content
+    from textual.worker import Worker
+
+    from chrys.app.tui.i18n import LocaleController
+    from chrys.app.tui.screens.main.dialog_controllers import (
+        AgentLoadDialogHandle,
+        ApprovalBypassDecision,
+        ApprovalDialogHandle,
+        ApprovalResponseWorker,
+        ImageCompressionDialogHandle,
+        QuestionDialogHandle,
+        QuestionDialogResult,
+    )
+    from chrys.app.tui.screens.main.engine_read_model import RollbackReadState
+    from chrys.app.tui.util.diff_entries import DiffFileEntry
+    from chrys.app.tui.widgets import PromptDraft
+    from chrys.app.tui.widgets.chrome.suggestion_list import SuggestionItem
+    from chrys.foundation.events.types import AgentRuntimeDetails
+    from chrys.foundation.models.ask_user import AskUserAnswer
+    from chrys.foundation.models.todos import TodoItem
+    from chrys.service.state.store import StateStore
+
+type SuggestionEntry = SuggestionItem | tuple[str, str | Content]
+type NotificationSeverity = Literal["information", "warning", "error"]
+type StatusMessage = MessageRef | str
+type StatusTrail = StatusMessage | tuple[StatusMessage, ...]
+type InputLabel = MessageRef | str
+type ConfirmMessage = StatusMessage | Text
+# Runs async work in a screen worker. The work is called only once the worker
+# starts, so a worker cancelled before it runs leaves no unawaited coroutine.
+type StartWorker = Callable[[Callable[[], Awaitable[object]]], object]
+
+
+class EventPublisher(Protocol):
+    """Minimal event publishing port."""
+
+    async def publish(self, event: Event) -> None: ...
+
+
+class EngineProvider(Protocol):
+    """Read the current backend engine."""
+
+    def __call__(self) -> object: ...
+
+
+@dataclass(frozen=True)
+class InputRestore:
+    """Proof that one specific restore put its text into an empty composer.
+
+    Handed out by :meth:`restore_input_text` and redeemable exactly once, by
+    :meth:`rewrite_restored_input`, for a follow-up that rewrites *that* text
+    in place. Ownership is the credential, never text equality across
+    operations: a draft the user typed — or retyped — is never ours to
+    replace, however it happens to read.
+    """
+
+    generation: int
+    text: str
+
+
+class InputFlowView(Protocol):
+    """UI operations required by user submit/retry/interrupt flow."""
+
+    def set_terminal_title_for_user_message(self, text: str) -> None: ...
+    def clear_terminal_title_result(self) -> None: ...
+    def current_chat_session_id(self) -> str: ...
+    def add_input_history(self, text: str, *, session_id: str | None) -> None: ...
+    def set_retry_mode(self, enabled: bool, *, label: InputLabel = "Retry") -> None: ...
+    def start_run_status(self, label: StatusMessage) -> None: ...
+    async def render_user_message(self, text: str, *, created_at: datetime, contents: list[Any] | None) -> None: ...
+    async def render_user_retry_note(self, text: str, *, created_at: datetime) -> None: ...
+    def hide_trailing_status_action(self) -> None: ...
+    def set_retry_pending(self, pending: bool) -> None: ...
+    def clear_ask_user_inline_prompts(self) -> None: ...
+    def lock_input_with_text(self) -> None: ...
+    def unlock_input_keep_if_locked(self) -> None: ...
+    def flash_interrupted(self) -> None: ...
+    async def render_interrupted(self) -> None: ...
+    def update_toc(self) -> None: ...
+
+
+class ShellModeView(Protocol):
+    """UI operations required by shell-mode transitions."""
+
+    def enter_shell_mode(self) -> None: ...
+    def exit_shell_mode(self) -> None: ...
+    def set_alternate_screen_active(self, active: bool) -> None: ...
+
+
+class InputFocusView(Protocol):
+    """UI operations required by focus and paste guards."""
+
+    def focus_input(self) -> None: ...
+    def insert_paste_payload(self, text: str) -> bool: ...
+
+
+class SuggestionPopupView(Protocol):
+    """Semantic suggestion-popup operations."""
+
+    @property
+    def is_attached(self) -> bool: ...
+
+    @property
+    def suggestions_active(self) -> bool: ...
+
+    def show_suggestions(
+        self,
+        mode: str,
+        items: Sequence[SuggestionEntry],
+        *,
+        disabled: set[str] | None = None,
+        initial: str | None = None,
+        title: str = "",
+    ) -> None: ...
+    def show_suggestions_loading(self, mode: str, *, title: str = "") -> None: ...
+    def update_suggestions(
+        self,
+        items: Sequence[SuggestionEntry],
+        *,
+        disabled: set[str] | None = None,
+        title: str | None = None,
+    ) -> None: ...
+    def hide_suggestions(self) -> None: ...
+    def focus_input(self) -> None: ...
+    async def load_prompt_history(self, *, max_entries: int) -> list[str]: ...
+    def run_file_suggestion_worker(self, awaitable: Awaitable[None], *, name: str, group: str) -> Worker[None]: ...
+    def move_suggestion_cursor(self, direction: str) -> None: ...
+    def select_highlighted_suggestion(self, *, execute: bool) -> bool: ...
+    def show_subcommand_suggestions(
+        self,
+        items: Sequence[SuggestionEntry],
+        *,
+        initial: str | None = None,
+    ) -> None: ...
+    def input_value(self) -> str: ...
+    def set_input_value(self, value: str) -> None: ...
+    def replace_input_trigger_text(self, trigger: str, replacement: str) -> None: ...
+
+
+class BuddyCommandView(Protocol):
+    """UI operations required by buddy slash commands."""
+
+    def notify_buddy(
+        self, message: StatusMessage, *, severity: NotificationSeverity = "information", timeout: float = 10
+    ) -> None: ...
+
+    def refresh_buddy_panel(self, *, focus_tab: bool) -> None: ...
+    def call_after_refresh(self, callback: Callable[[], None]) -> None: ...
+
+
+class SessionLifecycleView(Protocol):
+    """UI operations required by session lifecycle handling."""
+
+    def current_chat_session_id(self) -> str: ...
+    async def restore_workflow_session(self, session_id: str) -> None: ...
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+    def restore_session_chrome(self, *, session_id: str, profile: str, cwd: str) -> None: ...
+
+
+class RuntimeConfigView(Protocol):
+    """UI operations required by runtime/config actions."""
+
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+    def push_screen(self, screen: object, callback: object | None = None) -> object: ...
+    def run_worker(self, awaitable: Awaitable[Any], *, group: str) -> None: ...
+    def open_runtime_details(self, details: AgentRuntimeDetails) -> None: ...
+    def set_chat_profile(self, profile: str) -> None: ...
+    def set_status_profile(self, profile: str, *, description: str = "") -> None: ...
+    def focus_input(self) -> None: ...
+
+
+class WorkspaceView(Protocol):
+    """UI operations required by workspace actions."""
+
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+    def push_screen(self, screen: object, callback: object | None = None) -> object: ...
+
+
+class CopyActionView(Protocol):
+    """UI operations required by copy and fold actions."""
+
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+    def chat_copy_messages(self, target: str) -> list[tuple[str, str]]: ...
+    def copy_text(self, text: str) -> None: ...
+    def toggle_chat_fold_all(self) -> bool: ...
+
+
+class DiffView(Protocol):
+    """UI operations required by diff actions."""
+
+    def current_chat_session_id(self) -> str: ...
+    def open_diff_screen(
+        self,
+        periods_data: dict[int, list[DiffFileEntry]],
+        *,
+        cwd: str,
+        subtitle_parts: tuple[str, ...],
+        session_id: str,
+        all_entries: list[DiffFileEntry],
+        load_data: Callable[[], Awaitable[DiffLoadResult]] | None = None,
+    ) -> None: ...
+
+
+class RollbackView(Protocol):
+    """UI operations required by rollback actions."""
+
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+    def open_rollback_modal(
+        self,
+        *,
+        cwd: str,
+        load_state: Callable[[], Awaitable[RollbackReadState | None]],
+        on_result: object,
+    ) -> None: ...
+    def open_rollback_progress_modal(self, operation: Callable[[], Awaitable[None]]) -> None: ...
+    async def restore_welcome_rollback(self, *, session_id: str | None, profile: str, cwd: str) -> None: ...
+    def restore_input_text(self, text: str) -> InputRestore | None: ...
+
+
+class NavigationView(Protocol):
+    """UI operations required by navigation and overlay actions."""
+
+    def open_log_viewer(self) -> None: ...
+    def open_guide(self, locale_controller: LocaleController | None) -> None: ...
+    def stop_shell(self) -> None: ...
+    def exit_app(self) -> None: ...
+    def open_sessions_screen(self, state_store: StateStore, *, current_session_id: str, on_result: object) -> None: ...
+    def current_session_id(self) -> str: ...
+    def toggle_sidebar(self) -> None: ...
+    def update_toc(self) -> None: ...
+    def open_theme_picker(self, on_result: object) -> None: ...
+    def apply_theme_setting(self, name: str) -> bool: ...
+    def open_language_picker(self, current_locale: str, on_result: object) -> None: ...
+    def dashboard_visible(self) -> bool: ...
+    def show_trajectory_dashboard(self) -> None: ...
+    def hide_trajectory_dashboard(self) -> None: ...
+    def select_trajectory_turn(self, turn_id: str) -> None: ...
+    def open_confirm_dialog(
+        self,
+        *,
+        title: StatusMessage,
+        message: ConfirmMessage,
+        confirm_label: StatusMessage,
+        confirm_variant: str,
+        on_result: object,
+    ) -> None: ...
+    def dismiss_interrupt_confirm(self) -> None: ...
+    def scroll_chat_to_turn(self, turn_id: str) -> None: ...
+    def notify(
+        self,
+        message: StatusMessage,
+        *,
+        title: StatusMessage,
+        severity: NotificationSeverity = "information",
+        timeout: float | None = 3,
+    ) -> None: ...
+
+
+class ToolActionView(Protocol):
+    """UI operations required by inline tool action bridges."""
+
+    def update_tool_args(self, call_id: str, args: dict[str, Any]) -> None: ...
+
+
+class AgentLoadUiPort(Protocol):
+    """Agent-load dialog operations used across handlers."""
+
+    async def begin_session_restore_load(self, session_id: str) -> None: ...
+    def cancel_agent_load(self) -> None: ...
+    def finish_agent_load(self, message: StatusMessage = "") -> None: ...
+
+
+class RuntimeInfoFormatter(Protocol):
+    """Format runtime tool/skill/hook/file trail text."""
+
+    def format_tool_info(
+        self,
+        tool_names: list[str],
+        skill_names: list[str],
+        *,
+        memory_files: list[str] | None = None,
+        runtime_details: AgentRuntimeDetails | None = None,
+    ) -> StatusTrail: ...
+
+
+class ProfileDescriptionProvider(Protocol):
+    """Look up descriptions for configured agent profiles."""
+
+    def get_profile_description(self, profile_name: str) -> str: ...
+
+
+class RuntimeInfoProvider(RuntimeInfoFormatter, ProfileDescriptionProvider, Protocol):
+    """Combined runtime formatting and profile-description surface."""
+
+
+class DialogGatewayView(Protocol):
+    """UI operations required by dialog queue controllers."""
+
+    async def build_approval_body(self, event: ApprovalRequest) -> object | None: ...
+    def approval_body_bypass(self, body: object | None) -> ApprovalBypassDecision | None: ...
+    def show_approval_dialog(
+        self,
+        event: ApprovalRequest,
+        approval_body: object | None,
+        on_result: Callable[[tuple[bool, str, dict[str, Any] | None] | None], None],
+        *,
+        verdict: ApprovalReviewed | None,
+    ) -> ApprovalDialogHandle: ...
+    def deliver_approval_verdict(self, dialog: ApprovalDialogHandle, event: ApprovalReviewed) -> None: ...
+
+    def dismiss_approval_dialog(self, dialog: ApprovalDialogHandle) -> None: ...
+    def approval_dialog_tool_name(self, dialog: ApprovalDialogHandle) -> str: ...
+    def set_auto_review_count(self, count: int) -> None: ...
+    def notify_approval_required(self) -> None: ...
+    def update_tool_args(self, call_id: str, args: dict[str, Any]) -> None: ...
+    def run_worker(self, awaitable: Awaitable[Any], *, group: str) -> None: ...
+    def show_question_dialog(
+        self,
+        event: QuestionToUser,
+        draft: PromptDraft | None,
+        on_result: Callable[[object], None],
+    ) -> QuestionDialogHandle: ...
+    def parse_question_dialog_result(self, result: object) -> QuestionDialogResult: ...
+    def show_question_inline(self, event: QuestionToUser, draft: PromptDraft | None = None) -> bool: ...
+
+    def clear_question_inline(self, call_id: str, request_id: str) -> bool: ...
+    def question_can_reopen_modal(self, event: QuestionToUser) -> bool: ...
+    def notify_ask_user(self) -> None: ...
+    def focus_input(self) -> None: ...
+    def create_agent_load_dialog(self, *, title: StatusMessage, subtitle: str) -> AgentLoadDialogHandle: ...
+    def prepare_agent_load_ui(
+        self,
+        *,
+        title: StatusMessage,
+        session_id: str | None,
+        update_clipboard_dir: bool,
+        capture_status_snapshot: bool,
+    ) -> dict | None: ...
+    async def push_agent_load_dialog(self, dialog: AgentLoadDialogHandle) -> None: ...
+    def restore_agent_load_status(self, snapshot: dict) -> None: ...
+    def show_load_status(self, message: StatusMessage) -> None: ...
+    def render_status_message(self, message: StatusMessage) -> str: ...
+    def flash_agent_load_failed(self, message: str) -> None: ...
+    def create_image_compression_dialog(self, *, title: StatusMessage) -> ImageCompressionDialogHandle: ...
+    async def push_image_compression_dialog(self, dialog: ImageCompressionDialogHandle) -> None: ...
+
+
+class DialogGatewayCallbacks(Protocol):
+    """Non-UI dialog effects supplied by the screen owner."""
+
+    def debug(self, key: str, message: str = "") -> None: ...
+    def handle_approval_response(
+        self,
+        request_id: str,
+        approved: bool,
+        reason: str,
+        modified_args: dict[str, Any] | None = None,
+        remember_choice: ReuseChoice = "",
+    ) -> ApprovalResponseWorker | None: ...
+    async def publish_auto_fulfill_blocked(self, event: ApprovalReviewed) -> None: ...
+    def handle_ask_user_response(self, request_id: str, answers: tuple[AskUserAnswer, ...]) -> None: ...
+    def set_agent_loading(self, value: bool) -> None: ...
+
+
+class MainScreenPresentationView(Protocol):
+    """Backend/session presentation operations owned by the Textual adapter."""
+
+    def chat_session_id(self) -> str: ...
+    def set_tool_info(self, trail: StatusTrail) -> None: ...
+    def show_status(self, text: StatusMessage) -> None: ...
+    def clear_status(self) -> None: ...
+    def flash_status(self, *args: Any, **kwargs: Any) -> None: ...
+    def flash_turn_complete(self) -> None: ...
+    def mark_terminal_title_completed(self) -> None: ...
+    def mark_terminal_title_failed(self) -> None: ...
+    def start_tool_status(self, tool_name: str) -> None: ...
+    def set_chat_profile(self, profile: str) -> None: ...
+    def set_chat_tool_kinds(self, tool_kinds: dict[str, str]) -> None: ...
+    async def clear_chat(self) -> None: ...
+    def set_chat_workspace_cwd(self, cwd: str) -> None: ...
+    def update_welcome(self, *, profile: str = "", cwd: str = "") -> None: ...
+    def set_chat_session_id(self, session_id: str) -> None: ...
+    def set_session_title_state(
+        self,
+        *,
+        custom: str | None = None,
+        generated: str | None = None,
+        fallback: str | None = None,
+    ) -> None: ...
+    def reset_session_title_state(self) -> None: ...
+    def session_custom_title(self) -> str: ...
+    def set_context_usage_state(self, state: ContextUsageState | None) -> None: ...
+    def set_todo_state(self, items: tuple[TodoItem, ...]) -> None: ...
+    def clear_todos(self) -> None: ...
+    def set_header_approval_mode(self, mode: ApprovalMode) -> None: ...
+    def set_terminal_title_for_cwd(self, cwd: str | None = None) -> None: ...
+    def set_status_profile(self, profile: str, *, description: str = "") -> None: ...
+    def set_input_clipboard_dir(self, session_id: str | None) -> None: ...
+    def set_input_retry_mode(self, value: bool) -> None: ...
+    def set_input_retry(self, label: InputLabel, value: bool = True) -> None: ...
+    def set_input_paste_cwd(self, cwd: str) -> None: ...
+    def restore_input_text(self, text: str) -> InputRestore | None: ...
+    def rewrite_restored_input(self, restore: InputRestore | None, text: str) -> bool: ...
+    def unlock_input_keep_if_locked(self) -> None: ...
+    async def change_shell_directory(self, cwd: str) -> None: ...
+    def reset_context_usage(self, max_context_tokens: int = 0) -> None: ...
+    def clear_compressed_blocks(self) -> None: ...
+    async def add_error(self, message: str, *, action_label: str | None = "Retry") -> None: ...
+    async def add_system(self, text: str, *, key: str | None = None) -> None: ...
+    async def update_system(self, key: str, text: str) -> None: ...
+    async def remove_system(self, key: str) -> None: ...
+    async def replay_history(self, *args: Any, **kwargs: Any) -> None: ...
+    async def add_agent_message(self, *args: Any, **kwargs: Any) -> None: ...
+    async def accept_presentation_attempt(self, attempt_id: str, segment_ids: tuple[str, ...]) -> None: ...
+    async def reject_presentation_attempt(self, attempt_id: str) -> None: ...
+    async def add_user_injection(self, *args: Any, **kwargs: Any) -> None: ...
+    def unlock_input_after_consumed_injection(self) -> None: ...
+    def unlock_input_after_abandoned_injection(self) -> None: ...
+    async def add_tool_start(self, *args: Any, **kwargs: Any) -> None: ...
+    def update_tool_progress(
+        self,
+        call_id: str,
+        lines: list[str],
+        *,
+        image_contents: list[object] | None = None,
+        snapshot_metadata: dict[str, Any] | None = None,
+        provider_status: str = "",
+    ) -> None: ...
+    def update_tool_args(self, call_id: str, args: dict[str, Any]) -> None: ...
+    def update_tool_status(
+        self,
+        call_id: str,
+        status: str,
+        *,
+        provider_status: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> None: ...
+    async def add_tool_result(self, *args: Any, **kwargs: Any) -> None: ...
+    async def add_context_fold(self, *args: Any, **kwargs: Any) -> bool: ...
+    def add_compressed_block(
+        self,
+        context_id: str,
+        summary: str,
+        freed_messages: int = 0,
+        turn_range: tuple[int, int] = (0, 0),
+    ) -> None: ...
+    async def add_compaction_start(self, compaction_id: str) -> None: ...
+    def complete_compaction(self, *args: Any, **kwargs: Any) -> None: ...
+    def show_compaction_retry(self, *args: Any, **kwargs: Any) -> None: ...
+    def add_sub_agent_compaction_start(self, agent_name: str, invocation_id: str, compaction_id: str) -> None: ...
+    def complete_sub_agent_compaction(self, *args: Any, **kwargs: Any) -> None: ...
+    def record_sub_agent_compaction_committed(self, invocation_id: str, compaction_id: str) -> None: ...
+    def link_sub_agent_invocation(
+        self,
+        parent_call_id: str,
+        invocation_id: str,
+        agent_name: str,
+        sub_agent_log_file: str = "",
+        *,
+        tool_name: str = "",
+    ) -> None: ...
+    def add_sub_agent_message(
+        self,
+        agent_name: str,
+        invocation_id: str,
+        text: str,
+        *,
+        presentation: ProvisionalPresentation | None = None,
+    ) -> None: ...
+    def accept_sub_agent_presentation(
+        self,
+        invocation_id: str,
+        attempt_id: str,
+        segment_ids: tuple[str, ...],
+    ) -> None: ...
+    def reject_sub_agent_presentation(self, invocation_id: str, attempt_id: str) -> None: ...
+    async def add_sub_agent_tool_start(self, *args: Any, **kwargs: Any) -> None: ...
+    def update_sub_agent_tool_args(self, *args: Any, **kwargs: Any) -> None: ...
+    def update_sub_agent_tool_status(self, *args: Any, **kwargs: Any) -> None: ...
+    def update_sub_agent_tool_progress(self, *args: Any, **kwargs: Any) -> None: ...
+    def complete_sub_agent_tool(self, *args: Any, **kwargs: Any) -> None: ...
+    def update_sub_agent_progress(self, *args: Any, **kwargs: Any) -> None: ...
+    def sub_agent_retry_attempt(self, *args: Any, **kwargs: Any) -> None: ...
+    def sub_agent_paused(self, *args: Any, **kwargs: Any) -> None: ...
+    def sub_agent_resumed_after_pause(self, invocation_id: str) -> None: ...
+    def sub_agent_cascade_aborted(self, invocation_id: str) -> None: ...
+    def sub_agent_aborted(self, invocation_id: str, last_error: str) -> None: ...
+    async def show_retry_attempt(self, *args: Any, **kwargs: Any) -> None: ...
+
+
+class BackendEventView(
+    InputFlowView,
+    SessionLifecycleView,
+    ToolActionView,
+    MainScreenPresentationView,
+    DialogGatewayView,
+    Protocol,
+):
+    """Composite view surface used by transitional backend presenters."""
+
+    @property
+    def context_usage_state(self) -> ContextUsageState | None: ...
+
+    def notify_event(self, event: NotificationEvent) -> None: ...
+    def push_screen(self, screen: object, callback: object | None = None) -> object: ...
+    def set_chat_profile(self, profile: str) -> None: ...
+    def set_context_usage_state(self, state: ContextUsageState | None) -> None: ...
+    def set_header_approval_mode(self, mode: ApprovalMode) -> None: ...

chrys/app/tui/screens/main/recent_dirs.py

@@ -0,0 +1,123 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""RecentPaths implementation backed by the persisted workspace MRU index."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from chrys.app.tui.support.path_shortcuts import format_recent_path_label, get_default_favorite_paths
+from chrys.app.tui.support.workspace_mru import (
+    ensure_workspace_mru_index,
+    load_workspace_mru,
+    session_root_key,
+    workspace_mru_backfilled_for,
+    workspace_mru_exists,
+)
+from chrys.foundation.config.settings import DEFAULT_WORKSPACE_MRU_MAX_ENTRIES
+
+if TYPE_CHECKING:
+    from chrys.service.state.store import StateStore
+
+logger = logging.getLogger(__name__)
+
+
+class WorkspaceMruRecentDirs:
+    """Serves recently used working directories from the workspace MRU index.
+
+    Implements the :class:`~chrys.app.tui.screens.dialogs.file_picker.RecentPaths`
+    protocol so it can be passed directly to :class:`FilePicker`.
+
+    ``StateStore.list_sessions()`` (a full sessions-directory scan) runs only
+    for the one-time seed — when the index is missing or the current session
+    root has never been backfilled.  Once a root is marked backfilled, opening
+    the picker reads just the small index file, even if the index is empty or
+    corrupt.  All store access is offloaded to a worker thread: even the
+    one-time seed takes a file lock and does an atomic write, which must not
+    block the TUI event loop.
+    """
+
+    def __init__(
+        self,
+        state_store: StateStore | None,
+        *,
+        max_entries: int = DEFAULT_WORKSPACE_MRU_MAX_ENTRIES,
+    ) -> None:
+        self._state_store = state_store
+        self._max_entries = max_entries
+
+    async def get_recent_paths(self) -> list[tuple[str, str]]:
+        if self._max_entries <= 0:
+            return []
+        index_exists = await asyncio.to_thread(workspace_mru_exists)
+        if not index_exists and self._state_store is None:
+            # Never create an empty index without a state store — that would
+            # block the first real backfill once a state store is available.
+            return []
+        if index_exists and self._state_store is None:
+            return self._format(await asyncio.to_thread(load_workspace_mru, self._max_entries))
+        root_key = await asyncio.to_thread(self._session_root_key)
+        if index_exists and await asyncio.to_thread(workspace_mru_backfilled_for, root_key):
+            return self._format(await asyncio.to_thread(load_workspace_mru, self._max_entries))
+        return self._format(await self._seed_and_ensure(root_key))
+
+    async def _seed_and_ensure(self, root_key: str) -> list[str]:
+        """Run the one-time session backfill for *root_key* and return the index.
+
+        A failed scan still marks the root as backfilled (with an empty seed)
+        so a persistent failure cannot re-trigger the expensive scan on every
+        picker open; live workspace events fill the index incrementally.
+        """
+        seed: list[tuple[str, datetime]] = []
+        try:
+            seed = await self._collect_seed_paths()
+        except Exception:
+            logger.warning("Workspace MRU seed scan failed; creating empty index", exc_info=True)
+        return await asyncio.to_thread(
+            ensure_workspace_mru_index,
+            seed,
+            max_entries=self._max_entries,
+            root_key=root_key,
+        )
+
+    async def _collect_seed_paths(self) -> list[tuple[str, datetime]]:
+        """Collect ``(path, last_used_at)`` seeds from saved session metadata."""
+        exclude = get_default_favorite_paths()
+        seed: list[tuple[str, datetime]] = []
+        seen: set[str] = set()
+
+        sessions = sorted(await self._require_state_store().list_sessions(), key=lambda s: s.updated_at, reverse=True)
+        for meta in sessions:
+            for cwd in [meta.primary_cwd, *meta.working_dirs]:
+                if not cwd:
+                    continue
+                cwd = os.path.normpath(cwd)
+                key = os.path.normcase(cwd)
+                if key in seen or key in exclude:
+                    continue
+                seen.add(key)
+                if not os.path.isdir(cwd):
+                    continue
+                updated_at = meta.updated_at
+                if updated_at.tzinfo is None:
+                    updated_at = updated_at.replace(tzinfo=UTC)
+                seed.append((cwd, updated_at))
+                if len(seed) >= self._max_entries:
+                    return seed
+        return seed
+
+    def _require_state_store(self) -> StateStore:
+        if self._state_store is None:
+            raise RuntimeError("Reading recent session directories requires a state store.")
+        return self._state_store
+
+    def _session_root_key(self) -> str:
+        return session_root_key(self._require_state_store().session_dir("__workspace_mru_probe__").parent)
+
+    @staticmethod
+    def _format(paths: list[str]) -> list[tuple[str, str]]:
+        return [(format_recent_path_label(path), path) for path in paths]