TUI screen goes completely black when agent starts working (render loop silently stalls)

[AH64-dll]

Description

After pressing Enter to send a prompt to the agent, the entire TUI goes black while the agent is working. The process is still alive (keyboard input works, modals render correctly on top of the black screen). Switching to another terminal tab and back restores the display. This happens consistently (every session, every prompt), not intermittently.

OpenCode version: 1.18.3
Platform: Arch Linux
Terminal: (add your terminal info)

Steps to reproduce

1. Run opencode in any project
2. Enter any prompt and press Enter
3. As the agent starts working, the screen goes black
4. Switch to another terminal tab and back — display recovers
5. Prompt again → screen goes black again

Root cause

The bug is in the bundled @opentui/core CliRenderer render loop. A race condition in the frame scheduling mechanism causes the render loop to silently stop producing frames during bursts of requestRender() calls.

The race condition in detail

The renderer operates in idle mode (_isRunning = false), where frames are only produced on demand via requestRender(). The flow is:

1. User presses Enter → burst of events → multiple requestRender() calls
2. First requestRender() passes the guards and calls activateFrame() → loop()
3. loop() sets this.rendering = true
4. During loop(), subsequent requestRender() calls hit the this.rendering guard (line 1516) and only set this.immediateRerenderRequested = true
5. loop() finishes, reads immediateRerenderRequested (line 4478), schedules another loop via setTimeout, and clears the flag (line 4481)
6. RACE: Between line 4481 (flag cleared) and line 4516 (this.rendering = false in finally), another requestRender() fires — this.rendering is still true → sets immediateRerenderRequested = true again
7. The finally block (lines 4515–4521) sets this.rendering = false and calls resolveIdleIfNeeded() — but does NOT check immediateRerenderRequested
8. Control returns to activateFrame(), which clears updateScheduled = false in its finally
9. The scheduled setTimeout from step 5 fires, calls loop() — if no new requestRender() arrives in time, _isRunning is false and immediateRerenderRequested is false, so the else branch (line 4486–4489) clears the timeout and stops scheduling
10. Render loop is dead. No more frames are produced. The screen stays black.

Why switching tabs fixes it

Switching terminal tabs sends SIGWINCH, which triggers handleResize() → requestRender(), which wakes up the dead loop.

Code references

All line numbers refer to @opentui/core packages/core/src/renderer.ts v0.4.5:

• requestRender() (lines 1491–1534): early-return at line 1516 when this.rendering is true, only sets this.immediateRerenderRequested = true
• loop() scheduling decision (lines 4478–4489): reads immediateRerenderRequested at line 4478, clears it at line 4481 — but a request arriving between 4481 and the finally is lost
• loop() finally block (lines 4515–4521): sets this.rendering = false but does NOT re-check immediateRerenderRequested
• activateFrame() (lines 1536–1548): clears updateScheduled = false in its finally — another window where requestRender() is silently dropped (guarded by !this.updateScheduled at line 1521)

Proposed fix

Based on upstream PR anomalyco/opentui#1086 (which was closed without merging — re-submission needed):

In loop()'s finally block, re-check immediateRerenderRequested and re-issue via setImmediate:

} finally {
  this.rendering = false
  if (this._destroyPending) {
    this.finalizeDestroy()
  } else if (this.immediateRerenderRequested) {
    this.immediateRerenderRequested = false
    setImmediate(() => {
      if (!this._isDestroyed) this.requestRender()
    })
  }
  this.resolveIdleIfNeeded()
}

setImmediate (not process.nextTick) is needed because activateFrame() keeps updateScheduled = true until its own finally after loop() returns. process.nextTick fires before microtasks resume — before activateFrame's finally — so requestRender() would be blocked by the !updateScheduled guard at line 1521.

Upstream issue

This is a re-report of the upstream opentui issue:

• opentui issue tweak: keep completion options open when trigger is still present #789: "Render loop silently stalls when rendering flag blocks requestRender during event burst" — still open
• opentui PR type 'reasoning' was provided without its required following item #1086: Proposed fix — closed without merging

