chore: add comments explaining non-obvious design decisions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: smflorentino

src/uipath/runtime/logging/_interceptor.py

@@ -209,7 +209,14 @@ def _redirect_stdout_stderr(self) -> None:
         )
 
     def teardown(self) -> None:
-        """Restore original logging configuration."""
+        """Restore original logging configuration.
+
+        IMPORTANT: The ordering below is critical. Flushing must happen before
+        clearing the context variable and before removing handlers. Otherwise:
+        - If context is cleared first, the execution filter won't match the
+          flushed records and they'll be dropped.
+        - If handlers are removed first, the flushed records have no destination.
+        """
         # Step 1: Flush LoggerWriter buffers while context and handlers are still active.
         # Child mode: flush only this context's buffer from the shared LoggerWriter.
         # Master mode: flush ALL remaining buffers before restoring streams.
@@ -266,7 +273,9 @@ def teardown(self) -> None:
         if self._owns_handler:
             self.log_handler.close()
 
-        # Step 5: Only master restores streams (children never replaced them)
+        # Step 5: Only master restores streams. Children never replaced
+        # sys.stdout/sys.stderr (they only registered handlers on the loggers),
+        # so there is nothing for them to restore here.
         if not self.execution_id and self.original_stdout and self.original_stderr:
             sys.stdout = self.original_stdout
             sys.stderr = self.original_stderr

src/uipath/runtime/logging/_writers.py

@@ -24,6 +24,9 @@ def __init__(
         self.logger = logger
         self.level = level
         self.min_level = min_level
+        # Keyed by current_execution_id (None for master context).
+        # A single shared buffer would interleave partial lines from
+        # concurrent async tasks writing to the same sys.stdout.
         self._buffers: dict[str | None, str] = {}
         self.sys_file = sys_file
         self._in_logging = False  # Recursion guard
@@ -75,7 +78,11 @@ def flush(self) -> None:
             self._in_logging = False
 
     def flush_all(self) -> None:
-        """Flush all execution contexts' buffered messages. Called by master teardown."""
+        """Flush all execution contexts' buffered messages. Called by master teardown.
+
+        Intentionally ignores current_execution_id — iterates all keys
+        directly so that no context's partial lines are lost.
+        """
         if self._in_logging:
             return