feat(terminal): add Recover Terminal Display command (#1472) (#1473)

A terminal pane can go black while its shell keeps running, and no input
brings it back. SwiftTerm's Metal renderer refuses a frame when the frame
semaphore is held or no drawable exists; both paths set `pendingRedraw`
without submitting a command buffer, yet only that command buffer's
completion handler consumes the flag. The view then accepts input and PTY
output forever without presenting anything.

Pine cannot detect this from the outside — with the semaphore held, both
`setNeedsDisplay` and `drawMetalFrameNow()` re-enter the same refusal, and
there is no public "frame presented" signal. Rebuilding the renderer is the
only escape: it installs a fresh MTKView, semaphore, and drawable chain
while Terminal, the PTY, and the scrollback stay untouched.

Terminal ▸ Recover Terminal Display (⌘⌥R) rebuilds the renderer for the
active tab of every visible terminal pane, plus the quick terminal when it
is on screen. Background tabs are skipped — they are detached, so a rebuild
would cost a GPU round-trip for pixels nobody sees, and their own re-attach
already repaints them. The item is never disabled: the quick terminal lives
in its own window where `focusedProject` is nil, and gating on project
panes would leave exactly that surface unfixable.

Existing coverage missed this class entirely — `TerminalMetalRendererTests`
exercises only attachment-shaped events, and the UI-test harness launches
with `--disable-metal`.

The durable fix belongs upstream in SwiftTerm; it will be filed separately,
after which this command stays useful but no longer load-bearing.

Author: batonogov

Pine/Localizable.xcstrings

@@ -9750,6 +9750,66 @@
         }
       }
     },
