From 6d4065cae5406f25d9d9e24e7e8a257f2e17eb5a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 7 Jun 2026 09:49:03 -0700
Subject: [PATCH] Measure hidden PTY restore latency (#4806)

---
 .../summarize-terminal-perf-report.mjs        |  1 +
 ...icial-opencode-hidden-pressure-scenario.ts | 37 +++++++++++++++----
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/config/scripts/summarize-terminal-perf-report.mjs b/config/scripts/summarize-terminal-perf-report.mjs
index 33b43145d..0800ce446 100644
--- a/config/scripts/summarize-terminal-perf-report.mjs
+++ b/config/scripts/summarize-terminal-perf-report.mjs
@@ -74,6 +74,7 @@ function printMarkdownTable(rows) {
     ['Frames', 'frames'],
     ['Median', 'median'],
     ['Worst', 'worst'],
+    ['Restore', 'restore'],
     ['Max Drift', 'maxTimerDrift'],
     ['Hidden Skips', 'hiddenSkips'],
     ['Hidden Chars', 'hiddenSkippedChars'],
diff --git a/tests/e2e/artificial-opencode-hidden-pressure-scenario.ts b/tests/e2e/artificial-opencode-hidden-pressure-scenario.ts
index 141789d2e..a9c6de257 100644
--- a/tests/e2e/artificial-opencode-hidden-pressure-scenario.ts
+++ b/tests/e2e/artificial-opencode-hidden-pressure-scenario.ts
@@ -201,13 +201,20 @@ export async function runHiddenRealPtyPressureScenario<
     expect(measurement.maxTimerDriftMs).toBeLessThan(150)
 
     await deps.releaseTerminalAckGate(orcaPage)
-    await switchToWorktree(orcaPage, secondWorktreeId)
-    await expect
-      .poll(() => getTerminalContent(orcaPage, 20_000), {
-        timeout: 20_000,
-        message: 'Hidden PTY output was not restored from main buffer on return'
-      })
-      .toContain(`OPENCODE_PRESSURE_DONE_${runId}_`)
+    const restoreLatencyMs = await measureHiddenOutputRestoreLatency(
+      orcaPage,
+      secondWorktreeId,
+      runId
+    )
+    testInfo.annotations.push({
+      type: 'opencode-hidden-real-pty-restore',
+      description: `panes=${hiddenPanes.length + 1} restore=${restoreLatencyMs.toFixed(
+        1
+      )}ms hiddenSkippedChars=${debug?.hiddenRendererSkippedChars ?? 0} mainPeakInFlightChars=${
+        mainPressure?.peakRendererInFlightChars ?? 0
+      } heldAckChars=${ackGate?.heldAckChars ?? 0}`
+    })
+    expect(restoreLatencyMs).toBeLessThan(1000)
   } finally {
     await cleanupHiddenPressureScenario({
       deps,
@@ -221,6 +228,22 @@ export async function runHiddenRealPtyPressureScenario<
   }
 }
 
+async function measureHiddenOutputRestoreLatency(
+  orcaPage: Page,
+  worktreeId: string,
+  runId: string
+): Promise<number> {
+  const restoreStart = performance.now()
+  await switchToWorktree(orcaPage, worktreeId)
+  await expect
+    .poll(() => getTerminalContent(orcaPage, 20_000), {
+      timeout: 20_000,
+      message: 'Hidden PTY output was not restored from main buffer on return'
+    })
+    .toContain(`OPENCODE_PRESSURE_DONE_${runId}_`)
+  return performance.now() - restoreStart
+}
+
 async function startHiddenPressureCommands({
   hiddenPanes,
   orcaPage,