Sidebar Terminal pane fails on Windows: Bun PTY (terminal: spawn option) not supported
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Environment
- OS: Windows 11 Pro 10.0.26100
- Bun: 1.3.5
- gstack: invoked via `~/.claude/skills/gstack/browse/dist/browse.exe`
- claude CLI: 2.1.119
## Symptom
After `$B connect`, sidebar Terminal pane shows:
```
Cannot start: 503 {"error":"terminal-agent not ready"}
```
Even after manually starting `terminal-agent.ts` and confirming it listens + writes `~/.gstack/terminal-port` + `~/.gstack/terminal-internal-token`, pressing **Start** in the sidebar still fails.
## Two stacked Windows-only issues
### 1. `cli.ts` doesn't reliably auto-spawn terminal-agent on Windows
`browse/src/cli.ts:891-915`:
```ts
spawnSync('pkill', ['-f', 'terminal-agent\.ts'], { stdio: 'ignore', timeout: 3000 });
// ...
const termProc = Bun.spawn(['bun', 'run', termAgentScript], { ... });
termProc.unref();
```
- `pkill` doesn't exist on Windows (try/catch swallows ENOENT, harmless).
- `Bun.spawn(['bun', ...])` from inside the **compiled** `browse.exe` produces a child that dies before writing its state files. Manual `bun run terminal-agent.ts` from a normal shell works fine — port listens, files appear.
### 2. `terminal-agent.ts` PTY spawn unconditionally fails on Windows
`browse/src/terminal-agent.ts:170-177`:
```ts
const proc = (Bun as any).spawn([claudePath, '--append-system-prompt', tabHint], {
terminal: { rows, cols, data(_t, chunk) { onData(chunk); } },
env,
});
```
Bun's `terminal:` option is Linux/macOS only. Verified:
```
$ bun -e 'Bun.spawn(["claude","--version"], { terminal: { rows:24, cols:80, data(){} } })'
ERR: terminal option is not supported on this platform
```
## Repro
1. On Windows, `~/.claude/skills/gstack/browse/dist/browse.exe connect`
2. Open sidebar in launched Chromium → Terminal pane
3. Press Start → 503 (or after manual terminal-agent restart, connection drops on first input)
## Suggested fix
Replace `terminal:` spawn option with a cross-platform PTY library on Windows:
- `@lydell/node-pty` (maintained fork, ConPTY support)
- or `node-pty` directly
- Platform detect: keep `Bun.spawn({terminal})` on Linux/macOS, `node-pty` on `win32`.
Side issue: `cli.ts:901` `pkill` should be platform-gated (`taskkill /F /IM` or process-registry on Windows), and the `Bun.spawn(['bun', ...])` reliability from inside the compiled exe on Windows needs investigation separately.
## Workaround
Run `browse connect` from WSL Ubuntu — Linux PTY path works. Trade-off: separate Chromium profile, requires bun + Playwright deps installed in WSL.
## Impact
Per `docs/designs/SIDEBAR_MESSAGE_FLOW.md`, the Terminal pane (live `claude` PTY) is the **primary** sidebar surface. Browser control + Activity feed still work on Windows. But the headline "AI in your sidebar" experience is unavailable to Windows-native users.
Contributor guide
Assessment
This issue has not been assessed yet.