stablyai / stablyai/orca

Headless/server terminal renderer constrains full-screen TUI width despite wide PTY size

Open
#8,396 2 comments 1 reaction 1 assignee Claimed by @OrcaWin View on GitHub
orca-remote-server
Dominant language
TypeScript
Stars
72.1k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

### Summary

When using Orca in `serve` / headless server mode, full-screen terminal TUIs such as OpenCode render with a visually constrained/narrow layout. The same OpenCode session over normal SSH uses the full terminal width correctly.

This appears to be specific to Orca headless/server terminal rendering, not OpenCode itself.

### Environment

- Orca version: `1.4.104`
- Mode: `orca serve`
- Host: Linux server
- Access methods tested:
- normal runtime pairing
- mobile pairing
- Terminal app tested:
- `opencode`

Serve command shape:

```bash
orca serve --port 6768 --pairing-address --json
```

Also tested with:

```bash
orca serve --port 6768 --pairing-address --mobile-pairing --json
```

### Expected behavior

Full-screen TUI apps should use the full visual terminal width, matching the PTY dimensions and matching behavior over SSH.

### Actual behavior

OpenCode renders narrower/boxed in Orca server/headless terminal, even when the PTY reports a wide size.

Plain shell output appears okay, but full-screen TUI rendering exposes the width/layout issue.

### Reproduction steps

1. Start Orca in headless/server mode:

```bash
orca serve --port 6768 --pairing-address --json
```

2. Pair using the web/runtime client.
3. Open a terminal in Orca.
4. Run:

```bash
stty size
opencode
```

5. Observe that OpenCode does not visually use the full available width.
6. Compare with SSH into the same server and run:

```bash
stty size
opencode
```

OpenCode uses the full terminal width correctly in SSH.

### Additional tests performed

Forced PTY width:

```bash
stty cols 180 rows 50
COLUMNS=180 LINES=50 opencode
```

This partially improves layout, but does not make it fully match SSH behavior.

Also tested wider values:

```bash
stty cols 220 rows 60
COLUMNS=220 LINES=60 opencode
```

Still visually constrained.

Checked live PTY size from outside. Orca/OpenCode PTY reports wide sizes such as `180x96`, so the underlying PTY dimensions appear wide enough.

### Mobile vs runtime pairing

Issue happens in both:

- `--mobile-pairing`
- normal runtime pairing

So it does not appear to be mobile-only.

### Renderer settings tested

Changed Orca terminal settings:

```json
"terminalFontSize": 12,
"terminalGpuAcceleration": "off",
"terminalLigatures": "off"
```

No visible change. Reverted to:

```json
"terminalFontSize": 14,
"terminalGpuAcceleration": "auto",
"terminalLigatures": "auto"
```

### Relevant environment difference

OpenCode under Orca server mode includes Orca-specific environment such as:

```text
TERM=xterm-256color
TERM_PROGRAM=Orca
DISPLAY=:99
OPENCODE_CONFIG_DIR=
ORCA_APP_EXECUTABLE=
ORCA_TERMINAL_HANDLE=...
```

SSH OpenCode does not have the Orca server/headless renderer path and renders correctly.

### Suspected cause

The PTY size appears correct, but the Orca headless/server terminal renderer seems to constrain or mis-measure the visual terminal grid for full-screen/alternate-screen TUIs.

Potential area:

- terminal renderer viewport measurement
- xterm/canvas sizing in headless/server mode
- resize propagation from server/client renderer to TUI apps
- alternate-screen rendering path

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.