@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/gateway/stream_consumer.py

@@ -143,12 +143,26 @@ class GatewayStreamConsumer:
         # timestamps would be stale by completion time.  Ported from
         # openclaw/openclaw#72038.
         self._message_created_ts: Optional[float] = None
+        # Every real preview message id the consumer has put on screen during
+        # this response (first send + any continuation messages from oversized
+        # edits/sends).  The fresh-final path deletes all of them when it
+        # re-delivers the completed answer as a single (rich) message, so a
+        # reply that was split across the platform's edit limit while streaming
+        # doesn't leave stale fragments above the final message.
+        self._preview_message_ids: "set[str]" = set()
         self._already_sent = False
         self._edit_supported = True  # Disabled when progressive edits are no longer usable
         self._last_edit_time = 0.0
         self._last_sent_text = ""   # Track last-sent text to skip redundant edits
+        # True when the most recent _send_or_edit split-and-delivered across
+        # continuation messages (the adapter adopted a new message id).
+        self._last_edit_overflowed = False
         self._fallback_final_send = False
         self._fallback_prefix = ""
+        # True when fallback is sending only the missing tail after a partial
+        # Telegram overflow delivery.  In that case the already-visible prefix
+        # is intentional content, not a stale preview to delete.
+        self._fallback_preserve_partial_messages = False
         self._flood_strikes = 0         # Consecutive flood-control edit failures
         self._current_edit_interval = self.cfg.edit_interval  # Adaptive backoff
         self._final_response_sent = False
@@ -183,6 +197,30 @@ class GatewayStreamConsumer:
         # this response and route through edit-based for graceful degradation.
         self._draft_failures = 0
 
+    def _metadata_for_send(
+        self,
+        *,
+        final: bool = False,
+        expect_edits: bool = False,
+    ) -> dict | None:
+        """Return per-send metadata for stream-created messages.
+
+        Mattermost treats notify-worthy sends as user-visible final content
+        when deciding whether a broken thread root may fall back flat.  Preview
+        and progress sends keep their original metadata and remain thread-strict.
+
+        ``expect_edits`` preserves the upstream Telegram streaming contract:
+        preview messages that may be edited later must stay on the editable
+        legacy send path, while fresh/fallback final sends can still use richer
+        final-message delivery.
+        """
+        meta = dict(self.metadata) if self.metadata else {}
+        if expect_edits:
+            meta["expect_edits"] = True
+        if final:
+            meta["notify"] = True
+        return meta or None
+
     @property
     def already_sent(self) -> bool:
         """True if at least one message was sent or edited during the run."""
@@ -261,6 +299,7 @@ class GatewayStreamConsumer:
         self._last_sent_text = ""
         self._fallback_final_send = False
         self._fallback_prefix = ""
+        self._fallback_preserve_partial_messages = False
         # #29346: a tool/segment boundary means what we delivered was an interim
         # preamble, not the final answer — clear the flags so a premature setter
         # can't fool the gateway. Safe: got_done returns before any reset, and
@@ -412,7 +451,10 @@ class GatewayStreamConsumer:
             if isinstance(self.adapter, _BasePlatformAdapter)
             else len
         )
-        _raw_limit = getattr(self.adapter, "MAX_MESSAGE_LENGTH", 4096)
+        # Rich-capable adapters (Telegram rich messages) raise this above the
+        # legacy per-message limit so a reply that fits one rich send/draft
+        # isn't fragmented at 4096 while streaming.  See _raw_message_limit.
+        _raw_limit = self._raw_message_limit()
         _safe_limit = max(500, _raw_limit - _len_fn(self.cfg.cursor) - 100)
 
         # Resolve native draft streaming once per run.  When enabled the
@@ -495,7 +537,11 @@ class GatewayStreamConsumer:
                         chunks_delivered = False
                         reply_to = self._message_id or self._initial_reply_to_id
                         for chunk in chunks:
