iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/widgets/chat/chrome.py

@@ -0,0 +1,296 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Persistent chrome and border behavior for the chat panel."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.text import Text
+from textual.content import Content
+from textual.message import Message
+from textual.widgets import Static
+
+from chrys.app.tui.i18n import render_content, render_str
+from chrys.app.tui.util.git_branch import format_workspace_subtitle
+from chrys.app.tui.util.logo import CHAT_LOGO
+from chrys.app.tui.util.removal import remove_shielded
+from chrys.app.tui.widgets.chat.ports import ChatChromeHost
+from chrys.app.tui.widgets.click_affordance import ClickAffordance
+from chrys.app.tui.widgets.welcome import WelcomeWidget
+from chrys.foundation.i18n import MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message
+
+if TYPE_CHECKING:
+    from textual.events import Click
+    from textual.widget import Widget
+
+    from chrys.app.tui.i18n import LocaleController
+
+# Border-title budget for the session title fragment; the full title is
+# available via the click-to-edit dialog and the F1 sessions modal.
+_BORDER_TITLE_MAX_CHARS = 48
+
+_CHAT_SESSION_TITLE = msg("tui.chat.session_title", fallback="Session: {session_id}")
+_CHAT_SCROLL_TO_BOTTOM = msg("tui.chat.scroll_to_bottom", fallback="Scroll to bottom {glyph}")
+_CHAT_SCROLL_TO_BOTTOM_TOOLTIP = msg(
+    "tui.chat.scroll_to_bottom_tooltip",
+    fallback="Jump to the bottom of the conversation ({shortcut})",
+)
+
+
+def _truncate_border_title(title: str, max_chars: int = _BORDER_TITLE_MAX_CHARS) -> str:
+    """Collapse whitespace and cap the title for the one-line border."""
+    title = " ".join(title.split())
+    if len(title) <= max_chars:
+        return title
+    return title[: max_chars - 1].rstrip() + "…"
+
+
+class ChatBottomSpacer(Static):
+    """Flexible trailing spacer that lets short transcript content scroll to top."""
+
+    ALLOW_SELECT = False
+
+    DEFAULT_CSS = """
+    ChatBottomSpacer {
+        height: 1fr;
+        min-height: 0;
+        background: transparent;
+    }
+    """
+
+    def __init__(self) -> None:
+        super().__init__("")
+
+
+class ScrollToBottomRequested(Message):
+    """Posted by the floating bottom-jump affordance."""
+
+
+class ScrollToBottomButton(ClickAffordance):
+    """Floating affordance shown when the transcript is not at the bottom."""
+
+    # Floats over the transcript; its label must never join drag selections
+    # or copied text, and it must not hijack selection anchor resolution.
+    ALLOW_SELECT = False
+
+    CLICK_MESSAGE = ScrollToBottomRequested
+
+    # ``position: absolute`` keeps it out of the transcript flow (no trailing
+    # row); show/hide goes through the ``visibility`` rule — a ``display``
+    # toggle would force a full screen reflow plus a compositor full-map
+    # rebuild mid-scroll (a multi-hundred-ms hitch on large transcripts).
+    # Textual's ``visible`` setter itself escalates to a full reflow too, so
+    # ``sync_scroll_to_bottom_button`` writes the rule directly. Hidden
+    # widgets are skipped by both painting and hit testing, so the invisible
+    # button never blocks clicks.
+    DEFAULT_CSS = """
+    ScrollToBottomButton {
+        position: absolute;
+        visibility: hidden;
+        width: auto;
+        min-width: 20;
+        height: 1;
+        padding: 0 1;
+        background: $foreground 8%;
+        color: $text-muted;
+        text-style: dim;
+        content-align: center middle;
+        pointer: pointer;
+    }
+    ScrollToBottomButton:hover {
+        background: $foreground 15%;
+        color: $accent;
+        text-style: not dim;
+    }
+    """
+
+    def __init__(self, label: Content | None = None, *, tooltip: Content | None = None) -> None:
+        if label is None:
+            label = Content.from_text(format_message(_CHAT_SCROLL_TO_BOTTOM.bind(glyph="\u2193")), markup=False)
+        if tooltip is None:
+            tooltip = Content.from_text(
+                format_message(_CHAT_SCROLL_TO_BOTTOM_TOOLTIP.bind(shortcut="Ctrl+End")),
+                markup=False,
+            )
+        super().__init__(label)
+        self.tooltip = tooltip
+
+
+class ChatPanelChrome:
+    """Own welcome/spacer/button infrastructure and border metadata."""
+
+    def __init__(self, host: ChatChromeHost, *, locale_controller: LocaleController | None = None) -> None:
+        self._host = host
+        self._locale_controller = locale_controller
+        self._welcome: WelcomeWidget | None = None
+        self._bottom_spacer: ChatBottomSpacer | None = None
+        self._scroll_to_bottom_button: ScrollToBottomButton | None = None
+        self._session_id: str = ""
+        self._session_title: str = ""
+        self._workspace_cwd: str = ""
+        self._workspace_branch: str = ""
+
+    @property
+    def welcome(self) -> WelcomeWidget | None:
+        """Current welcome widget, if mounted."""
+        return self._welcome
+
+    @welcome.setter
+    def welcome(self, widget: WelcomeWidget | None) -> None:
+        self._welcome = widget
+
+    @property
+    def bottom_spacer(self) -> ChatBottomSpacer | None:
+        """Current bottom spacer widget."""
+        return self._bottom_spacer
+
+    @bottom_spacer.setter
+    def bottom_spacer(self, widget: ChatBottomSpacer | None) -> None:
+        self._bottom_spacer = widget
+
+    @property
+    def scroll_to_bottom_button(self) -> ScrollToBottomButton | None:
+        """Current bottom-jump button widget."""
+        return self._scroll_to_bottom_button
+
+    @scroll_to_bottom_button.setter
+    def scroll_to_bottom_button(self, widget: ScrollToBottomButton | None) -> None:
+        self._scroll_to_bottom_button = widget
+
+    @property
+    def session_id(self) -> str:
+        """Full session id backing the border title and click-to-edit dialog."""
+        return self._session_id
+
+    @property
+    def workspace_cwd(self) -> str:
+        """Current workspace cwd metadata."""
+        return self._workspace_cwd
+
+    def initial_widgets(self) -> tuple[WelcomeWidget, ChatBottomSpacer, ScrollToBottomButton]:
+        """Create initial persistent chrome widgets in mount order."""
+        return self._create_widgets()
+
+    def detach_infrastructure_refs(self) -> None:
+        """Forget current chrome widget refs before async child removal."""
+        self._welcome = None
+        self._bottom_spacer = None
+        self._scroll_to_bottom_button = None
+
+    def rebuild_widgets(self) -> tuple[WelcomeWidget, ChatBottomSpacer, ScrollToBottomButton]:
+        """Create fresh persistent chrome widgets after transcript clear."""
+        return self._create_widgets()
+
+    def _create_widgets(self) -> tuple[WelcomeWidget, ChatBottomSpacer, ScrollToBottomButton]:
+        # Rebuild from panel metadata, which survives transcript and mode changes.
+        welcome = WelcomeWidget(CHAT_LOGO, title=self._host.profile_name, cwd=self._host.workspace_cwd)
+        spacer = ChatBottomSpacer()
+        spacer.display = False
+        button = ScrollToBottomButton(
+            self._render_content(_CHAT_SCROLL_TO_BOTTOM.bind(glyph="\u2193")),
+            tooltip=self._render_content(_CHAT_SCROLL_TO_BOTTOM_TOOLTIP.bind(shortcut="Ctrl+End")),
+        )
+        self._welcome = welcome
+        self._bottom_spacer = spacer
+        self._scroll_to_bottom_button = button
+        return welcome, spacer, button
+
+    async def dismiss_welcome(self) -> None:
+        """Remove the welcome widget on first transcript content."""
+        welcome = self._welcome
+        if welcome is None:
+            return
+        self._welcome = None
+        try:
+            await remove_shielded(welcome)
+        finally:
+            if self._bottom_spacer is not None:
+                self._bottom_spacer.display = True
+
+    def update_welcome(self, profile: str = "", cwd: str = "") -> None:
+        """Update welcome widget metadata if the widget is still present."""
+        if self._welcome is not None:
+            self._welcome.update_info(title=profile or None, cwd=cwd or None)
+
+    def set_session_id(self, session_id: str) -> None:
+        """Set session id metadata and refresh the border title."""
+        self._session_id = session_id
+        self._update_border_title()
+
+    def set_session_title(self, title: str) -> None:
+        """Set the display title shown next to the session id in the border."""
+        self._session_title = title
+        self._update_border_title()
+
+    def set_workspace_cwd(self, cwd: str) -> None:
+        """Set workspace cwd metadata and refresh the border subtitle."""
+        self._workspace_cwd = cwd
+        self._update_border_subtitle()
+
+    def set_workspace_branch(self, branch: str) -> None:
+        """Set workspace git branch metadata and refresh the border subtitle."""
+        self._workspace_branch = branch
+        self._update_border_subtitle()
+
+    def _update_border_title(self) -> None:
+        if not self._session_id:
+            return
+        from chrys.foundation.util.session_ids import session_short_id
+
+        title = self._render_str(_CHAT_SESSION_TITLE.bind(session_id=session_short_id(self._session_id)))
+        display_title = _truncate_border_title(self._session_title)
+        if display_title:
+            title += f" · {display_title}"
+        self._host.set_border_title(Text(title))
+
+    def refresh_localization(self) -> None:
+        """Retranslate only stored border metadata and persistent button chrome."""
+        self._update_border_title()
+        button = self._scroll_to_bottom_button
+        if button is not None:
+            self._refresh_scroll_to_bottom_button(button)
+
+    def _refresh_scroll_to_bottom_button(self, button: ScrollToBottomButton) -> None:
+        button.update(self._render_content(_CHAT_SCROLL_TO_BOTTOM.bind(glyph="\u2193")), layout=False)
+        button.tooltip = self._render_content(_CHAT_SCROLL_TO_BOTTOM_TOOLTIP.bind(shortcut="Ctrl+End"))
+
+    def _render_str(self, reference: MessageRef) -> str:
+        controller = self._locale_controller
+        if controller is None:
+            return format_message(reference)
+        return render_str(controller.localizer, reference)
+
+    def _render_content(self, reference: MessageRef) -> Content:
+        controller = self._locale_controller
+        if controller is None:
+            return Content.from_text(format_message(reference), markup=False)
+        return render_content(controller.localizer, reference)
+
+    def _update_border_subtitle(self) -> None:
+        subtitle = format_workspace_subtitle(self._workspace_cwd, self._workspace_branch)
+        self._host.set_border_subtitle(Text(subtitle) if subtitle else None)
+
+    def is_infrastructure(self, widget: Widget) -> bool:
+        """Return whether ``widget`` is persistent chrome infrastructure."""
+        return widget is self._welcome or widget is self._bottom_spacer or widget is self._scroll_to_bottom_button
+
+    def handle_click(self, event: Click) -> None:
+        """Handle border/title/subtitle clicks."""
+        target = event.widget
+        if self._host.is_ask_user_interactive_target(target):
+            event.stop()
+            return
+        region = self._host.border_region()
+        if event.screen_y == region.y and self._session_id:
+            # stop() alone only blocks bubbling; prevent_default() is what
+            # keeps Widget._on_click from also running (a double-click on
+            # the border would otherwise text-select the whole transcript).
+            event.prevent_default()
+            event.stop()
+            self._host.post_title_clicked()
+        elif event.screen_y == region.y + region.height - 1 and self._host.has_border_subtitle():
+            event.prevent_default()
+            event.stop()
+            self._host.post_working_dir_clicked()

