Skip to content

bug(opencode): an OpenCode Terminal pane that lost its server port hangs with no visible error #881

Closed

Description

@Juliusolsson05

What happens

An OpenCode Terminal pane whose TUI lost its server port hangs, and nothing tells the user.

  1. Agent Code launches the TUI with --hostname 127.0.0.1 --port <free>. The port comes from a loopback probe (opencode-terminal-headless allocateLoopbackPort), which releases it before the TUI binds.
  2. If another process takes it in that window, the TUI neither exits nor paints. This was observed in Stage 0 and recorded in packages/opencode-terminal-headless/testing/fixtures/live/port-conflict.json.
  3. The package does detect it: after the connect deadline it emits live-state { connected: false, reason: 'server-unreachable' }. The adapter forwards that as a transcript-diagnostic (src/providers/opencode/runtime/opencodeTerminalSession.ts).
  4. Nothing in the renderer acts on that diagnostic. The user sees a blank pane, with no status, no conditions and no error.

Why it is rare, and why it still matters

  • Rare. The review found no same-process collisions in 2,000 sequential and 500×10 concurrent allocations, because macOS hands out ports sequentially. Only another process can take the port. Since 13b9f5c in the package, the port is allocated after the opencode db path lookup, which shrinks the window to the TUI's boot time.
  • Still matters. When it does happen, the pane is dead with no explanation. Before this runtime, the TUI took no --port, so this failure mode is new.

Suggested fix

  • Surface it. Map server-unreachable (before the first live connection) to something the pane shows, e.g. a process-state error with a clear reason.
  • Or recover. The TUI is unusable in this state and cannot be re-pointed, so kill it and respawn once with a fresh port.
  • Test. Replay port-conflict.json through the adapter and assert the renderer sees the failure.

Acceptance

A TUI that never brings up its server leads to a visible pane error (or one automatic respawn), not a silent blank pane.

Refs #864

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions