From 841c7882a88e3b64ac3bdcd53ba2bec55c4dbfa3 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 26 Jul 2026 17:58:23 -0700
Subject: [PATCH] docs(codex): correct two inaccurate comments on the pane
 input gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both were added by this PR onto the gate whose false positives silently kill a
pane's keyboard, so a wrong mental model here is expensive.

`tab.ptyId` does not name the pane that bound last: `updateTabPtyId` keeps the
first binder (`currentTabPtyId ?? nextPtyIds[0]`, "later split-pane spawns must
not steal it") and only `clearTabPtyId` demotes it to the last survivor. And a
keystroke on an unbound pane does not arm recovery against `tab.ptyId` —
`requestTerminalPaneRecovery` targets `ptyIdsByTabId[tabId][0]`, which diverges
from `tab.ptyId` in split tabs.

The reasoning the fixes rest on is unchanged: `tab.ptyId` holds *some sibling's*
id rather than this pane's, which is what makes it wrong to gate a bound pane on.
Comments only — no behavior change.
---
 .../src/components/terminal-pane/pty-connection.ts       | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 95c49d9d1d1..b2e56485fc1 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -828,16 +828,17 @@ function isCodexPaneStale(args: {
     return false
   }
   // Why: a bound pane's own record is the last word — its ptyId is exactly the
-  // shell its keystrokes reach. `tab.ptyId` names whichever pane bound last, so
-  // in a split tab consulting it would kill this pane's keyboard over a
-  // sibling's notice, with no prompt on screen once that sibling is answered.
+  // shell its keystrokes reach. `tab.ptyId` holds one sibling's id, not this
+  // pane's, so in a split tab consulting it would kill this pane's keyboard over
+  // that sibling's notice, with no prompt on screen once the sibling is answered.
   if (args.panePtyId) {
     return blocksCodexPaneInput(codexRestartNoticeByPtyId[args.panePtyId])
   }
 
   // Why: only an unbound pane needs the tab's persisted id. Both transports
   // refuse writes while their pty binding is null, so a keystroke here arms
-  // recovery, which reattaches to that id — the shell this pane is about to own.
+  // recovery — a coarser signal than a bound pane's own record, but the tab's id
+  // is the only evidence available of which shell this pane is about to own.
   const tab = (state.tabsByWorktree[args.worktreeId] ?? []).find((entry) => entry.id === args.tabId)
   if (tab?.ptyId && blocksCodexPaneInput(codexRestartNoticeByPtyId[tab.ptyId])) {
     return true