The fix needs to be applied in @opentui/core, released, and then pulled into the opencode build. Currently opencode v1.18.3 bundles @opentui/core v0.4.5 which has the bug.

Workarounds

• opencode spawn — runs backend in a separate process from TUI, may reduce the event burst pressure on the render loop
• Ctrl+P → "Toggle console" — triggers a re-render via the console overlay toggle
• Resize the terminal window — sends SIGWINCH, wakes the dead loop

Additional note

There is a related opentui issue anomalyco/opentui#1147 ("TextNodeRenderable.requestRender() silently drops renders when transiently detached") with an open fix PR anomalyco/opentui#1173. This could be a compounding factor, causing text content to freeze even when the render loop is technically alive. However, the primary symptom (entire screen black, not just text) matches the render loop stall described here.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• TUI hangs on black screen at boot (OpenTUI) since v1.17.0 — Ubuntu/Wayland, all terminals, no plugins #32361: TUI hangs on black screen (OpenTUI) — similar blank screen symptom, different trigger (startup vs. during agent work), same underlying renderer
• Possible regression in v1.17.10 on WSL: TUI shows black screen and no prompt can be entered #33887: TUI shows black screen regression on WSL — blank screen with no input possible
• TUI freezes on Debian 13 x86_64 / XFCE / X11 — blank screen, only kill -9 works #35494: TUI freezes with blank screen (Debian) — render loop fires but produces zero output, similar stall behavior

If your issue is specifically triggered during agent work (not at startup), it may be a distinct race condition as you've described. But linking these for cross-reference may help track down a shared root cause.

[AH64-dll]

Thanks for the cross-references. I checked all three:

• TUI hangs on black screen at boot (OpenTUI) since v1.17.0 — Ubuntu/Wayland, all terminals, no plugins #32361 (black at boot, Wayland) and Possible regression in v1.17.10 on WSL: TUI shows black screen and no prompt can be entered #33887 (WSL regression at v1.17.10): These are startup hangs — the terminal-capability DCS query phase deadlocks before any render loop runs. Different root cause from the render-loop-stall described here.

• TUI freezes on Debian 13 x86_64 / XFCE / X11 — blank screen, only kill -9 works #35494 (Debian 13, renders zero output): Most likely related — the reporter notes "Render loop timer fires every 1s but produces zero output." This could share the same requestRender() → loop() → finally race documented here, triggered during the initial render burst at startup rather than during agent work. The workaround of switching terminal tabs (SIGWINCH → handleResize → requestRender()) might also work for that case.

All four issues trace back to the same fragile render-loop scheduling in @opentui/core CliRenderer — the gap between flag checks and the finally block where re-render requests are silently dropped.

[AH64-dll]

Fix PRs are up:

• opentui PR AI_APICallError: messages.1.content.2: tool_use ids must be unique #1279 (the fix itself): fix(renderer): prevent render loop stall by re-checking immediateRerenderRequested in loop() finally block opentui#1279
• opencode PR chore: bump @opentui/core to fix render loop stall (opentui#1279) #37805 (bump dependency to pick up the fix): chore: bump @opentui/core to fix render loop stall (opentui#1279) #37805

To unblock yourself in the meantime, you can:

npm install github:AH64-dll/opentui#8989f078747116b42dda6af1fe1549e9de1e5cc8

or apply the one-line fix manually to node_modules/@opentui/core/renderer.js:

In the loop() function, find the finally block (around line 4500) and change:

} finally {
  this.rendering = false
  if (this._destroyPending) {
    this.finalizeDestroy()
  }
  this.resolveIdleIfNeeded()
}

to:

} finally {
  this.rendering = false
  if (this._destroyPending) {
    this.finalizeDestroy()
  } else if (this.immediateRerenderRequested) {
    this.immediateRerenderRequested = false
    setImmediate(() => {
      if (!this._isDestroyed) this.requestRender()
    })
  }
  this.resolveIdleIfNeeded()
}