gitpane 1.0.0__py3-none-any.whl

gitpane/operation/operation_trace.py

@@ -0,0 +1,766 @@
+"""Collect complete, filtered process records before exposing them to any consumer."""
+
+from __future__ import annotations
+
+import bisect
+import json
+import struct
+import tempfile
+from contextlib import ExitStack
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import LINE_SEPARATOR, TRACE_PAGE_SIZE, TRACE_STORAGE_LIMIT_BYTES, TRACE_UNIT_LIMIT_BYTES, TRACE_VIEW_LIMIT_BYTES
+from gitpane.operation.console_line import (
+    CANCELLED_TEXT,
+    FAILED_TEXT,
+    FAILED_WITH_EXIT_TEMPLATE,
+    NOT_STARTED_TEXT,
+    ConsoleLine,
+    cause_beyond_exit_code,
+    cause_without_shown_output,
+    command_line,
+    header_text,
+    line_with_cause,
+    process_end_line,
+    with_account_hint,
+)
+from gitpane.operation.console_tone import ConsoleTone, git_output_tone, result_tone
+from gitpane.operation.diagnostic import OPAQUE_BODY_PREFIX, Diagnostic, NetworkTextStream, PreparedDiagnostic, SensitiveTextFilter, SensitiveTextStream, TextUnit, TextUnitEnd, TextValueSource
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.process.process_runner import CREDENTIAL_PROFILE, NETWORK_PROFILE, READ_PROFILE
+from gitpane.transport.git_refusal import is_trace_line
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.operation.console_line import ConsoleHeader
+    from gitpane.operation.diagnostic import DiagnosticLog
+    from gitpane.process.process_runner import ProcessRequest, ProcessResult, ProcessRunner
+
+
+# Records of these kinds are errors GitPane reports itself, shown red unless the caller gives another tone.
+FAILURE_KIND_SET = frozenset({"error", "incomplete"})
+# Records of these kinds are what a process wrote; only they can be the description of a binary output.
+PROCESS_OUTPUT_KIND_SET = frozenset({"stdout", "stderr", "http-body"})
+# Kind of the event that tells the view about a console-only line, which is never stored as a record nor logged.
+CONSOLE_ONLY_KIND = "console"
+
+
+def publish_after_trace(publish: Callable[[], None], context: QObject | None = None) -> None:
+    """Call ``publish`` one event-loop turn later, once the operation's trace has heard the process that just ended.
+
+    A service hears a process end before the trace of its operation does, because the trace connects to the runner's
+    ``finished`` signal after the service. Writing the result one turn later lets the trace write the ended process's
+    own line first: a diagnostic then knows that line is already on screen, and the end line stays the last line. With
+    a ``context``, the call is dropped if that object is destroyed before the turn comes.
+    """
+    if context is None:
+        QTimer.singleShot(0, publish)
+        return
+    QTimer.singleShot(0, context, publish)
+
+
+def cause_without_trace_lines(cause: str) -> str:
+    """Return a process failure cause without its trace records, for the result record written to the ``--log`` file.
+
+    A process that fails without its own explanation takes its whole standard error as cause. Its trace records already
+    went to the ``--log`` file one by one as standard error, so the result record repeats only what Git says to the user.
+    """
+    kept_lines: list[str] = []
+    for line in cause.split("\n"):
+        if not is_trace_line(line):
+            kept_lines.append(line)
+    return "\n".join(kept_lines)
+
+
+@dataclass(frozen=True)
+class TraceEvent:
+    """Carry an operation's already-filtered record with its originating process."""
+
+    operation_id: str
+    process_id: str
+    kind: str
+    text: str
+    sequence: int = 0
+
+
+@dataclass(frozen=True)
+class ToneSpan:
+    """A byte range of the console text and its colour; the view sets the tone on the Qt blocks of that range.
+
+    ``end`` is exclusive. Spans are added in text order and never overlap.
+    """
+
+    start: int
+    end: int
+    tone: ConsoleTone
+
+
+@dataclass(frozen=True)
+class OpenLine:
+    """The console's last line while the process that wrote it can still redraw it."""
+
+    process_id: str
+    kind: str
+    line_start: int
+
+
+class OperationTrace(QObject):
+    """Retain safe complete units, withholding fragments until redaction is possible."""
+
+    event_added = Signal(object)
+
+    def __init__(self, operation_id: str, runner: ProcessRunner, log: DiagnosticLog | None = None, *, native_commands_only: bool = False,
+                 header: ConsoleHeader | None = None) -> None:
+        """Subscribe to the injected runner without owning its process lifetime.
+
+        With ``native_commands_only``, the reads the operation runs for its own checks are left out: they are not
+        commands the user would type, and the console then shows only what a terminal would. They are not lost: the
+        ``--log`` file keeps one line for every finished process, written by the launcher whatever the trace keeps.
+        The status lines the application appends itself are always kept. Without it, a read still shows only its
+        ``$`` line: its standard output is recorded and logged but never shown (see ``shows_output``).
+
+        A ``header`` names the repository (or a clone's destination) once, on the first line of the console, just
+        before the first line shown: an empty trace stays empty. It is console text only and never reaches the log.
+        """
+        super().__init__()
+        self.operation_id = operation_id
+        self.runner = runner
+        self.log = log
+        self.native_commands_only = native_commands_only
+        self.header = header
+        self.header_written = False
+        self.tone_spans: list[ToneSpan] = []
+        # Processes the console already ended with their own line, and the error output each of them showed: a
+        # diagnostic about one of them adds nothing, and any diagnostic leaves out of its cause what was already shown.
+        self.ended_process_id_set: set[str] = set()
+        self.failed_outputs: list[str] = []
+        # Processes whose ``$ `` line the console wrote and that have not ended yet: a request that ends without one
+        # never started, which its end line says.
+        self.started_request_id_set: set[str] = set()
+        self.event_count = 0
+        self.stored_count = 0
+        self.storage_size = 0
+        self.text_size = 0
+        self.open_line: OpenLine | None = None
+        self.capture_failed = False
+        self.failure_event: TraceEvent | None = None
+        self.failure_text = b""
+        self.index_record = struct.Struct("!Q")
+        self.resource = ExitStack()
+        self.stream = None
+        self.index_stream = None
+        self.text_stream = None
+        self.filter = SensitiveTextFilter()
+        self.complete = True
+        self.stream_by_key: dict[tuple[str, str], SensitiveTextStream] = {}
+        self.config_buffer_by_id: dict[str, bytearray] = {}
+        self.network_stream_by_id: dict[str, NetworkTextStream] = {}
+        self.closed = False
+        self.close_requested = False
+        runner.started.connect(self._started)
+        runner.stdout_chunk.connect(self._stdout)
+        runner.stderr_chunk.connect(self._stderr)
+        runner.finished.connect(self._finished)
+        try:
+            # Anonymous private handles belong to this collector and disappear on close or process exit.
+            self.stream = self.resource.enter_context(tempfile.TemporaryFile(mode="w+b"))  # noqa: SIM115
+            self.index_stream = self.resource.enter_context(tempfile.TemporaryFile(mode="w+b"))  # noqa: SIM115
+            self.text_stream = self.resource.enter_context(tempfile.TemporaryFile(mode="w+b"))  # noqa: SIM115
+        except OSError:
+            self.mark_incomplete("Filtered output storage could not be created. Check temporary-directory permissions or available disk space.")
+
+    def append_event(self, process_id: str, kind: str, text: str, tone: ConsoleTone = ConsoleTone.NEUTRAL) -> None:
+        """Record a text and show it as it is, as a terminal would, without any label.
+
+        A Git, curl or Git Credential Manager trace record on standard error stays out of the console text and of what
+        it copies: there it buries what Git says to the user. It is still stored as a record, so a reader of the
+        records, such as a test, sees every one, and it is still written to the ``--log``
+        file, which keeps the complete output for diagnosis. Such a record notifies no view, since none shows it. The
+        one-line description that replaces a binary output is kept the same way: it says nothing a terminal would show.
+
+        Without a given tone, a line of standard error takes the colour of what Git says on it (error, warning), an
+        error GitPane reports itself is red, and anything else, the status lines GitPane writes included, is neutral.
+        """
+        self._append(process_id, kind, text, self._output_console_line(kind, text, tone), hide_trace_line=kind == "stderr", hide_opaque_body=kind in PROCESS_OUTPUT_KIND_SET)
+
+    @staticmethod
+    def _output_console_line(kind: str, text: str, tone: ConsoleTone = ConsoleTone.NEUTRAL) -> ConsoleLine:
+        """Choose an output line's colour and account hint consistently for records and redraws."""
+        is_stderr = kind == "stderr"
+        if tone == ConsoleTone.NEUTRAL:
+            if is_stderr:
+                tone = git_output_tone(text)
+            elif kind in FAILURE_KIND_SET:
+                tone = ConsoleTone.FAILURE
+        console_text = with_account_hint(text) if is_stderr else text
+        return ConsoleLine(console_text, tone)
+
+    def append_record(self, process_id: str, kind: str, text: str, console_line: ConsoleLine | None) -> None:
+        """Store and log a record as it is, and show a different, shorter line in the console, or nothing.
+
+        The ``--log`` file keeps the full detail, such as the block describing a command; the console shows what a
+        terminal would, such as the command line itself.
+        """
+        self._append(process_id, kind, text, console_line)
+
+    def append_failure_cause(self, process_id: str, text: str) -> None:
+        """Write a cause GitPane found for a failure, such as a setting that made Git refuse something, apart from Git's own lines.
+
+        It is stored as an error record, written to the ``--log`` file and shown as one console line of its own, red and
+        bold even during a pause, so the user reads in plain words why the operation failed and what to change.
+        """
+        self.append_record(process_id, "error", text, ConsoleLine(text, ConsoleTone.FAILURE_CAUSE))
+
+    def append_end_line(self, process_id: str, kind: str, log_text: str, console_text: str, status: OperationStatus, *, failure_reported: bool = False,
+                        expected_stop: bool = False) -> None:
+        """Write the line that ends an operation: its old text in the records and the ``--log`` file, the readable one in the console.
+
+        Its colour comes from ``end_tone``, the one rule every end line follows.
+        """
+        tone = self.end_tone(status, failure_reported=failure_reported, expected_stop=expected_stop)
+        self.append_record(process_id, kind, log_text, ConsoleLine(console_text, tone))
+
+    def end_tone(self, status: OperationStatus, *, failure_reported: bool = False, expected_stop: bool = False) -> ConsoleTone:
+        """Return the colour of the line that ends an operation: the only rule for an end line's colour, wherever it is written.
+
+        It is the rule of the console window, which takes an incomplete trace for a reported failure: a pause on an
+        incomplete trace ends red, as its window ends failed, so the end line and the window cannot disagree.
+        """
+        return result_tone(status, failure_reported=failure_reported or not self.complete, expected_stop=expected_stop)
+
+    def unshown_cause(self, diagnostic: PreparedDiagnostic) -> str | None:
+        """Return the part of a GitPane diagnostic's cause the console has not shown yet, or None when it has nothing to add.
+
+        This is the one place that reads a cause for the console, so a diagnostic line and an end line that carries its
+        cause cannot disagree. Nothing is added for a process the console already ended with its own line, and the error
+        output the console already showed is removed; when nothing remains, the answer is None. The runner's generic
+        sentence for a silent failure only repeats the exit code, so it becomes an empty cause: the failure still has
+        something to say (its exit code), but no words to add.
+        """
+        if diagnostic.process_id and diagnostic.process_id in self.ended_process_id_set:
+            return None
+        cause = cause_without_shown_output(diagnostic.cause, "")
+        for failed_output in self.failed_outputs:
+            cause = cause_without_shown_output(cause, failed_output)
+        if not cause:
+            return None
+        return cause_beyond_exit_code(cause, diagnostic.return_code)
+
+    def diagnostic_console_line(self, diagnostic: PreparedDiagnostic, status: OperationStatus, *, paused: bool = False) -> ConsoleLine | None:
+        """Return the one line a console shows for a GitPane diagnostic, or None when it would only repeat what is on screen.
+
+        The rules apply in this order:
+        1. a diagnostic about a process the console already ended with its own line adds nothing;
+        2. the cause loses the error output the console already showed, and an empty cause adds nothing;
+        3. the runner's generic sentence for a silent failure is never written, since the exit code already says it;
+        4. during a pause the cause explains why the operation waits, so it is shown neutral, without a word of failure,
+           and nothing is added when no cause remains;
+        5. a failure that carries an exit code (a process this console hid) reads ``Failed (exit N): <cause>``, or
+           ``Failed (exit N)`` alone when no cause remains: its failure is shown nowhere else;
+        6. an operation GitPane refused before launching Git reads ``Not started: <cause>``;
+        7. an operation the user cancelled reads ``Cancelled: <cause>``, in orange;
+        8. anything else reads ``Failed: <cause>``.
+        Failures and refusals are red. The full diagnostic block is not shown: it belongs to the ``--log`` file.
+        """
+        cause = self.unshown_cause(diagnostic)
+        if cause is None:
+            return None
+        if paused:
+            return ConsoleLine(cause) if cause else None
+        if diagnostic.return_code is not None:
+            return ConsoleLine(line_with_cause(FAILED_WITH_EXIT_TEMPLATE.format(return_code=diagnostic.return_code), cause), ConsoleTone.FAILURE)
+        if status == OperationStatus.REFUSED:
+            return ConsoleLine(line_with_cause(NOT_STARTED_TEXT, cause), ConsoleTone.FAILURE)
+        if status == OperationStatus.CANCELLED:
+            return ConsoleLine(line_with_cause(CANCELLED_TEXT, cause), ConsoleTone.CANCELLED)
+        return ConsoleLine(line_with_cause(FAILED_TEXT, cause), ConsoleTone.FAILURE)
+
+    def append_diagnostic(self, process_id: str, kind: str, diagnostic: PreparedDiagnostic, status: OperationStatus, *, paused: bool = False) -> None:
+        """Log a GitPane diagnostic as its full block and show at most one line of it, by the rules of ``diagnostic_console_line``.
+
+        ``status`` is the operation's outcome, which tells a refusal from a failure; ``paused`` tells that the
+        operation stopped to wait for the user, which the diagnostic then explains.
+        """
+        self.append_record(process_id, kind, diagnostic.detail, self.diagnostic_console_line(diagnostic, status, paused=paused))
+
+    def append_console_line(self, console_line: ConsoleLine) -> None:
+        """Show a line in the console alone, such as the end line of an operation that no record carried.
+
+        The records and the ``--log`` file stay exactly as they were: no record is stored, none is counted and nothing
+        is logged. The line goes through the same filter as every shown text, and the view is told to show it.
+        """
+        if self.closed or self.capture_failed:
+            return
+        if len(console_line.text) > TRACE_UNIT_LIMIT_BYTES or len(console_line.text.encode("utf-8", "replace")) > TRACE_UNIT_LIMIT_BYTES:
+            self.mark_incomplete("An output record exceeded the text-unit limit.")
+            return
+        line_text = self.filter.redact(console_line.text)
+        self._close_open_line()
+        display_data, tone_span = self._display(line_text, console_line.tone)
+        if self.storage_size + len(display_data) > TRACE_STORAGE_LIMIT_BYTES:
+            self.mark_incomplete("Filtered storage quota exceeded. Earlier output remains available.")
+            return
+        try:
+            self._write_display(display_data)
+        except OSError:
+            self.mark_incomplete("Filtered output could not be saved. Check available disk space. Earlier output remains available.")
+            return
+        self.storage_size += len(display_data)
+        self._displayed(display_data, tone_span)
+        self.event_added.emit(TraceEvent(self.operation_id, self.operation_id, CONSOLE_ONLY_KIND, line_text, self.event_count))
+
+    def tone_spans_between(self, start: int, end: int) -> list[ToneSpan]:
+        """Return, in text order, the coloured byte ranges that overlap the console text from ``start`` to ``end`` (exclusive)."""
+        spans: list[ToneSpan] = []
+        first_index = bisect.bisect_right(self.tone_spans, start, key=lambda span: span.end)
+        for span in self.tone_spans[first_index:]:
+            if span.start >= end:
+                break
+            spans.append(span)
+        return spans
+
+    def _display_prefix(self) -> str:
+        """Return what comes before the next shown line: a line break after earlier text, and the header before the first line."""
+        prefix = LINE_SEPARATOR if self.text_size else ""
+        if self.header is not None and not self.header_written:
+            prefix += self.filter.redact(header_text(self.header)) + LINE_SEPARATOR
+        return prefix
+
+    def _display(self, line_text: str, tone: ConsoleTone) -> tuple[bytes, ToneSpan | None]:
+        """Return the bytes a shown line adds to the console text, line break and header included, and the coloured range of the line if any."""
+        prefix_data = self._display_prefix().encode("utf-8", "replace")
+        line_data = line_text.encode("utf-8", "replace")
+        tone_span = None
+        if tone != ConsoleTone.NEUTRAL and line_data:
+            line_start = self.text_size + len(prefix_data)
+            tone_span = ToneSpan(line_start, line_start + len(line_data), tone)
+        return prefix_data + line_data, tone_span
+
+    def _write_display(self, display_data: bytes) -> None:
+        """Write shown bytes at the end of the console text, flushed so that a full disk fails here; raise OSError on failure."""
+        self.text_stream.seek(self.text_size)
+        self.text_stream.write(display_data)
+        self.text_stream.flush()
+
+    def _displayed(self, display_data: bytes, tone_span: ToneSpan | None) -> None:
+        """Count written console bytes as shown: the header is now on screen and the line keeps its colour."""
+        self.text_size += len(display_data)
+        self.header_written = True
+        if tone_span is not None:
+            self.tone_spans.append(tone_span)
+
+    def stable_size(self) -> int:
+        """Return the size of the console prefix that no later write can change."""
+        if self.open_line is not None:
+            return self.open_line.line_start
+        return self.text_size + len(self.failure_text)
+
+    def _close_open_line(self) -> None:
+        """Keep the last drawn value as finished text before another line is written."""
+        self.open_line = None
+
+    def _rewrite_open_line(self, line_text: str, tone: ConsoleTone) -> bool:
+        """Replace only the open line's bytes, counting the size difference against storage limits."""
+        line_start = self.open_line.line_start
+        line_data = line_text.encode("utf-8", "replace")
+        size_difference = line_start + len(line_data) - self.text_size
+        if self.storage_size + size_difference > TRACE_STORAGE_LIMIT_BYTES:
+            self.mark_incomplete("Filtered storage quota exceeded. Earlier output remains available.")
+            return False
+        try:
+            self.text_stream.seek(line_start)
+            self.text_stream.write(line_data)
+            self.text_stream.truncate()
+            self.text_stream.flush()
+        except OSError:
+            self.mark_incomplete("Filtered output could not be saved. Check available disk space. Earlier output remains available.")
+            return False
+        self.storage_size += size_difference
+        self.text_size = line_start + len(line_data)
+        last_span_index = -1
+        if self.tone_spans and self.tone_spans[last_span_index].start >= line_start:
+            self.tone_spans.pop()
+        if tone != ConsoleTone.NEUTRAL and line_data:
+            self.tone_spans.append(ToneSpan(line_start, self.text_size, tone))
+        return True
+
+    def _draw_open_line(self, process_id: str, kind: str, value: str) -> None:
+        """Show a filtered redraw without adding a stored record or a log line."""
+        if self.closed or self.capture_failed:
+            return
+        console_line = self._output_console_line(kind, value)
+        line_text = self.filter.redact(console_line.text)
+        if self.open_line is not None and (self.open_line.process_id, self.open_line.kind) == (process_id, kind):
+            if not self._rewrite_open_line(line_text, console_line.tone):
+                return
+        else:
+            self._close_open_line()
+            display_data, tone_span = self._display(line_text, console_line.tone)
+            line_start = self.text_size + len(display_data) - len(line_text.encode("utf-8", "replace"))
+            if self.storage_size + len(display_data) > TRACE_STORAGE_LIMIT_BYTES:
+                self.mark_incomplete("Filtered storage quota exceeded. Earlier output remains available.")
+                return
+            try:
+                self._write_display(display_data)
+            except OSError:
+                self.mark_incomplete("Filtered output could not be saved. Check available disk space. Earlier output remains available.")
+                return
+            self.storage_size += len(display_data)
+            self._displayed(display_data, tone_span)
+            self.open_line = OpenLine(process_id, kind, line_start)
+        self.event_added.emit(TraceEvent(self.operation_id, process_id, CONSOLE_ONLY_KIND, line_text, self.event_count))
+
+    def _append(self, process_id: str, kind: str, text: str, console_line: ConsoleLine | None, *, hide_trace_line: bool = False, hide_opaque_body: bool = False,
+                console_text_filtered: bool = False, open_line_key: tuple[str, str] | None = None) -> None:
+        """Filter an entire record once before model, clipboard or optional log access, and show its console line if any.
+
+        The stored record and the logged text are the record itself, labelled with its process and kind; only the
+        console text differs. A console line equal to the record reuses its filtered text, so Git's output is filtered
+        once; a different line (a command, an end line) goes through the same filter, which knows every secret seen.
+        ``hide_trace_line`` leaves out of the console a record whose filtered text is a debug trace line, and
+        ``hide_opaque_body`` one that describes a binary output. ``console_text_filtered`` tells that the console line
+        already went through the filter piece by piece, as a command line does word by word, and must not be filtered
+        again as a whole.
+        """
+        if self.closed or self.capture_failed:
+            return
+        if len(text) > TRACE_UNIT_LIMIT_BYTES or len(text.encode("utf-8", "replace")) > TRACE_UNIT_LIMIT_BYTES:
+            self.mark_incomplete("An output record exceeded the text-unit limit.")
+            return
+        safe_text = self.filter.redact(text)
+        if '"result": "incomplete"' in safe_text or '"result":"incomplete"' in safe_text or "Trace incomplete:" in safe_text:
+            self.complete = False
+        event = TraceEvent(self.operation_id, process_id, kind, safe_text, self.event_count)
+        if hide_trace_line and is_trace_line(safe_text):
+            console_line = None
+        if hide_opaque_body and safe_text.startswith(OPAQUE_BODY_PREFIX):
+            console_line = None
+        data = json.dumps([event.operation_id, event.process_id, event.kind, event.text, event.sequence], ensure_ascii=True).encode("utf-8") + b"\n"
+        display_data = b""
+        tone_span = None
+        replaces_open_line = False
+        display_size = 0
+        if console_line is not None:
+            if console_text_filtered:
+                line_text = console_line.text
+            elif console_line.text == text:
+                line_text = safe_text
+            else:
+                line_text = self.filter.redact(console_line.text)
+            replaces_open_line = self.open_line is not None and (self.open_line.process_id, self.open_line.kind) == open_line_key
+            if replaces_open_line:
+                if line_text:
+                    display_size = self.open_line.line_start + len(line_text.encode("utf-8", "replace")) - self.text_size
+            else:
+                self._close_open_line()
+                display_data, tone_span = self._display(line_text, console_line.tone)
+                display_size = len(display_data)
+        size = len(data) + display_size + self.index_record.size
+        if self.storage_size + size > TRACE_STORAGE_LIMIT_BYTES:
+            self.mark_incomplete("Filtered storage quota exceeded. Earlier output remains available.")
+            return
+        # Flushing each record makes a full disk fail here, before the counters count the record as stored, and leaves
+        # nothing buffered for close() to write. It adds no system call: the seek before the next record would flush anyway.
+        try:
+            self.stream.seek(0, 2)
+            offset = self.stream.tell()
+            self.stream.write(data)
+            self.stream.flush()
+            if replaces_open_line:
+                if line_text and not self._rewrite_open_line(line_text, console_line.tone):
+                    return
+                self._close_open_line()
+            else:
+                self._write_display(display_data)
+            self.index_stream.seek(self.stored_count * self.index_record.size)
+            self.index_stream.write(self.index_record.pack(offset))
+            self.index_stream.flush()
+        except OSError:
+            self.mark_incomplete("Filtered output could not be saved. Check available disk space. Earlier output remains available.")
+            return
+        self.storage_size += size - display_size if replaces_open_line else size
+        self.stored_count += 1
+        self.event_count += 1
+        if console_line is not None and not replaces_open_line:
+            self._displayed(display_data, tone_span)
+        if self.log is not None:
+            self.log.write(PreparedDiagnostic("Operation", "", self.format_event(event), safe_text != text))
+        if console_line is not None:
+            self.event_added.emit(event)
+
+    def mark_incomplete(self, cause: str) -> None:
+        """Retain one bounded failure record even when no further disk writes are possible."""
+        if self.closed:
+            return
+        self._close_open_line()
+        self.complete = False
+        self.capture_failed = True
+        if self.failure_event is not None:
+            return
+        self.failure_event = TraceEvent(self.operation_id, self.operation_id, "incomplete", "Trace incomplete: " + self.filter.redact(cause), self.event_count)
+        prefix_data = self._display_prefix().encode("utf-8")
+        line_data = self.failure_event.text.encode("utf-8")
+        self.failure_text = prefix_data + line_data
+        line_start = self.text_size + len(prefix_data)
+        self.tone_spans.append(ToneSpan(line_start, line_start + len(line_data), ConsoleTone.FAILURE))
+        self.event_count += 1
+        if self.log is not None:
+            self.log.write(PreparedDiagnostic("Operation", "", self.format_event(self.failure_event), False))
+        self.event_added.emit(self.failure_event)
+
+    def read_page(self, start: int = 0, count: int = TRACE_PAGE_SIZE) -> list[TraceEvent]:
+        """Return a bounded page without lending mutable storage to the view."""
+        events: list[TraceEvent] = []
+        if self.closed:
+            return events
+        for index in range(max(0, start), min(self.event_count, max(0, start) + min(TRACE_PAGE_SIZE, max(0, count)))):
+            if index == self.stored_count and self.failure_event is not None:
+                events.append(self.failure_event)
+                continue
+            try:
+                self.index_stream.seek(index * self.index_record.size)
+                offset, = self.index_record.unpack(self.index_stream.read(self.index_record.size))
+                self.stream.seek(offset)
+                events.append(TraceEvent(*json.loads(self.stream.readline())))
+            except (OSError, ValueError, struct.error):
+                self.mark_incomplete("Some saved output records could not be read. Available text can still be copied.")
+                break
+        return events
+
+    def read_text_page(self, start: int = 0, count: int = TRACE_VIEW_LIMIT_BYTES) -> tuple[str, int, int]:
+        """Read one bounded UTF-8 page and return its exact byte boundaries for navigation."""
+        if self.closed:
+            return "", 0, 0
+        start = max(0, min(start, self.text_size + len(self.failure_text)))
+        limit = min(max(1, count), TRACE_VIEW_LIMIT_BYTES)
+        data = self._read_text(start, limit)
+        # Page requests can land inside UTF-8; advance only across the remaining continuation bytes.
+        first_byte_index = 0
+        while data and data[first_byte_index] & 0xC0 == 0x80:
+            start += 1
+            data = data[1:]
+        while data:
+            try:
+                return data.decode("utf-8"), start, start + len(data)
+            except UnicodeDecodeError as error:
+                if error.end == len(data):
+                    data = data[:error.start]
+                else:
+                    self.mark_incomplete("Saved output contained unreadable text.")
+                    return data.decode("utf-8", "replace"), start, start + len(data)
+        return "", start, start
+
+    def _read_text(self, start: int, count: int) -> bytes:
+        """Combine saved text with the single in-memory storage-failure record."""
+        data = b""
+        if start < self.text_size:
+            try:
+                self.text_stream.seek(start)
+                expected_count = min(count, self.text_size - start)
+                data = self.text_stream.read(expected_count)
+                if len(data) != expected_count:
+                    self.mark_incomplete("Saved output ended unexpectedly. The operation trace is incomplete.")
+                    return data + self.failure_text[:max(0, count - len(data))]
+            except OSError:
+                self.mark_incomplete("Saved text could not be read. The operation trace is incomplete.")
+                return self.failure_text[:count]
+        remaining = count - len(data)
+        failure_start = max(0, start - self.text_size)
+        return data + self.failure_text[failure_start:failure_start + remaining]
+
+    def copy_text(self) -> str:
+        """Return exactly the safe records available to the dialog."""
+        if self.closed:
+            return ""
+        return self._read_text(0, self.text_size + len(self.failure_text)).decode("utf-8", "replace")
+
+    @staticmethod
+    def format_event(event: TraceEvent) -> str:
+        """Label process and stream so concurrent commands remain distinguishable."""
+        return f"[{event.process_id} {event.kind}] {event.text}"
+
+    def close(self) -> None:
+        """Disconnect collection and discard any unpublished incomplete fragments."""
+        if self.closed:
+            return
+        for active in self.runner.active_by_id.values():
+            if active.request.operation_id == self.operation_id:
+                self.close_requested = True
+                return
+        for request in self.runner.pending_requests:
+            if request.operation_id == self.operation_id:
+                self.close_requested = True
+                return
+        self.closed = True
+        self.runner.started.disconnect(self._started)
+        self.runner.stdout_chunk.disconnect(self._stdout)
+        self.runner.stderr_chunk.disconnect(self._stderr)
+        self.runner.finished.disconnect(self._finished)
+        self.stream_by_key.clear()
+        self.config_buffer_by_id.clear()
+        self.network_stream_by_id.clear()
+        self.resource.close()
+
+    def _keeps(self, request: ProcessRequest) -> bool:
+        """Tell whether a process belongs to this operation and to what the trace shows of it."""
+        if request.operation_id != self.operation_id:
+            return False
+        return not (self.native_commands_only and request.profile == READ_PROFILE)
+
+    @staticmethod
+    def shows_output(request: ProcessRequest, kind: str) -> bool:
+        """Tell whether the console shows what a process writes on one of its streams; the records and the log keep it either way.
+
+        A read is a check GitPane runs for itself, and its standard output is in a machine format (fields separated by
+        NUL characters, raw listings) that tells the user nothing: the console shows only its ``$`` line, plus its error
+        output and its exit code when it fails. The ``--log`` file keeps that output for diagnosis. A program started for
+        the user (a write, a network command) keeps all its output on screen, as a terminal would show it.
+        """
+        return not (kind == "stdout" and request.profile == READ_PROFILE)
+
+    def _append_output(self, request: ProcessRequest, kind: str, text: str) -> None:
+        """Record one complete unit a process wrote, and show it only when ``shows_output`` says so."""
+        if self.shows_output(request, kind):
+            self.append_event(request.request_id, kind, text)
+            return
+        self.append_record(request.request_id, kind, text, None)
+
+    def _append_stream_unit(self, request: ProcessRequest, kind: str, unit: TextUnit) -> None:
+        """Store complete stream records while drawing only the unit's visible terminal value."""
+        shown_text = unit.shown_text
+        owns_open_line = self.open_line is not None and (self.open_line.process_id, self.open_line.kind) == (request.request_id, kind)
+        if unit.source == TextValueSource.PUBLISHED and not owns_open_line:
+            shown_text = None
+        if not self.shows_output(request, kind) or kind in PROCESS_OUTPUT_KIND_SET and unit.text.startswith(OPAQUE_BODY_PREFIX):
+            shown_text = None
+        if unit.end in (TextUnitEnd.REDRAW, TextUnitEnd.HIDDEN_TAIL):
+            if unit.end == TextUnitEnd.HIDDEN_TAIL:
+                self.append_record(request.request_id, kind, unit.text, None)
+            if shown_text:
+                self._draw_open_line(request.request_id, kind, shown_text)
+            return
+        console_line = self._output_console_line(kind, shown_text) if shown_text is not None else None
+        self._append(request.request_id, kind, unit.text, console_line, open_line_key=(request.request_id, kind))
+
+    def _started(self, request: ProcessRequest) -> None:
+        """Record the command of a process of this operation as soon as it starts.
+
+        The logged record is written while the process runs, so it cannot carry an exit code yet and says "running";
+        the result record that follows the process carries its status and exit code. The console shows the command as
+        one would type it, after a ``$ `` prompt, followed by its folder when it runs elsewhere than the header says.
+        """
+        if self._keeps(request):
+            self.started_request_id_set.add(request.request_id)
+            prepared = Diagnostic(request.operation, request.working_dir, request.program_filename, request.arguments, "", process_started=True).prepare()
+            console_line = ConsoleLine(command_line(request, self.header, redact=self.filter.redact))
+            self._append(request.request_id, "command", prepared.detail, console_line, console_text_filtered=True)
+
+    def _stdout(self, request: ProcessRequest, data: bytes) -> None:
+        self._receive(request, "stdout", data)
+
+    def _stderr(self, request: ProcessRequest, data: bytes) -> None:
+        self._receive(request, "stderr", data)
+
+    def _receive(self, request: ProcessRequest, kind: str, data: bytes) -> None:
+        """Retain incomplete lines so a chunk boundary cannot split a secret."""
+        if self.closed or self.capture_failed or not self._keeps(request):
+            return
+        if kind == "stdout" and (request.profile == CREDENTIAL_PROFILE or ("cat-file" in request.arguments and "--batch" in request.arguments)):
+            # Object bodies are repository contents, not diagnostics; keep command and result only.
+            return
+        if kind == "stdout" and "config" in request.arguments and "--null" in request.arguments:
+            buffer = self.config_buffer_by_id.setdefault(request.request_id, bytearray())
+            if len(buffer) + len(data) > TRACE_UNIT_LIMIT_BYTES:
+                self.mark_incomplete("A configuration response exceeded the text-unit limit.")
+                return
+            buffer.extend(data)
+            return
+        if kind == "stdout" and any("%(" in argument and "%00" in argument for argument in request.arguments):
+            data = data.replace(b"\0", b"\\0")
+        if kind == "stderr" and request.profile == NETWORK_PROFILE:
+            self._receive_network(request, data)
+            return
+        self._feed(request, kind, data)
+
+    def _feed(self, request: ProcessRequest, kind: str, data: bytes) -> None:
+        """Keep incomplete ordinary text units private until the shared filter can process them."""
+        key = (request.request_id, kind)
+        stream = self.stream_by_key.setdefault(key, SensitiveTextStream(self.filter, hides_value=is_trace_line if kind == "stderr" else None))
+        for unit in stream.feed_units(data):
+            self._append_stream_unit(request, kind, unit)
+        self.complete = self.complete and stream.complete
+
+    def _receive_network(self, request: ProcessRequest, data: bytes, final: bool = False) -> None:
+        """Reassemble curl body display lines so secrets split at trace widths stay private."""
+        process_id = request.request_id
+        stream = self.network_stream_by_id.setdefault(process_id, NetworkTextStream(self.filter, hides_value=is_trace_line))
+        for kind, unit in stream.feed_units(data, final):
+            self._append_stream_unit(request, kind, unit)
+        self.complete = self.complete and stream.complete
+        if final:
+            self.network_stream_by_id.pop(process_id, None)
+
+    def _finished(self, result: ProcessResult) -> None:
+        """Flush terminal fragments before publishing the process's actual result.
+
+        The log keeps the result record of every process; the console adds a line only when the process did not succeed,
+        and remembers that process and its error output so a later diagnostic does not show them again.
+        """
+        if self.closed or result.request.operation_id != self.operation_id:
+            return
+        if not self._keeps(result.request):
+            # A hidden read can be the operation's last process, and a close waits for that one to end.
+            if self.close_requested:
+                self.close()
+            return
+        if result.request.profile == NETWORK_PROFILE:
+            self._receive_network(result.request, b"", final=True)
+        buffer = self.config_buffer_by_id.pop(result.request.request_id, None)
+        if buffer is not None:
+            from gitpane.transport.remote_config import config_records
+            try:
+                content = bytes(buffer)
+                if any(argument in result.request.arguments for argument in ("--name-only", "--get-regexp", "--list")) and "--show-origin" not in result.request.arguments and "--show-scope" not in result.request.arguments:
+                    if content and not content.endswith(b"\0"):
+                        raise ValueError("Incomplete configuration record")
+                    records = []
+                    for setting in content.split(b"\0"):
+                        if setting:
+                            records.append(b"unknown\0unknown\0" + setting + b"\0")
+                    content = b"".join(records)
+                if content and "--show-origin" in result.request.arguments and "--show-scope" not in result.request.arguments:
+                    if not content.endswith(b"\0"):
+                        raise ValueError("Incomplete configuration record")
+                    fields = content.removesuffix(b"\0").split(b"\0")
+                    field_count = 2
+                    if len(fields) % field_count:
+                        raise ValueError("Incomplete configuration record")
+                    records = []
+                    iterator = iter(fields)
+                    for origin, setting in zip(iterator, iterator, strict=True):
+                        records.append(b"unknown\0" + origin + b"\0" + setting + b"\0")
+                    content = b"".join(records)
+                # The scope stays the word Git printed: a listing read without --show-scope is given "unknown" above.
+                for record in config_records(content):
+                    self._append_output(result.request, "stdout", f"{record.scope_text} {record.origin} {record.key}={record.value!r}")
+            except ValueError:
+                self.mark_incomplete("A configuration response ended before its complete record could be filtered.")
+        for kind in ("stdout", "stderr"):
+            stream = self.stream_by_key.pop((result.request.request_id, kind), None)
+            if stream is not None:
+                for unit in stream.feed_units(b"", final=True):
+                    self._append_stream_unit(result.request, kind, unit)
+                self.complete = self.complete and stream.complete
+        command_shown = result.request.request_id in self.started_request_id_set
+        self.started_request_id_set.discard(result.request.request_id)
+        end_line = process_end_line(result, command_shown=command_shown)
+        self.append_record(result.request.request_id, "result", f"{result.status.value}; exit={result.return_code}; {cause_without_trace_lines(result.cause)}", end_line)
+        if end_line is not None:
+            self.ended_process_id_set.add(result.request.request_id)
+            self.failed_outputs.append(result.stderr.decode("utf-8", "replace"))
+        if self.close_requested:
+            self.close()