Default to native process driver, deprecate GNU Screen

GNU Screen is no longer required. The native driver handles PTY
allocation, ANSI passthrough, and UTF-8 directly via Symfony Process
with soloterm/screen parsing all ANSI sequences.

The screen driver remains available for one release cycle with
deprecation warnings logged when explicitly selected via
SOLO_PROCESS_DRIVER=screen or SOLO_USE_SCREEN=true.

Also adds unhandled ANSI sequence logging via Screen's
reportUnhandledSequencesVia() to surface edge cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aarondfrancis

CHANGELOG.md

@@ -11,12 +11,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added configurable process drivers via `solo.process_driver` (`screen` or `native`) with backward-compatible fallback to `solo.use_screen`.
 - Added regression coverage for dashboard rendering behavior, diff-render cursor anchoring, renderer reuse, process-driver command wrapping, and shutdown signaling paths.
+- Added unhandled ANSI sequence logging to surface edge cases in command output.
 
 ### Changed
 
+- Changed the default process driver from `screen` to `native`. GNU Screen is no longer required. Solo now uses PTY mode directly via Symfony Process, with `soloterm/screen` handling all ANSI parsing.
 - Updated dashboard rendering to prefer screen-diff output when available while preserving string-renderer fallback behavior.
 - Upgraded `soloterm/screen` to include the upstream `toCellBuffer()` ANSI decode fix and removed Solo's temporary local shim.
 
+### Deprecated
+
+- Deprecated the `screen` process driver. It will be removed in a future release. Users who explicitly set `SOLO_PROCESS_DRIVER=screen` or `SOLO_USE_SCREEN=true` will see a deprecation warning in the log.
+
 ### Fixed
 
 - Fixed a frame composition bug that could scroll away the first row, causing the tab strip to disappear or appear incomplete.

config/solo.php

@@ -65,18 +65,18 @@
      * Process driver used to execute commands.
      *
      * Supported values:
-     * - screen: Wrap commands with GNU Screen (default behavior)
-     * - native: Run directly in Solo's PTY with locale + stty bootstrap
+     * - native: Run directly in Solo's PTY (default, no external dependencies)
+     * - screen: Wrap commands with GNU Screen (deprecated, will be removed)
      *
-     * Leave unset to keep legacy `use_screen` behavior.
+     * You should not need to change this. The native driver handles PTY
+     * allocation, ANSI passthrough, and UTF-8 without GNU Screen.
      */
     'process_driver' => env('SOLO_PROCESS_DRIVER'),
 
     /**
-     * Backwards-compatible fallback for projects that still use SOLO_USE_SCREEN.
-     * Prefer `process_driver` for new setups.
+     * @deprecated Use `process_driver` instead. This option will be removed in a future release.
      */