-                            new_id = await self._send_new_chunk(chunk, reply_to)
+                            new_id = await self._send_new_chunk(
+                                chunk,
+                                reply_to,
+                                final=got_done,
+                            )
                             if new_id is not None and new_id != reply_to:
                                 chunks_delivered = True
                         self._accumulated = ""
@@ -530,7 +576,19 @@ class GatewayStreamConsumer:
                         if split_at < _safe_limit // 2:
                             split_at = _safe_limit
                         chunk = self._accumulated[:split_at]
-                        ok = await self._send_or_edit(chunk)
+                        # finalize=True so the adapter applies platform-specific
+                        # rich-text markup (e.g. Telegram MarkdownV2). This
+                        # sealed chunk will never be edited again — _message_id
+                        # is reset to None right below — so it must receive its
+                        # final formatting pass now, or early split messages
+                        # render raw markdown while only the last chunk renders.
+                        # is_turn_final=False: this is the first of several split
+                        # messages, NOT the turn-final answer, so the fresh-final
+                        # path (opt-in fresh_final_after_seconds) must not mark
+                        # the turn delivered on it (#29346 semantics).
+                        ok = await self._send_or_edit(
+                            chunk, finalize=True, is_turn_final=False,
+                        )
                         if self._fallback_final_send or not ok:
                             # Edit failed (or backed off due to flood control)
                             # while attempting to split an oversized message.
@@ -569,14 +627,31 @@ class GatewayStreamConsumer:
                     if self._accumulated:
                         if self._fallback_final_send:
                             await self._send_fallback_final(self._accumulated)
+                        elif self._final_response_sent:
+                            # A finalize=True tick above already delivered the
+                            # final answer via the adapter's fresh-final path
+                            # (_try_fresh_final sent a fresh rich message and
+                            # deleted the preview).  Running a second finalize
+                            # edit here would duplicate the message / re-delete,
+                            # so just record delivery and stop.
+                            self._final_content_delivered = True
                         elif (
                             current_update_visible
-                            and not self._adapter_requires_finalize
+                            and (
+                                not self._adapter_requires_finalize
+                                or self._last_edit_overflowed
+                            )
                         ):
                             # Mid-stream edit above already delivered the
                             # final accumulated content.  Skip the redundant
-                            # final edit — but only for adapters that don't
-                            # need an explicit finalize signal.
+                            # final edit for adapters that don't need an
+                            # explicit finalize signal, and for any adapter
+                            # when that edit split-and-delivered across
+                            # continuations: the split edit carried
+                            # finalize=True itself, and re-finalizing with
+                            # the full text would overflow-split again into
+                            # the adopted continuation, duplicating chunks
+                            # on screen.
                             self._final_response_sent = True
                             self._final_content_delivered = True
                         elif self._message_id:
@@ -588,6 +663,15 @@ class GatewayStreamConsumer:
                             )
                             if self._final_response_sent:
                                 self._final_content_delivered = True
+                            elif self._fallback_final_send:
+                                # The final edit attempt itself may be the one
+                                # that exhausts flood-control strikes and
+                                # promotes the consumer into fallback mode.  Do
+                                # not return to the gateway with a full-response
+                                # fallback still pending; send only the unsent
+                                # tail here so the normal gateway send path does
+                                # not duplicate the visible prefix.
+                                await self._send_fallback_final(self._accumulated)
                         elif not self._already_sent:
                             self._final_response_sent = await self._send_or_edit(self._accumulated)
                             if self._final_response_sent:
@@ -635,11 +719,21 @@ class GatewayStreamConsumer:
                 await asyncio.sleep(0.05)  # Small yield to not busy-loop
 
         except asyncio.CancelledError:
-            # Best-effort final edit on cancellation
+            # Best-effort final edit on cancellation.  finalize=True so
+            # REQUIRES_EDIT_FINALIZE platforms (Telegram) apply final
+            # formatting — a plain edit here would leave the entire reply
+            # rendered as a raw streaming preview while the success flags
+            # below suppress the gateway's formatted re-send.
+            # is_turn_final=False keeps _try_fresh_final from setting
+            # _final_response_sent itself; this handler owns the flags.
             _best_effort_ok = False
             if self._accumulated and self._message_id:
                 try:
