shikiru-cli 0.2.0__py3-none-any.whl

shikiru/dashboard/fault_guidance.py

@@ -0,0 +1,216 @@
+"""Operator-facing summary and evidence of an open engine fault, from what was recorded."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from shikiru.dashboard.contract import EngineFaultView, FaultDetailRow
+from shikiru.engine.pull_request_closing import CLOSE_FAULT_SCOPE
+from shikiru.engine.push_service import PUSH_FAULT_SCOPE, REMOTE_CHECK_FAULT_SCOPE
+
+if TYPE_CHECKING:
+    from shikiru.domain.faults import FaultStreak
+
+_RECONCILE_SCOPE_PREFIX = "reconcile "
+_NOT_RECORDED = "not recorded"
+_KEY_SEPARATOR = "\x00"
+_CAUSE_LIMIT = 160
+_ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+
+
+class Recovery(StrEnum):
+    """How Shikiru itself retries a fault: the distinctions the Operator plans around."""
+
+    BACKOFF = "backoff"
+    BOUNDED = "bounded"
+    STARTUP_ONLY = "startup-only"
+    UNKNOWN = "unknown"
+
+
+_STATUS = {
+    Recovery.BACKOFF: "Retrying automatically",
+    Recovery.BOUNDED: "Retrying a few times, then waiting for an engine restart",
+    Recovery.STARTUP_ONLY: "Retried only at the next engine start",
+    Recovery.UNKNOWN: "Retry timing unknown",
+}
+_UNEXPECTED_BACKOFF_STATUS = "Unexpected error · retrying automatically"
+_UNRECOVERABLE_STEP = "Inspect the traceback and fix the unexpected error"
+_UNKNOWN_CAUSE = "unknown: no error text was recorded"
+_UNKNOWN_IMPACT = "not recorded for this kind of fault"
+_UNKNOWN_STEP = "Read the cause in Details; no retry is known for this fault"
+_RESTART_STEP = "Fix the cause, then restart the engine to retry sooner"
+_LEGACY_COMMAND_FAILURE = re.compile(
+    r"(?:CommandFailed: )?command .*?\) exited (-?\d+):\s*(.*)\Z", re.DOTALL
+)
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """The configured retry numbers the recovery descriptions quote."""
+
+    backoff_initial_seconds: float
+    backoff_max_seconds: float
+    close_attempts: int
+
+
+def _target(scope: str, prefix: str) -> str | None:
+    head = f"{prefix} "
+    return scope.removeprefix(head) if scope.startswith(head) else None
+
+
+def recovery_of(scope: str, *, recoverable: bool) -> Recovery:
+    """Return how `scope` is retried; a scope this view does not know retries at unknown times.
+
+    Whether the error is `recoverable` (environmental) does not change who schedules the retry,
+    except that the pull request close loop only retries environmental errors.
+    """
+    if _target(scope, PUSH_FAULT_SCOPE) is not None or _target(scope, REMOTE_CHECK_FAULT_SCOPE):
+        return Recovery.BACKOFF
+    if scope == CLOSE_FAULT_SCOPE:
+        return Recovery.BOUNDED if recoverable else Recovery.UNKNOWN
+    if scope.startswith(_RECONCILE_SCOPE_PREFIX):
+        return Recovery.STARTUP_ONLY
+    return Recovery.UNKNOWN
+
+
+def _impact_and_step(scope: str) -> tuple[str, str] | None:
+    base = _target(scope, PUSH_FAULT_SCOPE)
+    if base is not None:
+        return (
+            f"commits on {base} stay local",
+            "Fix the cause git reports; Shikiru never forces a push",
+        )
+    if _target(scope, REMOTE_CHECK_FAULT_SCOPE) is not None:
+        return (
+            "no base is pushed until the remote can be read",
+            "Fix the git remote configuration, for example a malformed .git/config",
+        )
+    if scope == CLOSE_FAULT_SCOPE:
+        return "the pull request is not closed", _RESTART_STEP
+    if scope.startswith(_RECONCILE_SCOPE_PREFIX):
+        return "a startup recovery step did not complete", _RESTART_STEP
+    return None
+
+
+def _policy_text(recovery: Recovery, policy: RetryPolicy) -> str:
+    backoff = f"{policy.backoff_initial_seconds:g}s doubling up to {policy.backoff_max_seconds:g}s"
+    return {
+        Recovery.BACKOFF: (
+            f"background push service logs failures and retries with backoff ({backoff}) "
+            "while the engine runs, even if the guard reaches its unexpected fault limit"
+        ),
+        Recovery.BOUNDED: (
+            f"up to {policy.close_attempts} attempts with backoff, {backoff}; "
+            "then again only at the next engine start"
+        ),
+        Recovery.STARTUP_ONLY: "attempted again only at the next engine start",
+        Recovery.UNKNOWN: "not recorded for this kind of fault",
+    }[recovery]
+
+
+def _is_logged(scope: str) -> bool:
+    return (
+        _target(scope, PUSH_FAULT_SCOPE) is not None
+        or _target(scope, REMOTE_CHECK_FAULT_SCOPE) is not None
+        or scope.startswith(_RECONCILE_SCOPE_PREFIX)
+    )
+
+
+def _shorten(text: str) -> str:
+    one_line = " ".join(text.split())
+    return one_line if len(one_line) <= _CAUSE_LIMIT else one_line[: _CAUSE_LIMIT - 1] + _ELLIPSIS
+
+
+def _recorded_error(fault: FaultStreak) -> str:
+    if fault.detail is not None:
+        return fault.detail
+    return fault.message.removeprefix(f"{fault.scope} failed: ")
+
+
+def _legacy_command_cause(error: str) -> str | None:
+    match = _LEGACY_COMMAND_FAILURE.fullmatch(error)
+    if match is None:
+        return None
+    exit_code, stderr = match.groups()
+    return f"exit {exit_code}: {stderr.strip()}" if stderr.strip() else f"exit {exit_code}"
+
+
+def _cause(fault: FaultStreak) -> str:
+    if fault.exit_code is not None:
+        stderr = (fault.stderr or "").strip()
+        return _shorten(
+            f"exit {fault.exit_code}: {stderr}" if stderr else f"exit {fault.exit_code}"
+        )
+    error = _recorded_error(fault)
+    return _shorten(_legacy_command_cause(error) or error) or _UNKNOWN_CAUSE
+
+
+def _command_rows(fault: FaultStreak) -> tuple[FaultDetailRow, ...]:
+    command = _NOT_RECORDED if fault.command is None else shlex.join(fault.command)
+    exit_code = _NOT_RECORDED if fault.exit_code is None else str(fault.exit_code)
+    return (
+        FaultDetailRow("Command", command),
+        FaultDetailRow("Exit code", exit_code),
+        FaultDetailRow("Stderr", _NOT_RECORDED if fault.stderr is None else fault.stderr.strip()),
+    )
+
+
+def _details(
+    fault: FaultStreak,
+    recovery: Recovery,
+    policy: RetryPolicy,
+    *,
+    log_path: str,
+    state_path: str,
+) -> tuple[FaultDetailRow, ...]:
+    logged = (
+        (FaultDetailRow("Log", f"{log_path} (traceback of each failed attempt)"),)
+        if _is_logged(fault.scope)
+        else ()
+    )
+    return (
+        FaultDetailRow("Error", _recorded_error(fault).strip() or _UNKNOWN_CAUSE),
+        *_command_rows(fault),
+        FaultDetailRow("First seen", fault.first_seen.isoformat()),
+        FaultDetailRow("Latest", fault.last_seen.isoformat()),
+        FaultDetailRow("Failures", str(fault.repeat)),
+        FaultDetailRow(
+            "Classification",
+            "environmental failure" if fault.recoverable else "unexpected software error",
+        ),
+        FaultDetailRow("Retry policy", _policy_text(recovery, policy)),
+        FaultDetailRow("Next retry", _NOT_RECORDED),
+        FaultDetailRow("Traceback", _NOT_RECORDED if fault.traceback is None else fault.traceback),
+        FaultDetailRow("Event", f"#{fault.event_id} in {state_path}"),
+        *logged,
+    )
+
+
+def engine_fault_view(
+    fault: FaultStreak, policy: RetryPolicy, *, log_path: str, state_path: str
+) -> EngineFaultView:
+    """Describe the open `fault` as a card summary plus the evidence recorded for it."""
+    recovery = recovery_of(fault.scope, recoverable=fault.recoverable)
+    known = _impact_and_step(fault.scope)
+    impact, step = known if known is not None else (_UNKNOWN_IMPACT, _UNKNOWN_STEP)
+    if not fault.recoverable:
+        step = _UNRECOVERABLE_STEP
+    return EngineFaultView(
+        key=f"{fault.task_id or ''}{_KEY_SEPARATOR}{fault.scope}",
+        task_id=fault.task_id,
+        scope=fault.scope,
+        status=(
+            _UNEXPECTED_BACKOFF_STATUS
+            if recovery is Recovery.BACKOFF and not fault.recoverable
+            else _STATUS[recovery]
+        ),
+        impact=impact,
+        cause=_cause(fault),
+        next_step=step,
+        needs_action=recovery is not Recovery.BACKOFF or not fault.recoverable,
+        details=_details(fault, recovery, policy, log_path=log_path, state_path=state_path),
+    )

shikiru/dashboard/fold_bodies.py

@@ -0,0 +1,276 @@
+"""Bodies of the Results and Decisions folds: grey labels, white values, one row per fact."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.console import Group
+from rich.text import Text
+
+from shikiru.dashboard.briefing_view import (
+    BRANCH_ARROW,
+    BRANCH_LABEL,
+    COMMITS_LABEL,
+    MINUS,
+    PR_LABEL,
+    RISKS_LABEL,
+    SUMMARY_LABEL,
+    TESTS_LABEL,
+    branch_row,
+    decision_rows,
+    live_unavailable_rows,
+    pull_request_groups,
+    tests_groups,
+)
+from shikiru.domain.acceptance import request_without_criteria_section
+from shikiru.domain.decisions import Decider
+from shikiru.domain.results import ResultOutcome
+from shikiru.ui.section import BOLD_STEEL, Row, grey, labelled_rows
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    AMBER,
+    STEEL_BLUE,
+    SUCCESS_COLOR,
+)
+
+if TYPE_CHECKING:
+    from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+
+    from shikiru.dashboard.contract import TaskDetailView
+    from shikiru.domain.briefing import ProducedNumbers
+    from shikiru.domain.decisions import DecisionEntry
+    from shikiru.domain.results import PlanChange, TaskResults
+
+PRIORITY_WORDS = {0: "standard", 1: "high", -1: "low"}
+CHANGES_LABEL = "Changes"
+PLAN_LABEL = "Plan"
+OPEN_LABEL = "Open"
+NOTHING_RECORDED = "Nothing is recorded yet."
+CRITERIA_LABEL = "Acceptance criteria"
+NO_CRITERIA = "No validated acceptance criteria are recorded."
+CRITERION_LEAD = "\N{BULLET} "
+PATH_LABEL = "Path"
+HOME_MARK = "~"
+MODE_LABEL = "Mode"
+SUBMITTED_LABEL = "Submitted"
+REQUEUED_LABEL = "Requeued"
+STATUS_REASON_LABEL = "Status reason"
+PRIORITY_LABEL = "Priority"
+MORE_COMMITS = "+{count} more"
+ADDED_TASK = "added {id}"
+CLOCK_FORMAT = "%H:%M"
+TIME_GAP = "  "
+DECIDER_WIDTH = max(len(decider.value) for decider in Decider)
+
+
+def _counted(count: int, noun: str) -> str:
+    return f"{count} {noun}{'' if count == 1 else 's'}"
+
+
+def _stacked(label: str, lines: list[Text]) -> list[Row]:
+    return [(grey(label if index == 0 else ""), (line,)) for index, line in enumerate(lines)]
+
+
+def _commit_rows(results: TaskResults) -> list[Row]:
+    lines = [
+        Text.assemble(Text(commit.sha, style=STEEL_BLUE), TIME_GAP, commit.subject)
+        for commit in results.commits
+    ]
+    if results.more_commits:
+        lines.append(grey(MORE_COMMITS.format(count=results.more_commits)))
+    return _stacked(COMMITS_LABEL, lines)
+
+
+def _changes_groups(produced: ProducedNumbers | None) -> tuple[Text, ...]:
+    if produced is None:
+        return ()
+    return (
+        Text.assemble(
+            _counted(produced.files, "file"),
+            TIME_GAP,
+            (f"+{produced.insertions}", SUCCESS_COLOR),
+            " ",
+            (f"{MINUS}{produced.deletions}", ALERT_COLOR),
+        ),
+    )
+
+
+def _plan_lines(change: PlanChange) -> list[Text]:
+    added = [
+        Text(ADDED_TASK.format(id=" ".join(filter(None, task))), style=SUCCESS_COLOR)
+        for task in change.new_tasks
+    ]
+    return [*added, *(Text(scope) for scope in change.scope_changes)]
+
+
+def _summary_rows(results: TaskResults) -> list[Row]:
+    if results.plan_summary is None:
+        return []
+    return [(grey(SUMMARY_LABEL), (Text(results.plan_summary),))]
+
+
+def _results_rows(results: TaskResults) -> list[Row]:
+    optional = (
+        (CHANGES_LABEL, _changes_groups(results.produced)),
+        (TESTS_LABEL, tests_groups(results.tests)),
+        (PR_LABEL, pull_request_groups(results.pull_request)),
+    )
+    plan = _stacked(
+        PLAN_LABEL, [line for change in results.plan_changes for line in _plan_lines(change)]
+    )
+    lead = [*plan, *_summary_rows(results)] if results.plan_summary is not None else []
+    return [
+        *live_unavailable_rows(results),
+        *lead,
+        *branch_row(results),
+        *_commit_rows(results),
+        *((grey(label), groups) for label, groups in optional if groups),
+        *([] if lead else plan),
+        *_stacked(RISKS_LABEL, [Text(risk, style=AMBER) for risk in results.residual_risks]),
+    ]
+
+
+def _body(width: int, rows: list[Row], notes: list[Text]) -> RenderableType:
+    if not rows:
+        return Group(*notes, grey(NOTHING_RECORDED))
+    label_width = max(len(label.plain) for label, _ in rows)
+    return Group(*notes, labelled_rows(rows, width, label_width))
+
+
+@dataclass(frozen=True)
+class ResultsBody:
+    """The Results fold body: where the work went, what it contains and what is left open."""
+
+    results: TaskResults | None
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the so-far note when work is in progress, then the labelled rows."""
+        del console
+        results = self.results
+        rows = _results_rows(results) if results is not None else []
+        so_far = results is not None and results.outcome is ResultOutcome.SO_FAR
+        yield _body(
+            options.max_width, rows, [grey(ResultOutcome.SO_FAR.value)] if so_far and rows else []
+        )
+
+
+def _decision_row(entry: DecisionEntry) -> Row:
+    decider = Text(entry.decider.value.ljust(DECIDER_WIDTH), style=STEEL_BLUE)
+    label = Text.assemble(grey(entry.at.strftime(CLOCK_FORMAT)), TIME_GAP, decider)
+    return label, (
+        Text("\n").join([Text(entry.headline), *(grey(line) for line in entry.details)]),
+    )
+
+
+def _decision_rows(view: TaskDetailView) -> list[Row]:
+    rows = decision_rows(view, OPEN_LABEL)
+    if view.decisions is not None:
+        rows.extend(_decision_row(entry) for entry in view.decisions.entries)
+    return rows
+
+
+@dataclass(frozen=True)
+class DecisionsBody:
+    """The Decisions fold body: the open question, then every decision oldest first."""
+
+    view: TaskDetailView
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the labelled rows in order, or the nothing-recorded note."""
+        del console
+        yield _body(options.max_width, _decision_rows(self.view), [])
+
+
+@dataclass(frozen=True)
+class DescriptionBody:
+    """The Task description fold body: the request, then the acceptance criteria as a list.
+
+    When the criteria are listed, the request's own criteria section is left out of the text so
+    each criterion is shown once.
+    """
+
+    view: TaskDetailView
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the request text and the criteria list."""
+        del console, options
+        criteria = self.view.acceptance_criteria
+        request = self.view.request
+        if criteria:
+            request = request_without_criteria_section(request)
+        yield Text(request)
+        yield Text(CRITERIA_LABEL, style=BOLD_STEEL)
+        if not criteria:
+            yield grey(NO_CRITERIA)
+        for item in criteria:
+            yield Text.assemble(grey(CRITERION_LEAD), item)
+
+
+def home_shortened(path: str, home: Path) -> str:
+    """Return `path` as `~/...` when it lies under `home`, otherwise unchanged."""
+    location = Path(path)
+    return (
+        str(Path(HOME_MARK) / location.relative_to(home)) if location.is_relative_to(home) else path
+    )
+
+
+def _workspace_rows(view: TaskDetailView, home: Path) -> list[Row]:
+    rows: list[Row] = []
+    if view.branch:
+        base = view.results.base if view.results is not None else None
+        target = view.branch if base is None else f"{view.branch} {BRANCH_ARROW} {base}"
+        rows.append((grey(BRANCH_LABEL), (Text(target),)))
+    rows.append((grey(PATH_LABEL), (Text(home_shortened(view.worktree_path, home)),)))
+    return rows
+
+
+@dataclass(frozen=True)
+class WorkspaceBody:
+    """The Workspace fold body: the task branch and where its worktree lives."""
+
+    view: TaskDetailView
+    home: Path
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the labelled branch and path rows."""
+        del console
+        yield _body(options.max_width, _workspace_rows(self.view, self.home), [])
+
+
+def priority_word(priority: int) -> str:
+    """Name a dispatch priority: `standard` at 0, `high` above it and `low` below it."""
+    return PRIORITY_WORDS[(priority > 0) - (priority < 0)]
+
+
+def _present(value: str | None, style: str = "") -> Text | None:
+    return Text(value, style=style) if value else None
+
+
+def _settings_rows(view: TaskDetailView) -> list[Row]:
+    entries = (
+        (MODE_LABEL, _present(view.mode)),
+        (SUBMITTED_LABEL, _present(view.submitted_age)),
+        (REQUEUED_LABEL, _present(view.requeued_age)),
+        (STATUS_REASON_LABEL, _present(view.status_reason, AMBER)),
+        (
+            PRIORITY_LABEL,
+            None
+            if view.priority is None
+            else Text(f"{priority_word(view.priority)} ({view.priority})"),
+        ),
+    )
+    return [(grey(label), (value,)) for label, value in entries if value is not None]
+
+
+@dataclass(frozen=True)
+class SettingsBody:
+    """The Settings fold body: mode, ages, status reason and dispatch priority."""
+
+    view: TaskDetailView
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the labelled settings rows."""
+        del console
+        yield _body(options.max_width, _settings_rows(self.view), [])

shikiru/dashboard/help_keys.py

@@ -0,0 +1,166 @@
+"""The one key table behind the Help panel: groups of key and action rows per context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from shikiru.dashboard.detail import TASK_DETAIL_VIEWS_KEY, TASK_WINDOW_KEY
+from shikiru.dashboard.resolution_view import EXTRA_DETAILS_KEY
+from shikiru.dashboard.timeline_filter import CLEAR_KEY, CYCLE_ROLE_KEY, CYCLE_TURN_KEY
+from shikiru.dashboard.timeline_section import FILTER_KEY
+
+_ARROWS = "Up/Down"
+_ESC = "Esc"
+_ENTER = "Enter"
+_PALETTE = "Ctrl+P"
+_DETACH_KEY = "d"
+_PALETTE_POPUP_KEY = "Space"
+
+
+class HelpTab(StrEnum):
+    """A Help context; the value is the tab label."""
+
+    HOME = "Home"
+    TASK = "Task details"
+    ESCALATIONS = "Escalations"
+
+
+@dataclass(frozen=True)
+class HelpRow:
+    """One key and what it does."""
+
+    keys: str
+    action: str
+
+
+@dataclass(frozen=True)
+class HelpGroup:
+    """A titled run of rows."""
+
+    title: str
+    rows: tuple[HelpRow, ...]
+
+
+@dataclass(frozen=True)
+class HelpAvailability:
+    """Which optional parts of Home exist, so their keys are listed only when they work."""
+
+    queue: bool
+    escalations: bool
+    detach_prefix: str | None
+
+
+def help_groups(tab: HelpTab, availability: HelpAvailability) -> tuple[HelpGroup, ...]:
+    """Return the groups of `tab`, with the Home keys that exist under `availability`."""
+    if tab is HelpTab.HOME:
+        return _home_groups(availability)
+    if tab is HelpTab.TASK:
+        return _task_groups()
+    return _escalation_groups()
+
+
+def _home_groups(availability: HelpAvailability) -> tuple[HelpGroup, ...]:
+    tasks = [HelpRow("Click", "Select a task and show its details")]
+    if availability.queue:
+        tasks[:0] = [
+            HelpRow(_ARROWS, "Select a task, wherever focus is"),
+            HelpRow("f", "Cycle the task status filter"),
+            HelpRow("/", "Search by task ID or title; Enter keeps it, Esc clears it"),
+            HelpRow("m", "Load more tasks, while the list shows the hint"),
+        ]
+    tasks.append(HelpRow(_ESC, "Close a popup, clear the search, then clear the selection"))
+    groups = [HelpGroup("Tasks", tuple(tasks))]
+    if availability.escalations:
+        groups.append(
+            HelpGroup(
+                "Escalations",
+                (HelpRow(_ENTER, "Open the decision"),),
+            )
+        )
+    everywhere = [
+        HelpRow(f"{_PALETTE} / F12", "Open the actions for the selected task"),
+        HelpRow("Tab", "Move to the footer, command status and resources; Enter uses them"),
+        HelpRow("?", "Show this help"),
+    ]
+    if availability.detach_prefix is not None:
+        prefix = availability.detach_prefix
+        everywhere.append(
+            HelpRow(
+                f"{prefix} {_PALETTE_POPUP_KEY}",
+                "Open the actions in any Shikiru pane (a popup in task and role panes)",
+            )
+        )
+        everywhere.append(HelpRow(f"{prefix} {_DETACH_KEY}", "Detach from tmux"))
+    groups.append(HelpGroup("Everywhere", tuple(everywhere)))
+    return tuple(groups)
+
+
+def _task_groups() -> tuple[HelpGroup, ...]:
+    return (
+        HelpGroup(
+            "Task",
+            (
+                HelpRow("Tab", "Move between the task's actions and its sections"),
+                HelpRow(_ENTER, "Run the focused action"),
+                HelpRow(TASK_DETAIL_VIEWS_KEY, "Focus task details sections"),
+                HelpRow(_PALETTE, "Open the actions for this task"),
+                HelpRow(_ESC, "Step back, then return to Home"),
+            ),
+        ),
+        HelpGroup(
+            "Sections",
+            (
+                HelpRow(_ARROWS, "Move between section headers"),
+                HelpRow(_ENTER, "Open the section, or enter its list"),
+                HelpRow("Space / click", "Open or close a section"),
+            ),
+        ),
+        HelpGroup(
+            "Lists",
+            (
+                HelpRow(_ARROWS, "Select a row"),
+                HelpRow("PgUp/PgDn", "Page through the rows"),
+                HelpRow("End", "Jump to the latest and follow"),
+                HelpRow(_ENTER, "Open the selected row"),
+                HelpRow(_ESC, "Back to the section header"),
+            ),
+        ),
+        HelpGroup(
+            "Agent activity filter",
+            (
+                HelpRow(FILTER_KEY, "Open the filter"),
+                HelpRow(CYCLE_ROLE_KEY, "Cycle the role"),
+                HelpRow(CYCLE_TURN_KEY, "Cycle the turn"),
+                HelpRow(CLEAR_KEY, "Clear the filter"),
+                HelpRow(_ESC, "Close the filter"),
+            ),
+        ),
+        HelpGroup(
+            "Workspace section",
+            (HelpRow(TASK_WINDOW_KEY, "Open the task's tmux window while its section is focused"),),
+        ),
+    )
+
+
+def _escalation_groups() -> tuple[HelpGroup, ...]:
+    return (
+        HelpGroup(
+            "Choose",
+            (
+                HelpRow(_ARROWS, "Choose an answer"),
+                HelpRow(_ENTER, "Send it, or edit or expand the chosen row"),
+                HelpRow("t", "Show or hide what was tried"),
+                HelpRow(EXTRA_DETAILS_KEY, "Open extra details (when Details is open)"),
+                HelpRow(_ESC, "Close without sending"),
+            ),
+        ),
+        HelpGroup(
+            "Write an answer",
+            (
+                HelpRow("Ctrl+S", "Send the typed answer"),
+                HelpRow(_ESC, "Back to the choices"),
+            ),
+        ),
+        HelpGroup("Cancel the task", (HelpRow(_ENTER, "Press Enter again to confirm"),)),
+    )