-    'use_screen' => (bool) env('SOLO_USE_SCREEN', true),
+    'use_screen' => (bool) env('SOLO_USE_SCREEN', false),
 
     /*
     |--------------------------------------------------------------------------

docs/architecture.md

@@ -61,8 +61,8 @@ Each command runs as a subprocess managed by the `ManagesProcess` trait.
 
 When a command starts:
 
-1. A new process is spawned with `proc_open()`
-2. If GNU Screen is available, the command is wrapped for proper PTY handling
+1. A new process is spawned with `proc_open()` using PTY mode
+2. The command runs in a login shell with locale and terminal size bootstrap
 3. Non-blocking I/O is configured for output collection
 
 ### Output Collection
@@ -132,26 +132,6 @@ public function hasNewOutput(): bool
 
 This reduces terminal I/O by ~99.5% for typical workloads.
 
-## GNU Screen Wrapper
-
-Solo wraps commands in GNU Screen for:
-
-- **PTY allocation** - Proper terminal emulation
-- **ANSI rendering** - Better color and formatting support
-- **Size handling** - Correct terminal dimensions
-
-The wrapper command:
-
-```bash
-screen -U -q sh -c "your-command"
-```
-
-Disable if Screen isn't available:
-
-```env
-SOLO_USE_SCREEN=false
-```
-
 ## Key Components
 
 ### Dashboard

docs/configuration.md

@@ -59,13 +59,6 @@ return [
         'Queue' => Command::from('php artisan queue:work')->lazy(),
     ],
 
-    /*
-    |--------------------------------------------------------------------------
-    | GNU Screen
-    |--------------------------------------------------------------------------
-    */
-    'use_screen' => (bool) env('SOLO_USE_SCREEN', true),
-
     /*
     |--------------------------------------------------------------------------
     | Dump Server
@@ -126,14 +119,6 @@ Available keybinding presets. Add your own custom keybinding classes here. See [
 
 The commands that appear as tabs in Solo. The array key becomes the tab name. See [Commands](commands) for all the ways to define commands.
 
-### use_screen
-
-```php
-'use_screen' => (bool) env('SOLO_USE_SCREEN', true),
-```
-
-Whether to use GNU Screen as a wrapper for commands. Screen provides proper PTY allocation and better ANSI rendering. Disable if Screen isn't installed or causes issues.
-
 ### dump_server_host
 
 ```php
@@ -153,9 +138,6 @@ SOLO_THEME=dark
 # Keybindings
 SOLO_KEYBINDING=vim
 
-# GNU Screen
-SOLO_USE_SCREEN=true
-
 # Dump server
 SOLO_DUMP_SERVER_HOST=tcp://127.0.0.1:9984
 ```

docs/installation.md

@@ -18,30 +18,6 @@ description: How to install and set up Solo in your Laravel application.
 
 Solo requires `ext-pcntl` and `ext-posix` for process management. These extensions are not available on Windows. If you're on Windows, consider using WSL2.
 
-### GNU Screen (Recommended)
-
-Solo works best with GNU Screen 5.0.0 or higher installed. Screen provides proper PTY allocation and improves ANSI rendering.
-
-Check if Screen is installed:
-
-```bash
-screen --version
-```
-
-Install on macOS:
-
-```bash
-brew install screen
-```
-
-Install on Ubuntu/Debian:
-
-```bash
-sudo apt install screen
-```
-
-Solo will work without Screen, but you may experience degraded output in some commands.
-
 ## Install via Composer
 
 Install Solo as a development dependency:
@@ -109,7 +85,7 @@ Solo respects these environment variables:
 |----------|---------|-------------|
 | `SOLO_THEME` | `dark` | Theme to use (light or dark) |
 | `SOLO_KEYBINDING` | `default` | Keybinding preset |
-| `SOLO_USE_SCREEN` | `true` | Use GNU Screen wrapper |
+| `SOLO_PROCESS_DRIVER` | `native` | Process driver (`native` or `screen`) |
 | `SOLO_DUMP_SERVER_HOST` | `tcp://127.0.0.1:9984` | Dump server address |
 
 ## Troubleshooting
@@ -129,21 +105,6 @@ composer dump-autoload
 2. Check if the command has an `--ansi` or `--colors=always` option
 3. Verify the command writes to STDOUT
 
-### Screen-related issues
-
-If you experience rendering problems:
-
-```bash
-# Disable Screen wrapper
-SOLO_USE_SCREEN=false php artisan solo
-```
-
-Or in your `.env`:
-
-```env
-SOLO_USE_SCREEN=false
-```
-
 ### Port conflicts
 
 If the dump server port is in use:

src/Commands/Command.php

@@ -12,6 +12,7 @@
 use Chewie\Concerns\Ticks;
 use Chewie\Contracts\Loopable;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Str;
 use SoloTerm\Screen\Screen;
 use SoloTerm\Solo\Commands\Concerns\ManagesProcess;
@@ -424,6 +425,13 @@ protected function makeNewScreen(): Screen
             height: $this->scrollPaneHeight()
         );
 
+        $screen->reportUnhandledSequencesVia(function (string $sequence) {
+            Log::debug('Solo: Unhandled ANSI sequence in command output', [
+                'command' => $this->name,
+                'sequence' => addcslashes($sequence, "\x00..\x1f\x7f..\xff"),
+            ]);
+        });
+
         return $screen->respondToQueriesVia(function ($output) {
             $this->input->write($output);
         });

src/Commands/Concerns/ManagesProcess.php

@@ -135,6 +135,11 @@ trait ManagesProcess
      */
     protected static bool $invokedProcessPropertyUnavailable = false;
 