-                    _best_effort_ok = bool(await self._send_or_edit(self._accumulated))
+                    _best_effort_ok = bool(
+                        await self._send_or_edit(
+                            self._accumulated, finalize=True, is_turn_final=False,
+                        )
+                    )
                 except Exception:
                     pass
             # Only confirm final delivery if the best-effort send above
@@ -683,7 +777,13 @@ class GatewayStreamConsumer:
         # Strip trailing whitespace/newlines but preserve leading content
         return cleaned.rstrip()
 
-    async def _send_new_chunk(self, text: str, reply_to_id: Optional[str]) -> Optional[str]:
+    async def _send_new_chunk(
+        self,
+        text: str,
+        reply_to_id: Optional[str],
+        *,
+        final: bool = False,
+    ) -> Optional[str]:
         """Send a new message chunk, optionally threaded to a previous message.
 
         Returns the message_id so callers can thread subsequent chunks.
@@ -692,15 +792,15 @@ class GatewayStreamConsumer:
         if not text.strip():
             return reply_to_id
         try:
-            meta = dict(self.metadata) if self.metadata else {}
             result = await self.adapter.send(
                 chat_id=self.chat_id,
                 content=text,
                 reply_to=reply_to_id,
-                metadata=meta,
+                metadata=self._metadata_for_send(final=final, expect_edits=True),
             )
             if result.success and result.message_id:
                 self._message_id = str(result.message_id)
+                self._track_preview_ids_from_result(result)
                 self._already_sent = True
                 self._last_sent_text = text
                 # Fresh content bubble — close off any stale tool bubble
@@ -815,7 +915,7 @@ class GatewayStreamConsumer:
                 result = await self.adapter.send(
                     chat_id=self.chat_id,
                     content=chunk,
-                    metadata=self.metadata,
+                    metadata=self._metadata_for_send(final=True),
                 )
                 if result.success:
                     break
@@ -855,11 +955,21 @@ class GatewayStreamConsumer:
             self._notify_new_message()
 
         # Remove the frozen partial message so the user only sees the
-        # complete fallback response.  Best-effort — if the platform doesn't
+        # complete fallback response.  ONLY safe when the fallback re-sent
+        # the FULL final text (continuation == final_text).  When the
+        # prefix-based dedup above sent only the missing TAIL, the partial
+        # message IS the head of the answer — deleting it leaves the user
+        # with only the last part of the response (the "Gemini sent only
+        # the second half" symptom).  Best-effort — if the platform doesn't
         # implement ``delete_message``, the delete fails (flood control still
         # active, bot lacks permission, message too old to delete), the
         # partial remains but at least the full answer was delivered.
-        if stale_message_id and stale_message_id != last_message_id:
+        if (
+            stale_message_id
+            and stale_message_id != last_message_id
+            and not self._fallback_preserve_partial_messages
+            and continuation == final_text
+        ):
             delete_fn = getattr(self.adapter, "delete_message", None)
             if delete_fn is not None:
                 try:
@@ -876,6 +986,7 @@ class GatewayStreamConsumer:
         self._final_content_delivered = True
         self._last_sent_text = chunks[-1]
         self._fallback_prefix = ""
+        self._fallback_preserve_partial_messages = False
 
     def _is_flood_error(self, result) -> bool:
         """Check if a SendResult failure is due to flood control / rate limiting."""
@@ -1067,6 +1178,76 @@ class GatewayStreamConsumer:
         age = time.monotonic() - self._message_created_ts
         return age >= threshold
 
+    def _raw_message_limit(self) -> int:
+        """Per-message length budget (in the adapter's ``message_len_fn`` units)
+        before the consumer splits an overflowing reply.
+
+        Adapters with a richer send/draft path (e.g. Telegram rich messages)
+        can raise this above ``MAX_MESSAGE_LENGTH`` via
+        ``streaming_overflow_limit`` so a reply that fits one rich message isn't
+        fragmented at the legacy edit limit.  Falls back to
+        ``MAX_MESSAGE_LENGTH`` (4096 default) for everyone else.
+        """
+        base = getattr(self.adapter, "MAX_MESSAGE_LENGTH", 4096)
+        # isinstance gate: MagicMock adapters return mock objects (truthy, not
+        # ints) for arbitrary attribute access — keep them on the base limit.
+        if isinstance(self.adapter, _BasePlatformAdapter):
+            try:
+                cap = self.adapter.streaming_overflow_limit()
+            except Exception as e:
+                logger.debug("streaming_overflow_limit check failed: %s", e)
+                cap = None
+            if isinstance(cap, int) and cap > base:
+                return cap
+        return base
+
+    def _track_preview_id(self, message_id: Optional[str]) -> None:
+        """Record a real preview message id for fresh-final cleanup."""
+        if message_id and message_id != "__no_edit__":
+            self._preview_message_ids.add(str(message_id))
+
+    def _track_preview_ids_from_result(self, result: Any) -> None:
+        """Record every message id a send/edit result exposes: the primary id
+        plus any continuation ids from an oversized split
+        (``continuation_message_ids`` or ``raw_response['message_ids']``)."""
+        self._track_preview_id(getattr(result, "message_id", None))
+        for mid in (getattr(result, "continuation_message_ids", None) or ()):
+            self._track_preview_id(mid)
+        raw = getattr(result, "raw_response", None) or {}
+        if isinstance(raw, dict):
+            for mid in (raw.get("message_ids") or ()):
+                self._track_preview_id(mid)
+
+    def _adapter_prefers_fresh_final(self, text: str) -> bool:
+        """Return True when the adapter would rather finalize a streamed reply
+        by sending a fresh message and deleting the preview than by editing the
+        preview in place — e.g. Telegram, whose ``sendRichMessage`` send path
+        currently renders richer markdown than Hermes' MarkdownV2 edit path.
+
+        Returns False when there is no real preview to replace (no message id,
+        or the ``__no_edit__`` sentinel), when the adapter doesn't expose the
+        hook, or on any error (the consumer then keeps the edit-in-place path).
+        """
+        if not self._message_id or self._message_id == "__no_edit__":
+            return False
+        fn = getattr(self.adapter, "prefers_fresh_final_streaming", None)
+        if fn is None:
+            return False
+        try:
+            try:
+                result = fn(text, metadata=self.metadata)
+            except TypeError:
+                # Adapter / test double whose hook doesn't accept the metadata
+                # keyword — fall back to the positional-only form.
+                result = fn(text)
+        except Exception as e:
+            logger.debug("prefers_fresh_final_streaming check failed: %s", e)
+            return False
+        # ``is True`` (not ``bool(...)``) so a MagicMock adapter's auto-child
+        # method — truthy by default in tests — does not wrongly enable the
+        # fresh-final path.  Mirrors the REQUIRES_EDIT_FINALIZE gate in __init__.
+        return result is True
+
     async def _try_fresh_final(self, text: str, *, is_turn_final: bool = True) -> bool:
         """Send ``text`` as a brand-new message (best-effort delete the old
         preview) so the platform's visible timestamp reflects completion
@@ -1080,37 +1261,47 @@ class GatewayStreamConsumer:
 
         Ported from openclaw/openclaw#72038.
         """
-        old_message_id = self._message_id
+        # Every preview message the user has seen for this response: the
+        # current one plus any continuation fragments tracked while streaming
+        # (an oversized reply split across the platform's edit limit).  All of
+        # them are replaced by the single fresh message below.
+        stale_ids = set(self._preview_message_ids)
+        if self._message_id and self._message_id != "__no_edit__":
+            stale_ids.add(self._message_id)
         try:
             result = await self.adapter.send(
                 chat_id=self.chat_id,
                 content=text,
-                metadata=self.metadata,
+                metadata=self._metadata_for_send(final=True),
             )
         except Exception as e:
             logger.debug("Fresh-final send failed, falling back to edit: %s", e)
             return False
         if not getattr(result, "success", False):
             return False
-        # Successful fresh send — try to delete the stale preview so the
-        # user doesn't see the old edit-stuck message underneath.  Cleanup
+        # Adopt the new message id as the current message so subsequent
+        # callers (e.g. overflow split loops, finalize retries) see a
+        # consistent state.
+        new_message_id = getattr(result, "message_id", None)
+        # Successful fresh send — try to delete the stale preview(s) so the
+        # user doesn't see the old edit-stuck message(s) underneath.  Cleanup
         # is best-effort; platforms that don't implement ``delete_message``
-        # just leave the preview behind (still an acceptable outcome —
-        # the visible final timestamp is the important part).
-        if old_message_id and old_message_id != "__no_edit__":
-            delete_fn = getattr(self.adapter, "delete_message", None)
-            if delete_fn is not None:
+        # just leave the preview behind (still an acceptable outcome — the
+        # visible final timestamp is the important part).  Never delete the
+        # message we just sent.
+        delete_fn = getattr(self.adapter, "delete_message", None)
+        if delete_fn is not None:
+            for stale_id in stale_ids:
+                if not stale_id or stale_id == "__no_edit__" or stale_id == new_message_id:
+                    continue
                 try:
-                    await delete_fn(self.chat_id, old_message_id)
+                    await delete_fn(self.chat_id, stale_id)
                 except Exception as e:
                     logger.debug(
                         "Fresh-final preview cleanup failed (%s): %s",
-                        old_message_id, e,
+                        stale_id, e,
                     )
-        # Adopt the new message id as the current message so subsequent
-        # callers (e.g. overflow split loops, finalize retries) see a
-        # consistent state.
-        new_message_id = getattr(result, "message_id", None)
+        self._preview_message_ids = set()
         if new_message_id:
             self._message_id = new_message_id
             self._message_created_ts = time.monotonic()
@@ -1196,6 +1387,7 @@ class GatewayStreamConsumer:
                 return True
             # Failure already disabled drafts for this run; fall through to
             # the regular edit/send path below.
+        self._last_edit_overflowed = False
         try:
             if self._message_id is not None:
                 if self._edit_supported:
@@ -1219,9 +1411,19 @@ class GatewayStreamConsumer:
                     # old preview follows.  Ported from
                     # openclaw/openclaw#72038.  Gated by config so the
                     # legacy edit-in-place path stays the default.
+                    #
+                    # Adapters can also opt in regardless of the time threshold
+                    # via prefers_fresh_final_streaming (e.g. Telegram, whose
+                    # send path renders richer markdown than its edit path):
+                    # finalizing through edit would visibly downgrade a rich
+                    # preview, so re-deliver as a fresh message + delete the
+                    # preview instead.
                     if (
                         finalize
-                        and self._should_send_fresh_final()
+                        and (
+                            self._should_send_fresh_final()
+                            or self._adapter_prefers_fresh_final(text)
+                        )
                         and await self._try_fresh_final(
                             text, is_turn_final=is_turn_final,
                         )
@@ -1235,6 +1437,9 @@ class GatewayStreamConsumer:
                     )
                     if result.success:
                         self._already_sent = True
+                        # Record any continuation fragments an oversized edit
+                        # split off, so fresh-final can clean them all up.
+                        self._track_preview_ids_from_result(result)
                         # Adapter may have split-and-delivered an oversized
                         # edit across the original message + N continuations.
                         # When that happens, ``message_id`` is the LAST visible
@@ -1252,6 +1457,7 @@ class GatewayStreamConsumer:
                             and result.message_id
                             and result.message_id != self._message_id
                         ):
+                            self._last_edit_overflowed = True
                             self._message_id = str(result.message_id)
                             self._message_created_ts = time.monotonic()
                             self._last_sent_text = ""
@@ -1262,6 +1468,51 @@ class GatewayStreamConsumer:
                         self._flood_strikes = 0
                         return True
                     else:
+                        if (
+                            finalize
+                            and is_turn_final
+                            and self.cfg.cursor
+                            and self._last_sent_text.endswith(self.cfg.cursor)
+                            and self._visible_prefix() == text
+                        ):
+                            # The final clean-up edit failed, but the complete
+                            # answer is already visible from the last streaming
+                            # frame (usually with only the cursor still stuck on
+                            # screen).  Mark the content delivered so the
+                            # gateway suppresses its normal full final send;
+                            # otherwise users see the same long answer twice
+                            # when Telegram/Discord rate-limit this cosmetic
+                            # final edit (#36965, #25349).
+                            self._final_content_delivered = True
+                        raw_response = getattr(result, "raw_response", None)
+                        if isinstance(raw_response, dict) and raw_response.get("partial_overflow"):
+                            # Telegram edited/sent one or more overflow chunks,
+                            # but not the complete response.  Preserve the
+                            # visible prefix so the got_done fallback sends the
+                            # missing tail instead of marking a clipped topic
+                            # reply as final delivery.
+                            self._message_id = str(
+                                raw_response.get("last_message_id")
+                                or result.message_id
+                                or self._message_id
+                            )
+                            delivered_prefix = raw_response.get("delivered_prefix")
+                            if isinstance(delivered_prefix, str) and delivered_prefix:
+                                self._last_sent_text = delivered_prefix
+                                self._fallback_prefix = delivered_prefix
+                                self._fallback_preserve_partial_messages = text.startswith(
+                                    delivered_prefix
+                                )
+                            else:
+                                self._fallback_prefix = self._visible_prefix()
+                                self._fallback_preserve_partial_messages = False
+                            self._fallback_final_send = True
+                            self._edit_supported = False
+                            self._already_sent = True
+                            if getattr(result, "continuation_message_ids", ()):
+                                self._notify_new_message()
+                            return False
+
                         # Edit failed.  If this looks like flood control / rate
                         # limiting, use adaptive backoff: double the edit interval
                         # and retry on the next cycle.  Only permanently disable
@@ -1311,7 +1562,10 @@ class GatewayStreamConsumer:
                     chat_id=self.chat_id,
                     content=text,
                     reply_to=self._initial_reply_to_id,
-                    metadata=self.metadata,
+                    metadata=self._metadata_for_send(
+                        final=finalize,
+                        expect_edits=True,
+                    ),
                 )
                 if result.success:
                     if result.message_id:
@@ -1320,6 +1574,9 @@ class GatewayStreamConsumer:
                         # the user so fresh-final logic can detect stale
                         # preview timestamps on long-running responses.
                         self._message_created_ts = time.monotonic()
+                        # Record this (and any continuation fragments from an
+                        # oversized first send) for fresh-final cleanup.
+                        self._track_preview_ids_from_result(result)
                     else:
                         self._edit_supported = False
                     self._already_sent = True

package/agent/hermes-already-has-routines.md

@@ -149,7 +149,7 @@ hermes webhook subscribe pr-review \
   --deliver github_comment
 ```
 
-Full automation templates gallery: [hermes-agent.nousresearch.com/docs/guides/automation-templates](https://hermes-agent.nousresearch.com/docs/guides/automation-templates)
+Full automation blueprints gallery: [hermes-agent.nousresearch.com/docs/reference/automation-blueprints-catalog](https://hermes-agent.nousresearch.com/docs/reference/automation-blueprints-catalog)
 
 Documentation: [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com)
 

package/agent/hermes_cli/__init__.py

@@ -14,34 +14,79 @@ Provides subcommands for:
 import os
 import sys
 
-__version__ = "0.15.1"
-__release_date__ = "2026.5.29"
+__version__ = "0.17.0"
+__release_date__ = "2026.6.19"
 
 
 def _ensure_utf8():
-    """Force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError.
+    """Force UTF-8 stdout/stderr to prevent UnicodeEncodeError crashes.
 
-    Windows services and terminals default to cp1252, which cannot encode
-    box-drawing characters used in CLI output. This causes unhandled
-    UnicodeEncodeError crashes on gateway startup.
+    Several environments select a legacy, non-UTF-8 encoding for the standard
+    streams:
+
+    - Windows services and terminals default to cp1252.
+    - Linux hosts with a latin-1 / C / POSIX locale (common on minimal Debian
+      installs and Raspberry Pi) select latin-1 or ASCII.
+
+    The CLI prints box-drawing characters (┌│├└─) and the ⚕ glyph in the setup
+    wizard, doctor, and status banners. Encoding those under a non-UTF-8 codec
+    raises an unhandled UnicodeEncodeError that crashes the command before it
+    can even start — e.g. `hermes setup` on a fresh Pi.
+
+    This runs at import time so it protects every CLI subcommand, on any
+    platform. It re-wraps stdout/stderr as UTF-8 when their encoding is not
+    already UTF-8, preferring TextIOWrapper.reconfigure() so the existing
+    stream object is fixed in place (cached `sys.stdout` references keep
+    working) and falling back to reopening the file descriptor with
+    closefd=False (the CPython-recommended safe variant).
+
+    No-op when the streams are already UTF-8: a healthy UTF-8 system sees no
+    stream change and no environment mutation.
+
+    Note: this is intentionally the earliest, platform-agnostic guard.
+    hermes_cli/stdio.py::configure_windows_stdio() runs later from the entry
+    points and layers on the Windows-only extras (console code-page flip,
+    EDITOR default, PATH augmentation); its stream reconfiguration is a
+    harmless idempotent no-op once we have already repaired the streams here.
     """
-    if sys.platform != "win32":
-        return
-    os.environ.setdefault("PYTHONUTF8", "1")
-    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    repaired = False
+
     for stream_name in ("stdout", "stderr"):
         stream = getattr(sys, stream_name, None)
         if stream is None:
             continue
         try:
-            if getattr(stream, "encoding", "").lower().replace("-", "") != "utf8":
-                new_stream = open(
-                    stream.fileno(), "w", encoding="utf-8",
-                    buffering=1, closefd=False,
-                )
-                setattr(sys, stream_name, new_stream)
-        except (AttributeError, OSError):
+            encoding = (getattr(stream, "encoding", "") or "").lower().replace("-", "")
+            if encoding == "utf8":
+                continue
+
+            # Preferred: reconfigure the existing TextIOWrapper in place. This
+            # preserves object identity so any code already holding a reference
+            # to the old sys.stdout benefits from the repair too.
+            reconfigure = getattr(stream, "reconfigure", None)
+            if callable(reconfigure):
+                reconfigure(encoding="utf-8", errors="replace")
+                repaired = True
+                continue
+
+            # Fallback: reopen the underlying file descriptor as UTF-8. Used
+            # for streams that don't expose reconfigure() (e.g. some wrapped
+            # or replaced streams). closefd=False keeps the original fd open.
+            new_stream = open(
+                stream.fileno(), "w", encoding="utf-8",
+                errors="replace", buffering=1, closefd=False,
+            )
+            setattr(sys, stream_name, new_stream)
+            repaired = True
+        except (AttributeError, OSError, ValueError):
             pass
 
+    # Only nudge child processes toward UTF-8 when we actually detected a
+    # non-UTF-8 locale. On a healthy UTF-8 host children inherit UTF-8 from the
+    # locale already, so leave the environment untouched (minimal footprint).
+    if repaired:
+        os.environ.setdefault("PYTHONUTF8", "1")
+        os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+
 
 _ensure_utf8()