Bug: Application Crashes When Opening Terminal in Docker Environment

[malys]

Summary

When attempting to open a terminal, Claude Code Studio throws an uncaught exception because it assumes gnome-terminal is available.

This causes a server-side error and the action fails.

Environment

• Claude Code Studio: v7.x
• Docker deployment
• Linux container
• No desktop environment installed

Error

uncaughtException

Executable not found in $PATH: "gnome-terminal"


Stack trace:

Error: Executable not found in $PATH: "gnome-terminal"
    at spawn
    at openTerminal (/app/server.js:10865:9)

Current Behavior
User clicks "Open Terminal" (or a feature requiring terminal launch).
CCS attempts to execute:
gnome-terminal

Docker container does not contain a graphical desktop environment.
Exception is thrown:
Executable not found in $PATH: "gnome-terminal"

Operation fails.
Expected Behavior

CCS should detect the execution environment and adapt accordingly.

Possible behavior:

Desktop Linux
gnome-terminal


or

konsole


or

xterm

Docker / Headless Environment

Instead of launching a GUI terminal:

Open an integrated web terminal.
Open a terminal panel in CCS.
Execute commands directly in the existing container session.
Display a helpful message explaining that graphical terminals are unavailable.
Suggested Fix

Implement terminal detection logic:

1. Integrated CCS terminal
2. gnome-terminal
3. konsole
4. xterm
5. fallback error message


Before spawning:

which gnome-terminal


or equivalent.

Docker Compatibility

Since CCS is increasingly deployed in Docker, the application should not assume the presence of:

GNOME
X11
Wayland
Desktop terminal emulators
Additional Improvement

Allow configuration:

{
  "terminalCommand": "custom-command"
}


Examples:

Integrated Terminal (by default)
gnome-terminal
konsole
tmux
screen
custom

Impact
Terminal-related features fail in Docker.
Uncaught exceptions pollute logs.
Headless deployments are affected.
Self-hosted users encounter unnecessary errors.
Priority

Medium-High

Expected User Experience

When running in Docker, opening a terminal should either:

Use an integrated web terminal, or
Gracefully report that graphical terminals are unavailable,

instead of throwing an uncaught exception.

[Lexus2016]

Thanks for the spot-on report and the exact stack trace!

Confirmed: openTerminal in server.js (10865:9) and /api/sessions/:id/open-terminal (8770) were calling spawnProc inside a synchronous try/catch. Because Node's child_process.spawn returns synchronously and emits ENOENT asynchronously on the next tick, the try/catch never caught it, and the missing 'error' listener triggered an uncaughtException. Furthermore, in headless/Docker environments there is no $DISPLAY / $WAYLAND_DISPLAY to attach a GUI emulator to.

Fixed in #110:

1. Added isHeadless() and hasCommand() checks.
2. If running headless on Linux (no $DISPLAY or $WAYLAND_DISPLAY), graphical terminal spawning is skipped, and /api/sessions/:id/open-terminal safely returns { ok: false, command: fullCmd } so the UI copies the command to your clipboard.
3. Every spawned terminal candidate now has an explicit 'error' event listener, preventing unhandled exceptions.
4. Added test coverage in test/delegate-terminal.test.js.