+    "menu.recoverTerminalDisplay": {
+      "comment": "Menu item: rebuild the renderer of visible terminals that stopped presenting frames (#1472).",
+      "extractionState": "manual",
+      "localizations": {
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Terminal-Anzeige wiederherstellen"
+          }
+        },
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Recover Terminal Display"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Recuperar la visualización del terminal"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Restaurer l’affichage du terminal"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ターミナル表示を復元"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "터미널 화면 복구"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Recuperar exibição do terminal"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Восстановить отображение терминала"
+          }
+        },
+        "zh-Hans": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "恢复终端显示"
+          }
+        }
+      }
+    },
     "menu.toggleTerminalZoom": {
       "comment": "Menu item: toggle zoom-to-fullscreen of the focused terminal pane (#1115).",
       "extractionState": "manual",

Pine/MenuIcons.swift

@@ -57,6 +57,7 @@ nonisolated enum MenuIcons {
     static let newTerminalTab = "plus"
     static let sendToTerminal = "paperplane"
     static let maximizeTerminal = "arrow.up.left.and.arrow.down.right"
+    static let recoverTerminalDisplay = "arrow.triangle.2.circlepath"
 
     // MARK: - Tasks menu (issue #1009)
     static let tasks = "wrench.and.screwdriver"

Pine/PineApp.swift

@@ -35,6 +35,9 @@ struct PineApp: App {
                 toggleQuickTerminal: { [weak appDelegate] in
                     appDelegate?.quickTerminalCoordinator.toggle()
                 },
+                recoverQuickTerminalDisplay: { [weak appDelegate] in
+                    appDelegate?.quickTerminalCoordinator.recoverDisplay()
+                },
                 recentProjects: { [weak appDelegate] in
                     appDelegate?.registry.recentProjects ?? []
                 },

Pine/PineAppMenuCommands.swift

@@ -31,6 +31,10 @@ struct PineAppMenuCommands: Commands {
     /// accidentally starting another Sparkle runtime in hosted tests.
     let checkForUpdatesViewModel: CheckForUpdatesViewModel
     let toggleQuickTerminal: () -> Void
+    /// Recovers the quick terminal alongside the focused project's panes: the
+    /// panel is a separate window, so a stuck session there is unreachable
+    /// through `focusedProject`. Inert when the panel is hidden.
+    let recoverQuickTerminalDisplay: () -> Void
     /// Reads the app-scoped registry without coupling Commands back to the
     /// AppDelegate. The closure keeps hosted tests inert while preserving
     /// observation of `ProjectRegistry.recentProjects` in the menu body.
@@ -808,6 +812,27 @@ struct PineAppMenuCommands: Commands {
             }
             .keyboardShortcut(.return, modifiers: [.command, .option])
             .disabled(focusedProject?.hasTerminalPanes != true)
+
+            Divider()
+
+            // Escape hatch for a terminal that renders nothing while its shell
+            // keeps running: SwiftTerm's Metal renderer can drop into a state
+            // where every frame request is refused and no repaint recovers it,
+            // so this rebuilds the renderer itself (issue #1472).
+            //
+            // Deliberately never disabled. The quick terminal lives in its own
+            // window, where `focusedProject` is nil — gating on project panes
+            // would leave exactly the surface a user is staring at unfixable.
+            Button {
+                focusedProject?.terminal.recoverVisibleTerminalDisplays()
+                recoverQuickTerminalDisplay()
+            } label: {
+                Label(
+                    Strings.menuRecoverTerminalDisplay,
+                    systemImage: MenuIcons.recoverTerminalDisplay
+                )
+            }
+            .keyboardShortcut("r", modifiers: [.command, .option])
         }
 
         // MARK: - Tasks menu (issue #1009)

Pine/QuickTerminal/QuickTerminalController.swift

@@ -170,6 +170,18 @@ final class QuickTerminalController {
 
     // MARK: - Public
 
+    /// Rebuilds the quick terminal's presentation layer, recovering a session
+    /// stuck on a renderer that refuses every frame (see
+    /// `TerminalTab.recoverDisplay()`).
+    ///
+    /// Only while on screen: a hidden panel is detached, so a rebuild would be
+    /// discarded and the next `show()` repaints through the ordinary
+    /// attachment path anyway.
+    func recoverDisplay() {
+        guard isVisible else { return }
+        paneState.activeTab?.recoverDisplay()
+    }
+
     /// Shows the quick terminal if hidden, hides it if visible. Bound to the
     /// global hotkey and the menu command.
     func toggle() {

Pine/Strings.swift

@@ -2074,6 +2074,8 @@ enum Strings {
     static let menuFindInTerminal: LocalizedStringKey = "menu.findInTerminal"
     static let menuSendToTerminal: LocalizedStringKey = "menu.sendToTerminal"
     static let menuToggleTerminalZoom: LocalizedStringKey = "menu.toggleTerminalZoom"
+    static let menuRecoverTerminalDisplay: LocalizedStringKey =
+        "menu.recoverTerminalDisplay"
 
     static var terminalSearchPreviousTooltip: String {
         String(localized: "terminal.search.previousTooltip")

Pine/TerminalManager.swift

@@ -1096,6 +1096,27 @@ final class TerminalManager {
         }
     }
 
+    // MARK: - Display recovery
+
+    /// Rebuilds the presentation layer of every terminal the user can actually
+    /// see in this project, recovering panes stuck on a renderer that refuses
+    /// every frame (see `TerminalTab.recoverDisplay()`).
+    ///
+    /// Scoped to the active tab of each terminal pane rather than to
+    /// `allTerminalTabs`: a background tab is detached, so recovery there is a
+    /// no-op that would still pay a renderer rebuild, and its own re-attach
+    /// already repaints it. Every visible pane is covered rather than only the
+    /// focused one — the stuck pane is frequently not the one holding focus,
+    /// and a user reaching for this command should not have to guess which.
+    ///
+    /// A permanently invalidated manager owns no live PTYs worth repainting.
+    func recoverVisibleTerminalDisplays() {
+        guard !isPermanentlyInvalidated, let pm = paneManager else { return }
+        for state in pm.terminalStates.values {
+            state.activeTab?.recoverDisplay()
+        }
+    }
+
     // MARK: - Queries (delegate to PaneManager)
 
     var allTerminalTabs: [TerminalTab] {

Pine/TerminalSession.swift

@@ -383,6 +383,49 @@ final class PineTerminalView: LocalProcessTerminalView {
         }
     }
 
+    /// Rebuilds the presentation layer on explicit user request, recovering a
+    /// terminal whose renderer stopped presenting frames.
+    ///
+    /// SwiftTerm's Metal renderer re-requests a dropped frame only from the
+    /// completion handler of a *submitted* command buffer. Both refusal paths
+    /// in `MetalTerminalRenderer.draw(in:)` — a busy frame semaphore and a
+    /// missing drawable/render-pass descriptor — set the pending-redraw flag
+    /// without submitting anything, so nothing ever consumes it. The view then
+    /// keeps accepting input and PTY output while never presenting a frame,
+    /// and no invalidation from Pine recovers it: `setNeedsDisplay` and
+    /// `drawMetalFrameNow()` both re-enter the same refusal.
+    ///
+    /// Recreating the renderer is the only escape — it installs a fresh
+    /// `MTKView`, semaphore, and drawable chain while `Terminal`, the PTY, and
+    /// the scrollback stay untouched. CoreGraphics has no such trap, so a
+    /// repaint through the backend-aware bridge is both necessary and
+    /// sufficient there.
+    ///
+    /// No-op while detached: `viewDidMoveToWindow` rebuilds and repaints on
+    /// the next real attachment anyway.
+    func recoverRendererNow() {
+        guard window != nil else { return }
+
+        if isUsingMetalRenderer {
+            do {
+                try setUseMetal(false)
+                try setUseMetal(true)
+            } catch {
+                Logger.terminal.error(
+                    "SwiftTerm Metal renderer recreation during display recovery failed: \(String(describing: error), privacy: .public)"
+                )
+            }
+            if isUsingMetalRenderer {
+                // A freshly created CAMetalLayer can miss its first drawable
+                // exactly like one created on attach; reuse the same bounded
+                // retry batch instead of betting recovery on a single frame.
+                scheduleInitialMetalRedrawRetries()
+            }
+        }
+
+        requestRendererDisplay()
+    }
+
     /// Re-arms first-frame recovery when visible terminal content first
     /// changes, rather than relying solely on the earlier view-attachment
     /// window. This matters for shells whose startup takes longer than the
@@ -2372,6 +2415,27 @@ final class TerminalTab: Identifiable, Hashable {
         }
     }
 
+    /// User-invoked escape hatch for a terminal that renders nothing while its
+    /// shell is demonstrably alive (Terminal ▸ Recover Display).
+    ///
+    /// Unlike `refreshAfterReparent()`, this rebuilds the renderer itself
+    /// rather than only repainting: the failure it targets is a Metal
+    /// presentation chain that refuses every frame, where repainting re-enters
+    /// the same refusal (see `PineTerminalView.recoverRendererNow()`).
+    ///
+    /// SIGWINCH is raised unconditionally rather than only for the alternate
+    /// screen. A stuck renderer leaves Pine unable to tell whether the primary
+    /// buffer still matches what the child last drew, and the signal is
+    /// harmless to an ordinary shell — it simply reprints its prompt.
+    ///
+    /// A terminated tab keeps its scrollback and is still worth repainting,
+    /// but has no child to signal.
+    func recoverDisplay() {
+        (terminalView as? PineTerminalView)?.recoverRendererNow()
+        forceFullRedraw()
+        kickPTYWindowSize()
+    }
+
     /// Whether the shell process is still running.
     var isProcessRunning: Bool {
         !isTerminated && processStarted && terminalView.process.running

PineTests/PineAppMenuCommandsTests.swift

@@ -28,6 +28,7 @@ struct PineAppMenuCommandsTests {
                 checkForUpdatesAction: {}
             ),
             toggleQuickTerminal: {},
+            recoverQuickTerminalDisplay: {},
             recentProjects: { [] },
             showAgentInbox: {}
         )

PineTests/QuickTerminalTests.swift

@@ -175,6 +175,41 @@ struct QuickTerminalTests {
         #expect(coordinator.paneState.activeTab?.id == firstTabID)
     }
 
+    @Test("display recovery while hidden is a no-op")
+    func recoverDisplayWhileHiddenIsNoOp() throws {
+        // The panel is a separate window: the menu command fires at it
+        // unconditionally because `focusedProject` is nil while it holds focus.
+        // While hidden it is detached, so a rebuild would be discarded and the
+        // next `show()` repaints through the ordinary attachment path.
+        let fixture = try QuickTerminalControllerFixture()
+        defer { fixture.cleanUp() }
+        let coordinator = fixture.controller
+
+        coordinator.recoverDisplay()
+
+        #expect(coordinator.isVisible == false)
+        #expect(coordinator.paneState.terminalTabs.isEmpty)
+    }
+
+    @Test("display recovery while visible repaints the live session")
+    func recoverDisplayWhileVisibleRepaints() throws {
+        let fixture = try QuickTerminalControllerFixture()
+        defer { fixture.cleanUp() }
+        let coordinator = fixture.controller
+        coordinator.show()
+        let tab = try #require(coordinator.paneState.activeTab)
+        let view = try #require(tab.terminalView as? PineTerminalView)
+        var redrawRequests = 0
+        view.backendRedrawRequestObserver = { redrawRequests += 1 }
+
+        coordinator.recoverDisplay()
+
+        #expect(redrawRequests >= 1)
+        // Recovery repaints the session; it must never restart it.
+        #expect(coordinator.paneState.activeTab?.id == tab.id)
+        coordinator.hide()
+    }
+
     @Test("cwd resolves to most-recent project, else $HOME")
     func cwdFallbackChain() throws {
         let fixture = try QuickTerminalControllerFixture()