From 995cda7f4e597ae9970ece8bf8a04d3b6a667e3e Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 15 Aug 2026 03:04:36 -0700
Subject: [PATCH] docs(ssh): make the parking kill switch's reach over the
 reconnect repaint deliberate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review flagged that terminalSshViewParking silently disables the full-screen
reconnect repaint, since both go through the same model probe, and that nothing
said so.

Keeping the coupling and documenting it rather than threading a reason through.
The switch is the kill for painting an SSH pane from main's model at all, and a
reconnect does exactly that; off should restore the relay-tail behavior that
predates the machinery, which is what an escape hatch is for. That matters more
than usual here: this repaint is new and review already found one case where it
was worse than the bug, so a way to turn it off in the field is worth its cost —
a user who disables parking also loses the reconnect repaint.

The alternative is worse than it looks anyway: the probe memo is keyed on ptyId
and shared with the park path, so a per-call reason would be reused by whichever
path created it first.
---
 .../terminal-pane/ssh-reattach-model-restore.ts        | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/renderer/src/components/terminal-pane/ssh-reattach-model-restore.ts b/src/renderer/src/components/terminal-pane/ssh-reattach-model-restore.ts
index 09f262fd763..fce84ea35e7 100644
--- a/src/renderer/src/components/terminal-pane/ssh-reattach-model-restore.ts
+++ b/src/renderer/src/components/terminal-pane/ssh-reattach-model-restore.ts
@@ -114,7 +114,15 @@ export function sshReconnectPaintsFromModel(args: {
   return !args.altFrameWouldBeSkipped && lastAlternateScreenTransition(args.replay) !== 'exited'
 }
 
-/** Skip the snapshot fetch entirely when the paint could never use it. */
+/**
+ * Skip the snapshot fetch entirely when the paint could never use it.
+ *
+ * DELIBERATE that terminalSshViewParking gates the reconnect repaint too, not just parking: it is
+ * the kill switch for painting an SSH pane from main's model at all, and a reconnect does exactly
+ * that from the same probe. Off means every SSH reattach degrades to the relay tail — the behavior
+ * that predates this machinery, which is what an escape hatch should restore. The cost is that a
+ * user who disables parking also loses the full-screen reconnect repaint.
+ */
 export function shouldFetchSshReattachModelSnapshot(args: {
   ptyId: string
   sshParkingEnabled: boolean