+    /**
+     * Whether the screen driver deprecation warning has already been logged.
+     */
+    protected static bool $screenDeprecationWarned = false;
+
     public function createPendingProcess(): PendingProcess
     {
         $this->input ??= new InputStream;
@@ -274,13 +279,26 @@ protected function processDriver(): string
                 static::PROCESS_DRIVER_NATIVE,
                 static::PROCESS_DRIVER_LEGACY,
             ], true)) {
+                if ($normalized === static::PROCESS_DRIVER_SCREEN && !static::$screenDeprecationWarned) {
+                    static::$screenDeprecationWarned = true;
+                    Log::warning('Solo: The "screen" process driver is deprecated and will be removed in a future release. Remove SOLO_PROCESS_DRIVER from your environment to use the native driver.');
+                }
+
                 return $normalized;
             }
         }
 
-        return (bool) Config::get('solo.use_screen', true)
-            ? static::PROCESS_DRIVER_SCREEN
-            : static::PROCESS_DRIVER_LEGACY;
+        // Legacy fallback: SOLO_USE_SCREEN=true selects the (deprecated) screen driver.
+        if ((bool) Config::get('solo.use_screen', false)) {
+            if (!static::$screenDeprecationWarned) {
+                static::$screenDeprecationWarned = true;
+                Log::warning('Solo: The SOLO_USE_SCREEN option is deprecated. GNU Screen is no longer required. Remove SOLO_USE_SCREEN from your environment.');
+            }
+
+            return static::PROCESS_DRIVER_SCREEN;
+        }
+
+        return static::PROCESS_DRIVER_NATIVE;
     }
 
     protected function localeEnvironmentVariables(): string

src/Console/Commands/Solo.php

@@ -35,6 +35,8 @@ protected function checkScreenVersion(): void
             return;
         }
 
+        Log::warning('Solo: The GNU Screen process driver is deprecated and will be removed in a future release. The native driver is now the default and does not require GNU Screen.');
+
         $process = new Process(['screen', '-v']);
         $process->run();
 
@@ -61,7 +63,7 @@ protected function usesScreenDriver(): bool
             return strtolower(trim($driver)) === 'screen';
         }
 
-        return (bool) Config::get('solo.use_screen', true);
+        return (bool) Config::get('solo.use_screen', false);
     }
 
     protected function monitor(): void

tests/Unit/ManagesProcessTest.php

@@ -12,7 +12,7 @@ class ManagesProcessTest extends Base
     public function commands_are_not_tokenized_when_screen_is_disabled(): void
     {
         config()->set('solo.use_screen', false);
-        config()->set('solo.process_driver', null);
+        config()->set('solo.process_driver', 'legacy');
 
         $command = new class(name: 'Tests', command: 'APP_ENV=testing php artisan test --filter="User Test"') extends Command
         {
@@ -347,6 +347,8 @@ protected function sendTermSignals(bool $force = false): void
     #[Test]
     public function screen_shutdown_refreshes_stay_eager_until_children_have_been_discovered(): void
     {
+        config()->set('solo.process_driver', 'screen');
+
         $command = new class extends Command
         {
             public float $fakeNowMs = 0;

tests/Unit/SoloCommandTest.php

@@ -52,7 +52,13 @@ public function runScreenVersionCheckForTest(): void
             $command->runScreenVersionCheckForTest();
         });
 
+        $deprecationWarning = [
+            'level' => 'warning',
+            'message' => 'Solo: The GNU Screen process driver is deprecated and will be removed in a future release. The native driver is now the default and does not require GNU Screen.',
+        ];
+
         $this->assertSame([
+            $deprecationWarning,
             [
                 'level' => 'error',
                 'message' => 'The installed version of `screen` (4.9.0) is outdated. Please upgrade to 5.0.0 or greater for best compatibility with Solo.',
@@ -82,7 +88,13 @@ public function runScreenVersionCheckForTest(): void
             $command->runScreenVersionCheckForTest();
         });
 
+        $deprecationWarning = [
+            'level' => 'warning',
+            'message' => 'Solo: The GNU Screen process driver is deprecated and will be removed in a future release. The native driver is now the default and does not require GNU Screen.',
+        ];
+
         $this->assertSame([
+            $deprecationWarning,
             [
                 'level' => 'error',
                 'message' => 'Unable to determine `screen` version. Make sure `screen` is installed.',