From 59edaa8891c80065407cdb9e892a8fd326cfd37e Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Thu, 13 Aug 2026 13:48:44 -0700
Subject: [PATCH] docs(terminal): record the hidden-delivery gate removal
 condition
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ties deletion to the existing hiddenDeliveryDroppedChars counter rather than a
new metric: with the default off, non-zero can only mean a profile re-enabled
the switch. Also notes the two things a future deletion must not get wrong —
unpicking the query-authority coupling, and NOT removing the general restore
pipeline, since backlog overflow and the pending cap lose bytes independently.
---
 src/main/ipc/pty-hidden-delivery-gate.ts | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/main/ipc/pty-hidden-delivery-gate.ts b/src/main/ipc/pty-hidden-delivery-gate.ts
index 6b464e7709f..433670c7caf 100644
--- a/src/main/ipc/pty-hidden-delivery-gate.ts
+++ b/src/main/ipc/pty-hidden-delivery-gate.ts
@@ -8,6 +8,23 @@
  * the existing seq-guarded machinery. Any renderer party that still needs raw
  * bytes (dispatcher sidecars) registers delivery
  * interest, which suppresses the gate for that PTY.
+ *
+ * DEFAULTED OFF (STA-4042). Dropping renderer-bound bytes makes the renderer's
+ * xterm a second emulator fed a different stream than the model, and a gap
+ * strands whatever state it interrupted — a swallowed `ESC[22m` leaves bold on
+ * every later cell. The setting survives only as an emergency rollback and has
+ * no settings UI, so it is an internal escape hatch, not a user choice.
+ *
+ * REMOVAL CONDITION: delete this module and its call sites once
+ * `hiddenDeliveryDroppedChars` (already reported via
+ * getHiddenRendererPtyDeliveryDebug, surfaced in the freeze diagnostics) has
+ * stayed at zero across released versions — non-zero can only mean a profile
+ * re-enabled the switch, since the default no longer drops. Deleting it also
+ * has to unpick the query-authority coupling in
+ * terminal-model-query-authority.ts, which ANDs this switch. Do NOT delete the
+ * general restore pipeline with it: renderer backlog overflow and main's
+ * pending-delivery cap discard bytes independently of this gate and still need
+ * recovery.
  */
 import type { GlobalSettings } from '../../shared/types'