chrys/app/tui/widgets/chat/compaction_card.py

@@ -0,0 +1,353 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""CompactionCard — live Phase-4 compaction status card for the main agent."""
+
+from __future__ import annotations
+
+import time
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+from textual.containers import Horizontal, Vertical
+from textual.content import Content
+from textual.message import Message
+from textual.reactive import reactive
+from textual.widgets import Static
+
+from chrys.app.tui.clipboard import OSC52_COPY_MAX_BYTES, copy_text_to_clipboards
+from chrys.app.tui.copy_messages import COPIED_TITLE
+from chrys.app.tui.i18n import render_str, widget_localizer
+from chrys.app.tui.util.static_update import update_static_in_place
+from chrys.app.tui.widgets.chat.tool_call import (
+    TOOL_COPY_EXCLUDED_CLASS,
+    ToolCopyButton,
+    ToolCopyExcludedMixin,
+    fmt_duration,
+)
+from chrys.app.tui.widgets.click_affordance import ClickAffordance
+from chrys.app.tui.widgets.loading import ChrysLoadingIndicator
+from chrys.app.tui.widgets.markdown import VirtualizedMarkdown
+from chrys.foundation.i18n import DisplayBlock, msg
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+    from textual.timer import Timer
+
+
+_COMPACTION_SUMMARY_COPIED = msg(
+    "tui.compaction.copy.summary",
+    fallback="Copied compaction summary",
+)
+_COMPACTION_SUMMARY_COPIED_UNAVAILABLE = msg(
+    "tui.compaction.copy.summary_unavailable",
+    fallback="Copied compaction summary (terminal clipboard unavailable)",
+)
+_COMPACTION_COPY_SUMMARY_TOOLTIP = msg(
+    "tui.compaction.copy.summary_tooltip",
+    fallback="Copy summary markdown",
+)
+_COMPACTION_SUMMARY_TITLE = msg("tui.compaction.summary_title", fallback="Summary")
+_COMPACTION_LABEL_RUNNING = msg("tui.compaction.label_running", fallback="Compacting conversation...")
+_COMPACTION_LABEL_SUMMARIZED = msg("tui.compaction.label_summarized", fallback="Conversation summarized")
+_COMPACTION_LABEL_INTERRUPTED = msg("tui.compaction.label_interrupted", fallback="Compaction interrupted")
+_COMPACTION_LABEL_FAILED = msg("tui.compaction.label_failed", fallback="Compaction failed")
+_COMPACTION_LABEL_FAILED_REASON = msg(
+    "tui.compaction.label_failed_reason",
+    fallback="Compaction failed ({reason})",
+    multiline=True,
+)
+_COMPACTION_RETRY_NOTICE = msg(
+    "tui.compaction.retry_notice",
+    fallback="⚠ {message} — retrying in {delay_seconds}s ({attempt}/{max_attempts})",
+    multiline=True,
+)
+
+
+class CompactionCardTitle(ToolCopyExcludedMixin, ClickAffordance):
+    """Clickable compaction card header — posts Clicked message on click."""
+
+    class Clicked(Message):
+        """Posted when the header is clicked."""
+
+    CLICK_MESSAGE = Clicked
+
+
+class CompactionCard(Vertical):
+    """Live status card for one Phase-4 "compact the conversation" pass.
+
+    Mounted inline in the transcript's tool flow when the backend publishes
+    ``CompactionStarted``: a loading indicator plus a "Compacting
+    conversation..." label with a live elapsed timer.  On
+    ``CompactionFinished`` the header flips to "Conversation summarized"
+    (or a failed/interrupted variant) and, when the LAST_WORDS note text is
+    available, a bordered unlimited-height markdown panel with the note is
+    attached below (collapsed by default) — mirroring the sub-agent result
+    rendering.  Like a ``ToolGroup``, the header acts as the expand/collapse
+    toggle, and a trailing ``copy`` affordance copies the raw note markdown.
+    """
+
+    DEFAULT_CSS = """
+    CompactionCard {
+        height: auto;
+        padding: 0 0 0 2;
+        margin: 0 0 1 0;
+    }
+    CompactionCard > #compaction-header {
+        height: 1;
+    }
+    CompactionCard > #compaction-header > ChrysLoadingIndicator {
+        width: 6;
+        height: 1;
+        margin: 0 1 0 0;
+        color: $accent;
+    }
+    CompactionCard > #compaction-header > #compaction-label {
+        width: auto;
+        height: 1;
+        color: $accent;
+    }
+    CompactionCard.-finished > #compaction-header > #compaction-label {
+        color: $text-muted;
+    }
+    CompactionCard > #compaction-header > ToolCopyButton {
+        display: none;
+        width: auto;
+        height: 1;
+        margin: 0 0 0 2;
+        color: $text-muted;
+        text-style: dim;
+        pointer: pointer;
+    }
+    CompactionCard > #compaction-header > ToolCopyButton:hover {
+        color: $accent;
+        text-style: underline not dim;
+    }
+    CompactionCard > #compaction-retry-notice {
+        display: none;
+        height: auto;
+        color: $warning;
+        margin: 0 0 0 2;
+    }
+    CompactionCard.-done > #compaction-header > ToolCopyButton {
+        display: block;
+    }
+    CompactionCard > #compaction-note-panel {
+        display: none;
+        height: auto;
+        margin: 0 0 0 2;
+        border: round $tui-border-success 30%;
+        border-title-color: $success;
+        border-title-style: not bold;
+        padding: 0 1;
+    }
+    CompactionCard.-done > #compaction-note-panel {
+        display: block;
+    }
+    CompactionCard.-done.-collapsed > #compaction-note-panel {
+        display: none;
+    }
+    CompactionCard > #compaction-note-panel > #compaction-note {
+        height: auto;
+    }
+    """
+
+    collapsed: reactive[bool] = reactive(False)
+
+    # LLM side calls fail transiently often but usually recover by the
+    # second or third attempt — the first few retry notices stay hidden so
+    # a self-healing compaction never alarms the user.
+    QUIET_RETRY_NOTICES = 3
+
+    def __init__(self, compaction_id: str) -> None:
+        super().__init__()
+        self.compaction_id = compaction_id
+        self.status = "running"
+        self._start_time = time.monotonic()
+        self._duration_ms = 0
+        self._has_note = False
+        self._last_words = ""
+        self._failure_reason = ""
+        self._retry_notice_count = 0
+        self._timer: Timer | None = None
+
+    def compose(self) -> ComposeResult:
+        # The whole header row is chrome (spinner glyphs, title, copy
+        # affordance) — excluded from drag-selection copy; only the note
+        # panel below carries selectable prose.
+        header = Horizontal(id="compaction-header")
+        header.add_class(TOOL_COPY_EXCLUDED_CLASS)
+        with header:
+            yield ChrysLoadingIndicator()
+            yield CompactionCardTitle(self._running_label_text(), id="compaction-label")
+            yield ToolCopyButton(tooltip_message=_COMPACTION_COPY_SUMMARY_TOOLTIP.bind())
+        yield Static("", id="compaction-retry-notice")
+        with Vertical(id="compaction-note-panel") as panel:
+            panel.border_title = render_str(widget_localizer(self), _COMPACTION_SUMMARY_TITLE.bind())
+            yield VirtualizedMarkdown("", id="compaction-note")
+
+    def on_mount(self) -> None:
+        self._timer = self.set_interval(1.0, self._tick)
+
+    def on_unmount(self) -> None:
+        self._stop_timer()
+
+    def _stop_timer(self) -> None:
+        if self._timer is not None:
+            self._timer.stop()
+            self._timer = None
+
+    def _tick(self) -> None:
+        if self.status != "running":
+            return
+        with suppress(Exception):
+            update_static_in_place(self.query_one("#compaction-label", Static), self._running_label_text())
+
+    def _running_label_text(self) -> Content:
+        # Accent title (widget CSS) with a dim elapsed trail — matching the
+        # terminal labels below and the StatusBar trail's visual tone.
+        # ``$text-muted`` ("auto 60%") resolves against the card surface and
+        # renders visibly brighter than the StatusBar's CSS-colored trail.
+        # Localized text enters only via ``$``-substitution, which keeps it
+        # literal — the markup skeletons stay prose-free.
+        label = render_str(widget_localizer(self), _COMPACTION_LABEL_RUNNING.bind())
+        elapsed_ms = int((time.monotonic() - self._start_time) * 1000)
+        if elapsed_ms >= 1000:
+            return Content.from_markup(
+                "[b]$label[/b] [dim]($elapsed)[/]",
+                label=label,
+                elapsed=fmt_duration(elapsed_ms),
+            )
+        return Content.from_markup("[b]$label[/b]", label=label)
+
+    def _final_label_text(self) -> Content:
+        # Terminal tones come from the theme ($warning/$error), not literal
+        # colors — Rich styles cannot resolve Textual variables, so the label
+        # goes through Content markup like the running label above.
+        localizer = widget_localizer(self)
+        elapsed = f" [dim]({fmt_duration(self._duration_ms)})[/]" if self._duration_ms else ""
+        if self.status == "ok":
+            prefix = ("▶ " if self.collapsed else "▼ ") if self._has_note else "• "
+            label = render_str(localizer, _COMPACTION_LABEL_SUMMARIZED.bind())
+            return Content.from_markup(f"[b]{prefix}$label[/b] [$success]✓[/]{elapsed}", label=label)
+        if self.status == "canceled":
+            label = render_str(localizer, _COMPACTION_LABEL_INTERRUPTED.bind())
+            return Content.from_markup(f"[$warning]✗ $label[/]{elapsed}", label=label)
+        if self._failure_reason:
+            # A safety-limit trip reason replaces the (meaningless fast-fail)
+            # duration — "Compaction failed (100 attempts limit exceeded for
+            # current turn)".  DisplayBlock keeps the reason text literal.
+            label = render_str(
+                localizer,
+                _COMPACTION_LABEL_FAILED_REASON.bind(reason=DisplayBlock(self._failure_reason)),
+            )
+            return Content.from_markup("[$error]✗ $label[/]", label=label)
+        label = render_str(localizer, _COMPACTION_LABEL_FAILED.bind())
+        return Content.from_markup(f"[$error]✗ $label[/]{elapsed}", label=label)
+
+    def _refresh_final_label(self) -> None:
+        with suppress(Exception):
+            self.query_one("#compaction-label", Static).update(self._final_label_text())
+
+    def watch_collapsed(self, collapsed: bool) -> None:
+        self.set_class(collapsed, "-collapsed")
+        if self.status != "running":
+            self._refresh_final_label()
+
+    def on_compaction_card_title_clicked(self) -> None:
+        """Toggle the summary panel, mirroring the ToolGroup header."""
+        if not self._has_note:
+            return
+        self.collapsed = not self.collapsed
+
+    def on_tool_copy_button_clicked(self, event: ToolCopyButton.Clicked) -> None:
+        """Copy the raw LAST_WORDS markdown to the clipboards."""
+        event.stop()
+        if not self._last_words:
+            return
+        localizer = widget_localizer(self)
+        if copy_text_to_clipboards(self.app, self._last_words, max_terminal_bytes=OSC52_COPY_MAX_BYTES):
+            self.notify(
+                render_str(localizer, _COMPACTION_SUMMARY_COPIED.bind()),
+                title=render_str(localizer, COPIED_TITLE.bind()),
+                timeout=2,
+                markup=False,
+            )
+        else:
+            self.notify(
+                render_str(localizer, _COMPACTION_SUMMARY_COPIED_UNAVAILABLE.bind()),
+                title=render_str(localizer, COPIED_TITLE.bind()),
+                timeout=3,
+                markup=False,
+            )
+
+    def show_retry_notice(self, message: str, attempt: int, max_attempts: int, delay_seconds: int) -> None:
+        """Show a side-call retry as a quiet warning line inside the card.
+
+        The first ``QUIET_RETRY_NOTICES`` notices are counted but not
+        displayed; from the next one on, the latest notice replaces the
+        line.  Rendered in the warning tone — the generation is still
+        auto-retrying, so this is not an error state.
+        """
+        if self.status != "running":
+            return
+        self._retry_notice_count += 1
+        if self._retry_notice_count <= self.QUIET_RETRY_NOTICES:
+            return
+        with suppress(Exception):
+            notice = self.query_one("#compaction-retry-notice", Static)
+            # Content keeps provider-derived error text literal — square
+            # brackets in it must not be parsed as Textual markup.
+            notice.update(
+                Content(
+                    render_str(
+                        widget_localizer(self),
+                        _COMPACTION_RETRY_NOTICE.bind(
+                            message=DisplayBlock(message),
+                            delay_seconds=delay_seconds,
+                            attempt=attempt,
+                            max_attempts=max_attempts,
+                        ),
+                    )
+                )
+            )
+            notice.display = True
+
+    def set_complete(
+        self,
+        *,
+        outcome: str,
+        duration_ms: int = 0,
+        last_words: str = "",
+        failure_reason: str = "",
+    ) -> None:
+        """Finalize the card; reveal the note panel when a note exists.
+
+        Idempotent — the first terminal outcome wins, so a dangling-card
+        sweep on run end cannot overwrite a real ``CompactionFinished``.
+        """
+        if self.status != "running":
+            return
+        self.status = outcome or "failed"
+        self._duration_ms = duration_ms
+        self._failure_reason = failure_reason if self.status == "failed" else ""
+        self._stop_timer()
+        # Drop the live accent styling: finished cards return to the muted
+        # transcript tone (ok) or their inline yellow/red terminal styles.
+        self.add_class("-finished")
+        # Any terminal state supersedes a lingering retry notice: success
+        # proves recovery, and failure/cancel carry their own label.
+        with suppress(Exception):
+            self.query_one("#compaction-retry-notice", Static).display = False
+        if self.status == "ok" and last_words:
+            self._has_note = True
+            self._last_words = last_words
+            with suppress(Exception):
+                self.query_one("#compaction-note", VirtualizedMarkdown).update(last_words)
+                self.add_class("-done")
+            # Collapsed by default — the summary only unfolds on an explicit
+            # header click, so a mid-run compaction doesn't flood the
+            # transcript with a page of markdown.
+            self.collapsed = True
+        with suppress(Exception):
+            self.query_one(ChrysLoadingIndicator).display = False
+        self._refresh_final_label()